Cloud Trace für Ruby einrichten

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

Bibliothek installieren

  1. Installieren Sie Ruby 2.2 oder höher.

  2. Fügen Sie das Stackdriver-Gem in Ihr Gemfile ein:

    gem "stackdriver"
  3. 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

Ihre 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 keine Anmeldedaten zur Authentifizierung in Form eines Dienstkontos für die Clientbibliothek angeben. Sie müssen jedoch gewährleisten, dass auf Ihrer Google Cloud Platform der Zugriffsbereich der Cloud Trace API aktiviert ist.

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)

  • Compute Engine

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, müssen Sie gewährleisten, dass der Zugriffsbereich der Cloud Trace API aktiviert ist. Geben Sie für gcloud-Nutzer Zugriffsbereiche mit dem Flag --scopes an und fügen Sie den Cloud Trace API-Zugriffsbereich trace.append hinzu. 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 Authentifizierungsdaten in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Cloud Trace-Agent-Rolle enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Die Google Cloud-Clientbibliotheken für Ruby verwenden Standardanmeldedaten für Anwendungen, um die Anmeldedaten Ihrer Anwendung zu finden. 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 festlegen, ermittelt die Ruby-Bibliothek google-cloud automatisch, ob die Umgebungsvariable GOOGLE_CLOUD_PROJECT festgelegt ist. In diesem Fall 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 Standardanmeldedaten für Anwendungen, um die Anmeldedaten Ihrer Anwendung zu finden. Sie können diese Anmeldedaten angeben, indem 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"

Ruby on Rails-Konfigurationsoberfläche

Wenn Sie Ruby on Rails verwenden, besteht eine Alternative für Ruby darin, die Parameter über die Konfigurationsoberfläche bereitzustellen:

# 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

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

require "stackdriver"

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

Traces ansehen

Nach der Bereitstellung können Sie die Traces im Trace Viewer der Cloud Console anzeigen.

Trace-Anzeige öffnen

Fehlerbehebung

Informationen zur Behebung von Problemen mit Cloud Trace finden Sie auf der Seite zur Fehlerbehebung.

Ressourcen