Für Cloud Trace instrumentieren

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

In diesem Dokument finden Sie 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

Wenn keine Trace-Daten zum Validieren der Leistung oder zur Fehlerbehebung automatisch erfasst werden, müssen Sie Ihre Anwendung instrumentieren.

Instrumentieren Sie Ihre Anwendung, um bestimmte Informationen zu erfassen, mit denen Sie die Leistung nachvollziehen 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. Bei Ihren Agent-basierten Anwendungen können einige Frameworks Ihre Prompts und Antworten erfassen oder Kontext übergeben, der die Nachverfolgung 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 OpenTelemetry anstelle von anbieter- und produktspezifischen APIs oder Clientbibliotheken zu verwenden. Informationen zu diesen Frameworks finden Sie unter Instrumentierung und Beobachtbarkeit und Instrumentierungsansatz auswählen.

Anwendungen instrumentieren

Es gibt mehrere Möglichkeiten, Ihre Anwendung zu instrumentieren:

  • Empfohlen: Verwenden Sie OpenTelemetry, konfigurieren Sie Ihre Anwendung mit einem OTLP-Exporter, der Tracedaten an einen Collector sendet, und konfigurieren Sie den Collector so, dass Tracedaten mithilfe der Telemetry (OTLP) API an Ihr Google Cloud -Projekt gesendet werden. Weitere Informationen zu unseren Empfehlungen

  • Verwenden Sie OpenTelemetry und konfigurieren Sie Ihre Anwendung mit einem OTLP-Exporter, der Ihre Tracedaten 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 über OTLP. Weitere Informationen finden Sie unter Ops-Agent und OTLP verwenden und Übersicht über den Ops-Agent.

  • 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. Weitere Informationen zu diesem Verfahren finden Sie unter Spring Cloud for Google Cloud: Cloud Trace.

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

Instrumentierungsbeispiele

In den von uns bereitgestellten Instrumentierungsbeispielen wird OpenTelemetry verwendet:

  • Beispiele für den Collector-basierten Export finden Sie unter:

    In diesen Beispielen werden Messwert- und Trace-Daten, die dem OpenTelemetry Protocol (OTLP) entsprechen, mithilfe der Telemetry API an Ihr Projekt gesendet. In den Beispielen wird ein Google Cloud Exporter für Log-Daten verwendet.

  • 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 für die Konfiguration einer agentischen Anwendung zum Erfassen von Prompts und Antworten finden Sie unter Generative KI-Anwendungen instrumentieren.

Benutzerdefinierte Spannen erstellen

Mit OpenTelemetry und Clientbibliotheken können Sie benutzerdefinierte Spans erstellen. Möglicherweise müssen Sie sie jedoch 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 Spannen benutzerdefinierte Anmerkungen und Tags hinzufügen. Alternativ können Sie neue untergeordnete Spannen mit eigenen Anmerkungen und Tags erstellen, um das Verhalten der Anwendung genauer nachzuvollziehen.

Bibliotheken verwalten in der Regel einen globalen Trace-Kontext, der Informationen zum aktuellen Span enthält, einschließlich seiner Trace-ID und seines Sampling-Status. 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 der Kontext in Anwendungen mit mehreren Threads über Threads hinweg weitergegeben wird, damit die Tracedaten korrekt bleiben.

Trace-Sampling erzwingen

Sie können nicht erzwingen, dass Spans erfasst werden, da jede Komponente im Anfragepfad eine unabhängige Sampling-Entscheidung trifft. Sie können jedoch nachgelagerte Komponenten beeinflussen, indem Sie das sampled-Flag im Trace-Header auf true festlegen. Diese Einstellung ist ein Hinweis für untergeordnete Komponenten, die Anfrage zu analysieren. Weitere Informationen zu Trace-Headern finden Sie unter Protokolle für die Weitergabe von Kontext.

  • 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 services: Jeder Dienst bestimmt seine eigene Unterstützung für das Tracing. Im Allgemeinen akzeptieren Dienste das Flag für die übergeordnete Stichprobenerhebung als Hinweis, während sie ihre eigenen Grenzwerte für die Stichprobenerhebung durchsetzen.

Messwerte und Traces mit Beispielen korrelieren

Sie können Messwertdaten mithilfe von Exemplars mit Traces korrelieren. Ein Exemplar ist eine repräsentative Stichprobenanfrage oder ein repräsentativer Stichprobenzeitraum, 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 Dashboarddiagrammen, in denen SQL-Abfrageergebnisse für Tracedaten angezeigt werden, sind möglicherweise vom System generierte Beispiele zu sehen. Diese Beispiele 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 Anmeldedaten für Ihre Plattform konfigurieren.

APIs aktivieren

Standardmäßig sind die Cloud Trace API und die Telemetry API für Google Cloud -Projekte aktiviert. Sie müssen also 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.

Rollen, die zum Aktivieren von APIs erforderlich sind

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 Rolle „Inhaber“ (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 Tracedaten in der Google Cloud Console ansehen oder Tracedaten in Ihr Projekt schreiben:

  • Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Trace User (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 für Ihr Projekt die IAM-Rolle Cloud Trace-Agent (roles/cloudtrace.agent) zuzuweisen, damit Sie die Berechtigungen 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, damit Sie die Berechtigungen erhalten, die Sie zum Schreiben von Tracedaten mit der Telemetry API benötigen.

Authentifizieren

In diesem Abschnitt wird beschrieben, wie Sie sich authentifizieren, wenn Ihre Anwendungen aufGoogle Cloud ausgeführt werden und wenn sie an einem anderen Ort ausgeführt werden.

Ausführen auf Google Cloud

Wenn Ihre Anwendung auf Google Cloudausgeführt wird, müssen Sie in der Regel keine Anmeldedaten für die Authentifizierung angeben. Für einige Sprachclientbibliotheken ist die Projekt-ID jedoch auch dann erforderlich, wenn sie auf Google Cloudgehostet werden.

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

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, müssen Sie dafür sorgen, dass der Cloud Trace API-Zugriffsbereich aktiviert ist. 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. Im folgenden Befehl wird das Festlegen des Flags --scopes veranschaulicht:

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 Authentifizierungsanmeldedaten zur Verfügung stellen. Dem Dienstkonto muss die Rolle „Cloud Trace-Agent“ (roles/cloudtrace.agent) zugewiesen sein. Weitere 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 drei Arten angeben:

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

  • Speichern Sie die Dienstkontoschlüsseldatei 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