Für Cloud Trace instrumentieren

Dieses Dokument enthält einen kurzen Überblick darüber, wie Sie Ihre Anwendung für Cloud Trace instrumentieren. Eine ausführliche Anleitung zur Einrichtung von Cloud Trace finden Sie auf den sprachspezifischen Einrichtungsseiten.

Cloud Trace bietet verteilte Tracing-Daten für Ihre Anwendungen. Nachdem Sie Ihre Anwendung instrumentiert haben, können Sie die Latenzdaten für eine einzelne Anfrage prüfen und die aggregierte Latenz für eine ganze Anwendung in der Cloud Trace-Konsole anzeigen lassen.

Wann Sie Ihre Anwendung instrumentieren müssen

Wenn Trace-Daten zur Validierung der Leistung oder zur Fehlerbehebung nicht automatisch erfasst werden, instrumentieren Sie Ihre Anwendung.

Instrumentieren Sie Ihre Anwendung, um bestimmte Informationen zu erfassen, mit denen Sie die Leistung Ihrer Anwendung besser verstehen und Fehler beheben können. Mit verschiedenen als Open Source veröffentlichten Instrumentierungs-Frameworks können Sie Log-, Messwert- und Trace Daten erfassen und diese Daten an einen beliebigen Anbieter senden, einschließlich Google Cloud. Für Ihre agentenbasierte Anwendungen können einige Frameworks Ihre Eingabeaufforderungen und Antworten erfassen oder Kontext weitergeben, der das Tracing einiger Remote Aufrufe von Google Cloud MCP-Servern ermöglicht.

Wir empfehlen, für die Instrumentierung Ihrer Anwendung ein anbieterneutrales als Open Source veröffentlichtes Instrumentierungs-Framework wie OpenTelemetryanstelle von anbieter- und produktspezifischen APIs oder Clientbibliotheken zu verwenden. Weitere Informationen zu diesen Frameworks finden Sie unter Instrumentierung und Beobachtbarkeit und Instrumentierungsansatz auswählen.

Anwendungen instrumentieren

Es gibt verschiedene Ansätze, mit denen Sie Ihre Anwendung instrumentieren können:

Empfohlen: Verwenden Sie OpenTelemetry, konfigurieren Sie Ihre Anwendung mit einem OTLP-Exporter, der Trace-Daten an einen Collector sendet, und konfigurieren Sie den Collector so, dass Trace-Daten mithilfe der Telemetry (OTLP) API an Ihr Google Cloud Projekt gesendet werden. Weitere Informationen zu unseren Empfehlungen, siehe Instrumentierungsansatz auswählen.
Verwenden Sie OpenTelemetry und konfigurieren Sie Ihre Anwendung mit einem OTLP-Exporter, der Ihre Trace-Daten mithilfe der Telemetry API an Ihr Google Cloud Projekt sendet.
Wenn Sie Anwendungen schreiben, die in Compute Engine ausgeführt werden, können Sie den Ops-Agent und den OTLP-Empfänger (OpenTelemetry Protocol) verwenden, um Traces und Messwerte aus Ihrer Anwendung zu erfassen. Der Ops-Agent kann auch Logs erfassen, aber nicht mit OTLP. Weitere Informationen finden Sie unter Ops-Agent und OTLP verwenden und Ops-Agent – Übersicht.
Rufen Sie entweder die Telemetry API oder die Cloud Trace API direkt auf.
Verwenden Sie Cloud Trace-Clientbibliotheken oder den Cloud Trace-Exporter für OpenTelemetry.
Konfigurieren Sie Spring Boot-Anwendungen so, dass die erfassten Trace-Daten an Cloud Trace weitergeleitet werden. Informationen zu dieser Vorgehensweise finden Sie unter Spring Cloud für Google Cloud: Cloud Trace.

In den von uns bereitgestellten Instrumentierungsbeispielen wird OpenTelemetry verwendet:

Beispiele, die einen Collector-basierten Export verwenden, finden Sie unter:
- Go
- Java
- Node.js
- Python
Diese Beispiele senden Trace-Daten an die Telemetry API.
Informationen zur Verwendung eines direkten Exports von Trace-Daten und zum Senden dieser Daten an die Telemetry API finden Sie unter Vom Trace-Exporter zum OTLP-Endpunkt migrieren.
Beispiele, die zeigen, wie Sie eine agentenbasierte Anwendung so konfigurieren, dass Eingabeaufforderungen und Antworten erfasst werden, finden Sie unter Generative KI-Anwendungen instrumentieren.

Informationen dazu, welche Remote-Google Cloud MCP-Server die Trace-Generierung unterstützen und wie Sie Ihre Anwendung so konfigurieren, dass diese Server Spans erstellen, finden Sie unter MCP-Aufrufe mit Trace untersieren.

Zeitpunkt der Erstellung von Spans

Die Cloud Trace-Clientbibliotheken verwalten normalerweise einen globalen Trace-Kontext, der Informationen über den aktuellen Span enthält, einschließlich der Trace-ID und ob der Trace als Stichprobe erfasst wird. Diese Bibliotheken erstellen in der Regel Spans für RPC-Grenzen. Möglicherweise müssen Sie jedoch Spans erstellen, wenn der Standard-Erstellungs-Algorithmus für Ihre Anforderungen nicht ausreicht.

Auf den aktuellen aktiven Span kann vom globalen Trace-Kontext zugegriffen werden, der manchmal in einem Tracer-Objekt verpackt ist. Sie können Informationen, die für Ihre Anwendung relevant sind, indem Sie benutzerdefinierte Annotationen und Tags zu vorhandenen Spans verwenden oder neue untergeordnete Spans mit eigenen Annotationen und Tags erstellen, um das Verhalten der Anwendung mit detaillierterer Genauigkeit zu verfolgen. Da der Kontext global ist, müssen Multi-Threaded-Anwendungen, die den Kontext aktualisieren, eine geeignete Isolation verwenden.

Wann Anmeldedaten zur Authentifizierung zur Verfügung gestellt werden müssen

Im Allgemeinen müssen Sie keine Anmeldedaten zur Authentifizierung für Ihre Anwendung angeben oder Ihre Google Cloud Projekt-ID in Ihrer Anwendung angeben, wenn Sie in ausgeführt werden Google Cloud. Bei einigen Sprachen, müssen Sie Ihre Google Cloud Projekt-ID auch dann angeben, wenn Sie in ausgeführt werden Google Cloud. Wenn Sie außerdem den Autopilot-Modus für Google Kubernetes Engine verwenden oder die Workload Identity-Föderation für GKE aktivieren, müssen Sie Ihre Anwendung so konfigurieren, dass die Workload Identity-Föderation für GKE verwendet wird.

Wenn Sie außerhalb von Google Cloudausgeführt werden, müssen Sie Anmeldedaten zur Authentifizierung für Ihre Anwendung angeben. Außerdem müssen Sie Ihre Google Cloud Projekt-ID in Ihrer Anwendung angeben.

Weitere Informationen finden Sie auf den sprachspezifischen Einrichtungsseiten.

Tracing einer Anfrage erzwingen

Sofern Ihre Anwendung nicht immer jeden Span als Stichprobe erfasst, ist es im Allgemeinen nicht möglich, das Tracing einer Anfrage von Anfang bis Ende zu erzwingen, da jede Komponente in einer End-to-End-Anfrage ihre eigene Entscheidung zur Stichprobenerfassung trifft. Sie können die Entscheidung jedoch beeinflussen, indem Sie dem Trace-Header ein sampled Flag hinzufügen und dieses Flag auf true setzen. Diese Einstellung ist ein Hinweis für untergeordnete Komponenten, die Anfrage als Stichprobe zu erfassen. Weitere Informationen zu Trace-Headern finden Sie unter Protokolle für die Kontextweitergabe.

Bei nachgelagerten Komponenten, deren Code Sie besitzen, müssen Sie festlegen, ob Ihre Instrumentierungslogik das sampled-Flag berücksichtigt. Wenn Sie beispielsweise OpenTelemetry für die Instrumentierung verwenden, können Sie den ParentBased Sampler verwenden, um sicherzustellen, dass das Flag für die Stichprobenerfassung des übergeordneten Elements berücksichtigt wird.

Google Cloud Dienste, die Tracing-Informationen in Cloud Trace aufzeichnen, akzeptieren das Flag für die Stichprobenerfassung des übergeordneten Elements in der Regel als Hinweis. Die meisten Dienste begrenzen jedoch auch die Stichprobenerfassung. Jeder Google Cloud Dienst bestimmt, ob er Tracing unterstützt, wie das Flag für die Stichprobenerfassung des übergeordneten Elements verwendet wird und wie die Ratenbegrenzung für die Stichprobenerfassung aussieht.

Messwert- und Trace-Daten korrelieren

Sie können Messwertdaten mit Verteilungswerten mit Traces korrelieren, indem Sie den Messwertdatenpunkten Beispiele anhängen. Wenn Sie die erforderlichen Konfigurationsschritte ausführen, fügt OpenTelemetry, die empfohlene Instrumentierungsbibliothek, diese Beispiele automatisch hinzu. Weitere Informationen finden Sie unter Messwerte und Traces mithilfe von Exemplars korrelieren.

Projekt und Plattform konfigurieren

Prüfen Sie, ob die Cloud Trace API aktiviert ist.

Standardmäßig ist für Projekte die Cloud Trace API aktiviert Sie müssen nichts weiter tun. Google Cloud Sicherheitsbeschränkungen, die von Ihrer Organisation definiert wurden, haben die API jedoch möglicherweise deaktiviert. Informationen zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud Umgebung entwickeln.

Aktivieren Sie die Cloud Trace API.
Rollen, die zum Aktivieren von APIs erforderlich sind
Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen.
API aktivieren
Konfigurieren Sie Ihre Plattform.

Sie können Cloud Trace in Google Cloud und auf anderen Plattformen verwenden.
- Google Cloud: Wenn Ihre Anwendung in Google Cloudausgeführt wird, müssen Sie für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in Form eines Dienstkontos angeben. Sie müssen jedoch dafür sorgen, dass für Ihre Google Cloud Plattform der Zugriffsbereich der Cloud Trace API aktiviert ist.
  
  Für die folgenden Konfigurationen ist der Zugriffsbereich der Cloud Trace API in den Standardeinstellungen für den Zugriffsbereich enthalten:
  - Compute Engine
  - Google Kubernetes Engine (GKE)
    
    Hinweis: Wenn Sie Autopilot verwenden oder die Workload Identity-Föderation für GKE für Ihren GKE-Cluster aktivieren, müssen Sie sicherstellen, dass Sie Ihre Anwendung für die Verwendung der Workload Identity-Föderation für GKE konfigurieren.
  - Flexible App Engine-Umgebung
  - App Engine-Standardumgebung
  - Cloud Run
  Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein. Wenn Sie beispielsweise die Google Cloud CLI verwenden, um einen GKE-Cluster zu erstellen, und das Flag --scopes angeben, muss der Bereich trace.append enthalten. Der folgende Befehl zeigt, wie das Flag --scopes festgelegt wird:
```
gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
```
- Lokal und an anderen Orten ausführen: Wenn Ihre Anwendung außerhalb von Google Cloudausgeführt wird, müssen Sie Anmeldedaten zur Authentifizierung in Form eines Dienstkontos für die Clientbibliothek angeben. Dem Dienstkonto muss die Rolle „Cloud Trace-Agent“ (roles/cloudtrace.agent) zugewiesen werden. Informationen zu Rollen finden Sie unter Zugriff mit IAM steuern.
  
  Google Cloud Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen (ADC) bei der Suche nach den Anmeldedaten Ihrer Anwendung. Sie können diese Anmeldedaten auf eine von drei Arten angeben:
  - Führen Sie gcloud auth application-default login aus.
  - Platzieren Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem. Im Folgenden sind die Standardpfade für Windows und Linux aufgeführt:
    - Windows: %APPDATA%/gcloud/application_default_credentials.json
    - Linux: $HOME/.config/gcloud/application_default_credentials.json
  - Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad zu Ihrem Dienstkonto fest:
    Linux/macOS
    
    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
    Windows
    
    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
    
    PowerShell:
    
    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Nächste Schritte

Detaillierte Konfigurationsinformationen, Beispiele und Links zu GitHub und anderen Open-Source-Repositories finden Sie auf der Einrichtungsseite für Ihre Sprache.

OpenTelemetry-Beispiele: