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 nicht automatisch erfasst werden, müssen Sie Ihre Anwendung instrumentieren, um diese Daten zu erheben.

Sie können Ihre Anwendung so instrumentieren, dass anwendungsspezifische Informationen erfasst werden. Mit mehreren Open-Source-Instrumentierungs-Frameworks können Sie Messwerte, Protokolle und Traces aus Ihrer Anwendung erfassen und an jeden Anbieter senden, einschließlich Google Cloud. Wir empfehlen, zur Instrumentierung Ihrer Anwendung ein anbieterneutrales Open-Source-Instrumentierungsframework wie OpenTelemetry zu verwenden, anstatt anbieter- und produktspezifische APIs oder Clientbibliotheken.

Informationen zur Instrumentierung Ihrer Anwendungen mithilfe von anbieterunabhängigen Instrumentierungsframeworks finden Sie unter Instrumentierung und Beobachtbarkeit.

Anwendungen instrumentieren

Sie haben folgende Möglichkeiten, Ihre Anwendungen für die Erfassung von Trace-Daten zu instrumentieren:

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

Wenn Sie Google Cloud ausführen, müssen Sie in der Regel keine Authentifizierungsanmeldedaten für Ihre Anwendung oder Ihre Google Cloud-Projekt-ID in Ihrer Anwendung angeben. 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 die Google Kubernetes Engine verwenden oder die Identitätsföderation von Arbeitslasten für GKE aktivieren, müssen Sie Ihre Anwendung für die Verwendung der Identitätsföderation von Arbeitslasten für GKE 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 alle SPANs erfasst, ist es im Allgemeinen nicht möglich, eine Anfrage zu erzwingen, die End-to-End-Analyse zu durchlaufen, da jede Komponente in einer End-to-End-Anfrage eine eigene Entscheidung zur Stichprobenerhebung trifft. Sie können die Entscheidung jedoch beeinflussen, indem Sie dem Trace-Header das sampled-Flag mit der Einstellung true hinzufügen. 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.

Bei Downstream-Komponenten, deren Code Ihnen gehört, müssen Sie prüfen, ob Ihre Instrumentierungslogik das Flag sampled 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 übergeordnete Stichprobe berücksichtigt wird.

Google Cloud-Dienste, die Informationen zur Aufrufabfolge in Cloud Trace erfassen, akzeptieren das Flag für die übergeordnete Stichprobenerhebung in der Regel als Hinweis. Die meisten Dienste begrenzen die Stichprobenerhebung jedoch auch. 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. Wenn Sie die erforderlichen Konfigurationsschritte ausführen, fügt OpenTelemetry, die empfohlene Instrumentierungsbibliothek, diese Musterbeispiele automatisch hinzu. Weitere Informationen finden Sie unter Messwerte und Traces mithilfe von Beispielen korrelieren.

Projekt und Plattform konfigurieren

  1. Prüfen Sie, ob 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 Sicherheitsbeschränkungen deaktiviert, die von Ihrer Organisation festgelegt wurden. Informationen zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud-Umgebung entwickeln.

    Enable the Cloud Trace API.

    Enable the API

  2. 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 ist der Zugriffsbereich der Cloud Trace API in den Standardeinstellungen für den Zugriffsbereich enthalten:

      Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein. Wenn Sie beispielsweise mit der Google Cloud CLI einen GKE-Cluster erstellen und das Flag --scopes angeben, muss der Umfang trace.append enthalten. Im folgenden Befehl wird das Flag --scopes festgelegt:

      gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

    • Lokale und andere Ausführung: Wenn Ihre Anwendung außerhalb von Google Cloud ausgefü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 für die Suche nach den Anmeldedaten Ihrer Anwendung. Sie haben drei Möglichkeiten, diese Anmeldedaten anzugeben:

      • 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.