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 um diese Daten zu erheben.
Sie können Ihre Anwendung so instrumentieren, dass Anwendungsspezifische Informationen. Mehrere Open-Source- Instrumentierungs-Frameworks erfassen Messwerte, Logs und von Ihrer Anwendung abrufen und diese Daten an einen beliebigen Anbieter senden, einschließlich Google Cloud. Zur Instrumentierung Ihrer Anwendung empfehlen wir die Verwendung einer anbieterneutrales, quelloffenes Instrumentierungsframework wie OpenTelemetry statt anbieter- und produktspezifischen APIs oder Clientbibliotheken.
Informationen zur Instrumentierung Ihrer Anwendungen mithilfe der anbieterneutrale Instrumentierungs-Frameworks, siehe Instrumentierung und Beobachtbarkeit.
Anwendungen instrumentieren
Um Ihre Anwendungen für die Erfassung von Trace-Daten zu instrumentieren, haben Sie folgende Möglichkeiten: eines der folgenden Elemente:
Sie können OpenTelemetry und das zugehörige Cloud Trace-Exporter für die folgenden Programmiersprachen:
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 Traces 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 OpenTelemetry-Dokumentation. Wenn Sie Anwendungen entwickeln, die in der Compute Engine ausgeführt werden, können Sie mit dem Ops-Agent und dem OpenTelemetry Protocol-Empfänger (OTLP) Traces und Messwerte aus Ihrer Anwendung erfassen. Der Ops-Agent kann auch Logs, aber nicht mit 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 für den Empfang von Traces konfigurieren. von Zipkin-Clients aus und leiten diese Traces dann an Cloud Trace weiter. zu analysieren. 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. Informationen zu diesem Verfahren finden Sie unter Spring Cloud für 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 oder geben Sie Ihre Google Cloud-Projekt-ID in der wenn Sie Google Cloud nutzen. 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 oder wenn Sie die Identitätsföderation von Arbeitslasten für GKE aktivieren, müssen Sie konfigurieren Sie Ihre Anwendung für die Verwendung der Identitätsföderation von Arbeitslasten für GKE.
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 verwendet,
Im Allgemeinen ist es nicht möglich, das Tracing einer Anfrage von Anfang bis Ende zu erzwingen.
da jede Komponente in einer End-to-End-Anfrage ihren eigenen
Entscheidung über die Stichprobenerhebung. Sie können jedoch beeinflussen,
indem Sie dem Trace-Header ein sampled
-Flag hinzufügen,
wobei dieses Flag auf true
gesetzt ist. Diese Einstellung ist ein Hinweis für untergeordnete Komponenten.
um die Anfrage zu stichproben.
Weitere Informationen zu Trace-Headern finden Sie unter Protokolle für die Kontextweitergabe.
Bei Downstream-Komponenten, deren Code Ihnen gehört, müssen Sie prüfen, ob Ihre Instrumentierungslogik das Flag sampled
berücksichtigt.
Zum Beispiel bei der Verwendung von OpenTelemetry
Für die Instrumentierung kannst du den ParentBased
-Sampler verwenden
damit das Parent-Sampled-Flag berücksichtigt wird.
Google Cloud-Dienste, die Tracing-Informationen in Cloud Trace aufzeichnen akzeptieren in der Regel das Parent-Sampling-Flag als Hinweis. Die meisten Ratenbegrenzung für Stichproben. Jeder Google Cloud-Dienst bestimmt, ob er das Tracing unterstützt, wie das Flag für die übergeordnete Stichprobenerhebung verwendet wird und welche Ratenbegrenzung für die Stichprobenerhebung gilt.
Messwerte und Trace-Daten korrelieren
Sie können Messwertdaten mit Verteilungswerten mit Traces in Beziehung setzen, indem Sie den Messwertdatenpunkten Musterbeispiele zuordnen. Sofern Sie die erforderlichen Konfigurationsschritte abgeschlossen haben, OpenTelemetry, die empfohlene Instrumentierungsbibliothek, fügt diese Musterbeispiele automatisch hinzu. Weitere Informationen finden Sie unter Messwerte und Traces mithilfe von Musterbeispielen korrelieren.
Projekt und Plattform konfigurieren
Die Cloud Trace API muss aktiviert sein.
Standardmäßig ist für das Google Cloud-Projekt die Cloud Trace API aktiviert. Sie müssen nichts weiter tun. Die definierten Sicherheitseinschränkungen von Ihrer Organisation möglicherweise die API deaktiviert. Zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud-Umgebung entwickeln:
Enable the Cloud Trace API.
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 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.
Für die folgenden Konfigurationen sind die Standardeinstellungen für den Zugriffsbereich den Zugriffsbereich der Cloud Trace API einschließen:
Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein. Wenn Sie beispielsweise die Google Cloud CLI verwenden, um eine Wenn Sie das Flag
--scopes
angeben, Stellen Sie dann sicher, dass der Geltungsbereichtrace.append
umfasst. Im folgenden Befehl wird das Flag--scopes
festgelegt: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 des Google Cloud müssen Sie die Anmeldedaten zur Authentifizierung in in Form eines Dienstkontos an die Clientbibliothek gesendet. Dem Dienstkonto muss der Cloud Trace-Agent gewährt werden Rolle (
roles/cloudtrace.agent
). 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 in einem der drei Möglichkeiten:
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 Pfad zu Ihrem Dienstkonto: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
Ausführliche Konfigurationsinformationen, Beispiele und Links zu GitHub und anderen Open-Source-Repositories erhalten Sie auf der Einrichtungsseite für Ihre Sprache.
OpenTelemetry-Beispiele:
Beispiele für Clientbibliotheken: