Cloud Trace für Ruby einrichten

Sie können Cloud Trace für Ruby-Anwendungen mit der Cloud Trace-Bibliothek für Ruby aktivieren.

Bibliothek installieren

Installieren Sie Ruby 2.2 oder höher.
Fügen Sie das Stackdriver-Gem in Ihr Gemfile ein:
```
gem "stackdriver"
```
Installieren Sie das Gem mit Bundler:
```
bundle install
```

Bibliothek aktivieren

Rails

Wenn Sie Ruby on Rails verwenden, lädt Bundler automatisch die Bibliothek in Ihre Anwendung, wenn sie gestartet wird.

Andere (nicht Rails)

Andere rackbasierte Anwendungen können die Rack-Middleware aus der Bibliothek verwenden:

require "google/cloud/trace"

use Google::Cloud::Trace::Middleware

Weitere Informationen oder Angaben zum Melden von Problemen mit der Bibliothek finden Sie im Quellcode-Repository der Bibliothek.

Client konfigurieren

Sie können das Verhalten der Cloud Trace-Bibliothek für Ruby anpassen. Die Konfiguration der Bibliothek enthält eine Liste der Konfigurationsmöglichkeiten.

Benutzerdefinierten Trace-Span hinzufügen

Die Cloud Trace-Bibliothek für Ruby erstellt automatisch einen Trace-Eintrag für jede Anfrage, die Ihre Rack-Anwendung erhält. Sie können auch benutzerdefinierte Trace-Spans in jeder Anfrage hinzufügen:

Google::Cloud::Trace.in_span "my_task" do |_span|
  # Insert task

  Google::Cloud::Trace.in_span "my_subtask" do |subspan|
    # Insert subtask
  end
end

Plattform konfigurieren

Sie können Cloud Trace in Google Cloud und auf anderen Plattformen verwenden.

In Google Cloud ausführen

Wenn Ihre Anwendung in Google Cloud ausgeführt wird, müssen Sie für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in der Clientbibliothek angeben. Für die Google Cloud Platform muss jedoch der Zugriffsbereich der Cloud Trace API aktiviert sein.

Eine Liste der unterstützten Google Cloud-Umgebungen finden Sie unter Umgebungsunterstützung.

Für die folgenden Konfigurationen wird die Cloud Trace API über die Standardeinstellungen für den Zugriffsbereich aktiviert:

Flexible App Engine-Umgebung
App Engine-Standardumgebung
Google Kubernetes Engine (GKE)

Hinweis: Wenn Sie Autopilot verwenden oder Workload Identity für Ihren GKE-Cluster aktivieren, müssen Sie Ihre Anwendung für die Verwendung von Workload Identity konfigurieren.
Compute Engine
Cloud Run

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein:

Informationen zum Konfigurieren der Zugriffsbereiche für Ihre Umgebung mit der Google Cloud Console finden Sie unter Google Cloud-Projekt konfigurieren.
Geben Sie für gcloud-Nutzer mithilfe des Flags --scopes Zugriffsbereiche an und beziehen Sie den Zugriffsbereich der Cloud Trace API trace.append ein. So erstellen Sie beispielsweise einen GKE-Cluster, für den nur die Cloud Trace API aktiviert ist:
```
gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
```

Lokal und extern ausführen

Wenn Ihre Anwendung außerhalb von Google Cloud ausgeführt wird, müssen Sie Anmeldedaten zur Authentifizierung in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Rolle "Cloud Trace-Agent" enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Die Google Cloud-Clientbibliotheken für Ruby verwenden die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) bei der Suche nach den Anmeldedaten Ihrer Anwendung. Im folgenden Abschnitt wird beschrieben, wie Sie diese Anmeldedaten und die Google Cloud-Projekt-ID festlegen.

Google Cloud-Projekt-ID und Anmeldedaten festlegen

In diesem Abschnitt werden drei verschiedene Ansätze dafür beschrieben, wie Sie in der Ruby-Anwendung die Google Cloud-Projekt-ID, die Anmeldedaten für die Authentifizierung oder beides festlegen.

Umgebungsvariable

Wenn Sie die Google Cloud-Projekt-ID nicht explizit angeben, legt die Ruby-Bibliothek google-cloud automatisch fest, ob die Umgebungsvariable GOOGLE_CLOUD_PROJECT festgelegt ist. Wenn ja, verwendet die Bibliothek den Wert von GOOGLE_CLOUD_PROJECT als Google Cloud-Projekt-ID. Weitere Informationen finden Sie unter Authentifizierung.

Wie bereits beschrieben verwenden die Google Cloud-Clientbibliotheken die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) zur Suche nach den Anmeldedaten Ihrer Anwendung. Um diese Anmeldedaten anzugeben, können Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen:

Linux/macOS

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Windows

Befehlsfenster:

set GOOGLE_CLOUD_PROJECT=your-project-id
set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"
$env:GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Konfigurationsoberfläche von Ruby on Rails

Wenn Sie Ruby on Rails verwenden, können Sie die Parameter über die Konfigurationsoberfläche von Ruby on Rails angeben:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Trace specific parameters
  config.google_cloud.trace.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.trace.keyfile    = "/path/to/service-account.json"
end

Sie können eine gemeinsame Konfiguration für alle Stackdriver-Gems festlegen, wenn Sie Folgendes eingeben:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

Trace ist standardmäßig aktiviert, wenn Rails im Produktionsmodus ausgeführt wird. Fügen Sie Folgendes hinzu, um Trace im Entwicklungsmodus zu aktivieren:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_trace = true
end

Konfigurationsoberfläche für die Instrumentierung

Eine weitere Alternative für Ruby besteht darin, die Parameter über die Konfigurationsoberfläche bereitzustellen, wenn sie in anderen Rack-basierten Anwendungen verwendet werden:

require "google/cloud/trace"

Google::Cloud.configure do |config|
  # Stackdriver Trace specific parameters
  config.trace.project_id = "YOUR-PROJECT-ID"
  config.trace.keyfile    = "/path/to/service-account.json"
end