Für Cloud Trace instrumentieren

Sie können Ihre Anwendungen für Cloud Trace instrumentieren, um verteilte Tracing-Daten zu erfassen, die Latenz für einzelne Anfragen zu prüfen und die aggregierte Latenz für Ihre Dienste in der Trace-Konsole anzusehen.

Dieses Dokument bietet einen Überblick über Instrumentierungsansätze und Konfigurationsoptionen. Eine detaillierte Anleitung für bestimmte Programmiersprachen finden Sie auf den sprachspezifischen Einrichtungsseiten.

Wann Sie Ihre Anwendung instrumentieren müssen

Instrumentieren Sie Ihre Anwendung, um bestimmte Informationen zu erfassen, die Ihnen helfen, die Leistung zu verstehen und Fehler zu beheben. 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 agentischen Anwendungen können einige Frameworks Ihre Prompts 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öffentliches Instrumentierungs-Framework wie OpenTelemetry anstelle von anbieter- und produktspezifischen APIs oder Clientbibliotheken zu verwenden. Informationen zu diesen Frameworks finden Sie unter Beobachtbarkeit für Anwendungsentwickler und Instrumentierungsansatz auswählen.

Anwendungen instrumentieren

Es gibt mehrere 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 finden Sie unter 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 der 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 über 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.

  • Konfigurieren Sie Spring Boot-Anwendungen so, dass die von ihnen erfassten Trace-Daten an Cloud Trace weitergeleitet werden. Informationen zu diesem Verfahren finden Sie unter Spring Cloud für Google Cloud: Cloud Trace.

  • Verwenden Sie Cloud Trace-Clientbibliotheken oder den Cloud Trace-Exporter für OpenTelemetry.

Instrumentierungsbeispiele

Die von uns bereitgestellten Instrumentierungsbeispiele verwenden OpenTelemetry:

Benutzerdefinierte Spans erstellen

Mit OpenTelemetry und Clientbibliotheken können Sie zwar benutzerdefinierte Spans erstellen, aber Sie müssen sie möglicherweise nicht manuell erstellen, da diese Bibliotheken automatisch Spans an RPC-Grenzen erstellen.

Sie können auch Informationen hinzufügen, die für Ihre Anwendung relevant sind, indem Sie vorhandenen Spans benutzerdefinierte Annotationen und Tags hinzufügen. Alternativ können Sie neue untergeordnete Spans mit eigenen Annotationen und Tags erstellen, um das Verhalten der Anwendung mit einer feineren Granularität zu verfolgen.

Bibliotheken verwalten in der Regel einen globalen Trace-Kontext, der Informationen zum aktuellen Span enthält, einschließlich Trace-ID und Stichprobenstatus. Anwendungen können über den globalen Trace-Kontext auf den aktuellen Span zugreifen. Da der Kontext global ist, müssen Sie dafür sorgen, dass Multithread-Anwendungen den Kontext über Threads hinweg weitergeben, um genaue Trace-Daten zu erhalten.

Trace-Stichprobenerhebung erzwingen

Sie können die Stichprobenerhebung für Spans nicht erzwingen, da jede Komponente im Anfragepfad eine unabhängige Stichprobenentscheidung trifft. Sie können jedoch nachgelagerte Komponenten beeinflussen, indem Sie das Flag sampled im Trace-Header auf true setzen. Diese Einstellung ist ein Hinweis für untergeordnete Komponenten, die Anfrage zu erfassen. Weitere Informationen zu Trace-Headern finden Sie unter Protokolle für die Kontextweitergabe.

  • Ihre Anwendungen: Sie konfigurieren, wie die Instrumentierungslogik das Flag sampled berücksichtigt. Wenn Sie beispielsweise OpenTelemetry verwenden, können Sie den ParentBased-Sampler verwenden, um sicherzustellen, dass das Sampling-Flag des übergeordneten Elements berücksichtigt wird.

  • Google Cloud -Dienste: Jeder Dienst bestimmt seine eigene Tracing-Unterstützung. Im Allgemeinen akzeptieren Dienste das übergeordnete Stichproben-Flag als Hinweis, während sie ihre eigenen Stichprobenratenlimits erzwingen.

Messwerte und Traces mithilfe von Exemplars korrelieren

Sie können Messwertdaten mithilfe von Exemplars mit Traces korrelieren. Ein Exemplar ist eine repräsentative Beispielanfrage oder ein repräsentativer Span, der mit einer Messwertmessung verknüpft ist. Ein Beispiel kann beispielsweise einen Link zu einem Trace enthalten, mit dem Sie Ihre Messwert- und Trace-Daten korrelieren können. Ein OpenTelemetry-basiertes Beispiel finden Sie unter Messwerte und Traces mithilfe von Exemplars korrelieren.

In Dashboard-Diagrammen, in denen SQL-Abfrageergebnisse für Trace-Daten angezeigt werden, sehen Sie möglicherweise vom System generierte Exemplare. Diese Exemplare verknüpfen bestimmte Abfrageergebnisse direkt mit Traces. Weitere Informationen finden Sie unter Trace-Beispiele generieren und anzeigen.

Projekt und Plattform konfigurieren

In diesem Abschnitt werden die erforderlichen APIs und IAM-Rollen (Identity and Access Management) beschrieben und es wird erläutert, wie Sie Authentifizierungsdaten für Ihre Plattform konfigurieren.

APIs aktivieren

In Google Cloud -Projekten sind die Cloud Trace API und die Telemetry API standardmäßig aktiviert. Sie müssen nichts weiter tun. Von Ihrer Organisation definierte Sicherheitsbeschränkungen haben jedoch möglicherweise eine oder beide dieser APIs deaktiviert. Informationen zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud -Umgebung entwickeln.

Aktivieren Sie die Telemetry API und die Cloud Trace API, falls sie noch nicht aktiviert sind.

Erforderliche Rollen zum Aktivieren von APIs

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

APIs aktivieren

IAM-Rollen zuweisen

Die erforderlichen IAM-Rollen hängen davon ab, ob Sie Trace-Daten in der Google Cloud Console ansehen oder Trace-Daten in Ihr Projekt schreiben:

  • Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Trace-Nutzer (roles/cloudtrace.user) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen von Trace-Daten über die Google Cloud Console benötigen.

  • Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Trace-Agent (roles/cloudtrace.agent) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Schreiben von Trace-Daten mit der Cloud Trace API benötigen.

  • Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Telemetry Writer (roles/telemetry.writer) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Schreiben von Trace-Daten mit der Telemetry API benötigen.

Authentifizieren

In diesem Abschnitt wird beschrieben, wie Sie sich authentifizieren, wenn Ihre Anwendungen inGoogle Cloud oder an anderer Stelle ausgeführt werden.

Ausführen am Google Cloud

Wenn Ihre Anwendung in Google Cloudausgeführt wird, müssen Sie in der Regel keine Authentifizierungsdaten angeben. Einige Sprach-Clientbibliotheken erfordern jedoch die Projekt-ID, auch wenn sie auf Google Cloudgehostet werden.

Prüfen Sie, ob auf Ihrer Google Cloud -Plattform der Zugriffsbereich für die Cloud Trace API aktiviert ist. Bei den folgenden Konfigurationen enthalten die Standardeinstellungen für den Zugriffsbereich den Zugriffsbereich der Cloud Trace API:

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, müssen Sie darauf achten, dass der Zugriffsbereich der Cloud Trace API aktiviert ist. Wenn Sie beispielsweise die Google Cloud CLI zum Erstellen eines GKE-Cluster verwenden und das Flag --scopes angeben, muss der Bereich trace.append enthalten. Der folgende Befehl veranschaulicht das Festlegen des Flags --scopes:

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 Cloudausgeführt wird, müssen Sie der Clientbibliothek Authentifizierungsdaten bereitstellen. 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 (Application Default Credentials, ADC), um die Anmeldedaten Ihrer Anwendung zu finden. Sie können diese Anmeldedaten auf eine von drei Arten bereitstellen:

  • Führen Sie gcloud auth application-default login aus

  • Legen Sie die Dienstkontoschlüsseldatei in einem Standardpfad für Ihr Betriebssystem ab. 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