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 nicht automatisch erfasst werden, müssen Sie Ihre Anwendung so instrumentieren, dass diese Daten erfasst werden.
Sie können Ihre Anwendung so instrumentieren, dass sie anwendungsspezifische Informationen erfasst. Mit verschiedenen Open-Source-Instrumentierungs-Frameworks können Sie Messwerte, Logs und Traces aus Ihrer Anwendung erfassen und diese Daten an einen beliebigen Anbieter, einschließlich Google Cloud, senden. Zur Instrumentierung Ihrer Anwendung empfehlen wir die Verwendung eines anbieterneutralen Open-Source-Instrumentierungs-Frameworks wie OpenTelemetry anstelle von anbieter- und produktspezifischen APIs oder Clientbibliotheken.
Informationen zur Instrumentierung Ihrer Anwendungen mit anbieterneutralen Instrumentierungs-Frameworks finden Sie unter Instrumentierung und Beobachtbarkeit.
Anwendungen instrumentieren
Sie haben folgende Möglichkeiten, Ihre Anwendungen zum Erfassen von Trace-Daten zu instrumentieren:
Sie können OpenTelemetry und den zugehörigen Cloud Trace-Exporter für die folgenden Programmiersprachen verwenden:
OpenTelemetry SDK Beispiel Go SDK Beispiel für Trace und Messwerte für Go Java SDK Beispiel für Trace und Messwerte für Java Node.js-SDK Beispiel für Trace und Messwerte für Node.js Python SDK Beispiel für Trace und Messwerte für Python C++ SDK Trace-Beispiel für C++ Ruby SDK Weitere Informationen finden Sie in der Dokumentation zu OpenTelemetry. 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, jedoch nicht mithilfe von OTLP. Weitere Informationen finden Sie unter Ops-Agent und OTLP verwenden und Ops-Agent – Übersicht.
Sie können die Clientbibliotheken verwenden oder die Cloud Trace API direkt aufrufen, um Tracing-Daten an Cloud Trace zu senden. Wir empfehlen jedoch, OpenTelemetry zu verwenden, wenn Ihre Sprache von dieser Bibliothek unterstützt wird.
Sie können einen Zipkin-Server so konfigurieren, dass er Traces von Zipkin-Clients empfängt, und diese Traces dann zur Analyse an Cloud Trace weiterleiten. Informationen zu diesem Ansatz finden Sie unter Cloud Trace mit Zipkin verwenden.
Sie können Spring Boot-Anwendungen so konfigurieren, dass die erfassten Trace-Daten an Cloud Trace weitergeleitet werden. Weitere Informationen zu diesem Verfahren finden Sie unter Spring Cloud for Google Cloud: Cloud Trace.
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
In der Regel 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 Google Cloud ausgeführt werden. Bei einigen Sprachen müssen Sie Ihre Google Cloud-Projekt-ID angeben, auch wenn Sie Google Cloud ausführen. Wenn Sie den Autopilot-Modus für Google Kubernetes Engine verwenden oder Workload Identity aktivieren, müssen Sie außerdem Ihre Anwendung für die Verwendung von Workload Identity konfigurieren.
Wenn Sie außerhalb der Google Cloud ausgeführt werden, müssen Sie Authentifizierungsdaten für Ihre Anwendung angeben. Sie müssen außerdem 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 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 Stichprobenentscheidung trifft. Sie können die Entscheidung jedoch beeinflussen, indem Sie dem Trace-Header das Flag sampled
hinzufügen, wobei dieses Flag auf true
gesetzt ist. Diese Einstellung ist ein Hinweis für untergeordnete Komponenten, mit denen die Anfrage abgetastet werden soll.
Weitere Informationen zu Trace-Headern finden Sie unter Protokolle für die Kontextweitergabe.
Für nachgelagerte Komponenten, deren Code Sie besitzen, müssen Sie bestimmen, ob die Instrumentierungslogik das Flag sampled
berücksichtigt.
Wenn Sie beispielsweise OpenTelemetry für die Instrumentierung verwenden, können Sie mit dem ParentBased
-Sampler dafür sorgen, dass das Parent-sampled-Flag berücksichtigt wird.
Google Cloud-Dienste, die Trace-Informationen für Cloud Trace aufzeichnen, akzeptieren in der Regel das übergeordnete Stichproben-Flag als Hinweis. Die meisten Dienste verwenden jedoch auch das Ratenbegrenzungs-Sampling. Jeder Google Cloud-Dienst bestimmt, ob er Tracing unterstützt, wie das übergeordnete Stichproben-Flag verwendet wird und wie hoch die Ratenbegrenzung für die Stichprobenerhebung ist.
Projekt und Plattform konfigurieren
Achten Sie darauf, dass die Cloud Trace API aktiviert ist.
Standardmäßig ist für das Google Cloud-Projekt die Cloud Trace API aktiviert. Sie müssen nichts weiter tun. Möglicherweise wurde die API jedoch aufgrund von Sicherheitseinschränkungen Ihrer Organisation deaktiviert. Informationen zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud-Umgebung entwickeln.
Cloud Trace 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 Cloud ausgeführt wird, müssen Sie der Clientbibliothek keine Anmeldedaten zur Authentifizierung in Form eines Dienstkontos zur Verfügung stellen. Sie müssen jedoch dafür sorgen, dass für Ihre Google Cloud Platform der Zugriffsbereich der Cloud Trace API aktiviert ist.
Bei den folgenden Konfigurationen umfassen die Standardeinstellungen für den Zugriffsbereich den Zugriffsbereich der Cloud Trace API:
Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein. Wenn Sie beispielsweise die Google Cloud CLI zum Erstellen eines GKE-Cluster verwenden und das Flag
--scopes
angeben, muss der Bereichtrace.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 extern ausführen: Wenn Ihre Anwendung außerhalb von Google Cloud ausgeführt wird, müssen Sie der Clientbibliothek Anmeldedaten zur Authentifizierung in Form eines Dienstkontos zur Verfügung stellen. Dem Dienstkonto muss die Rolle des Cloud Trace-Agents (
roles/cloudtrace.agent
) zugewiesen sein. Informationen zu Rollen finden Sie unter Zugriff mit IAM steuern.Google Cloud-Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen für die Suche nach den Anmeldedaten Ihrer Anwendung. Sie können diese Anmeldedaten auf drei Arten angeben:
Führen Sie
gcloud auth application-default login
ausPlatzieren 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.
Beispiele für OpenTelemetry:
Beispiele für Clientbibliotheken: