Sie können Ihre Anwendungen für Cloud Trace instrumentieren, um verteilte Trace-Daten zu erfassen, die Latenz für einzelne Anfragen zu untersuchen und die aggregierte Latenz für alle 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
Wenn Trace-Daten zur Validierung der Leistung oder zur Fehlerbehebung nicht automatisch erfasst werden, instrumentieren Sie Ihre Anwendung.
Instrumentieren Sie Ihre Anwendung, um bestimmte Informationen zu erfassen, mit denen Sie die Leistung Ihrer Anwendung besser verstehen 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. Für Ihre agentenbasierten 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öffentlichtes Instrumentierungs-Framework wie OpenTelemetryanstelle 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 verschiedene 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 er Trace-Daten mithilfe der Telemetry API (OTLP) an Ihr Google Cloud Projekt sendet. Weitere Informationen zu unseren Empfehlungen, siehe 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 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 mit OTLP. Weitere Informationen finden Sie unter Ops-Agent und OTLP verwenden und Übersicht über den Ops-Agenten.
Rufen Sie entweder die Telemetry API oder die Cloud Trace API direkt auf.
Konfigurieren Sie Spring Boot-Anwendungen so, dass die erfassten Trace-Daten an Cloud Trace weitergeleitet werden. Informationen zu dieser Vorgehensweise 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:
Diese Beispiele senden Messwert- und Trace-Daten im OpenTelemetry Protocol-Format (OTLP) mithilfe der Telemetry API an Ihr Projekt. In den Beispielen wird ein Google Cloud Exporter für Logdaten 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, die zeigen, wie Sie eine agentenbasierte Anwendung so konfigurieren, dass Prompts und Antworten erfasst werden, finden Sie unter Generative KI-Anwendungen instrumentieren.
- Informationen zu Google Cloud MCP-Servern, die Trace-Spans generieren können, siehe MCP-Aufrufe mit Trace untersuchen.
Benutzerdefinierte Spans erstellen
Mit OpenTelemetry und Clientbibliotheken können Sie benutzerdefinierte Spans erstellen. Sie müssen sie jedoch möglicherweise nicht manuell erstellen, da diese Bibliotheken automatisch Spans an RPC-Grenzen erstellen.
Sie können auch Informationen, die für Ihre Anwendung relevant sind, hinzufügen, indem Sie benutzerdefinierte Annotationen und Tags zu vorhandenen Spans hinzufügen. Alternativ können Sie neue untergeordnete Spans mit eigenen Annotationen und Tags erstellen, um das Verhalten der Anwendung mit detaillierterer Genauigkeit zu verfolgen.
Bibliotheken verwalten normalerweise einen globalen Trace-Kontext, der Informationen über den aktuellen Span enthält, einschließlich der Trace-ID und des Sampling-Status. Anwendungen können über den globalen Trace-Kontext auf den aktuellen Span zugreifen. Da der Kontext global ist, müssen Multi-Threaded-Anwendungen den Kontext über Threads hinweg weitergeben, um genaue Trace-Daten zu erhalten.
Trace-Sampling erzwingen
Sie können nicht erzwingen, dass Spans als Stichprobe erfasst werden, da jede Komponente im Anfrage
pfad eine unabhängige Sampling-Entscheidung trifft. Sie können jedoch
nachgelagerte Komponenten beeinflussen, indem Sie das
sampled Flag im Trace-Header auf true setzen.
Diese Einstellung ist ein Hinweis für untergeordnete Komponenten, die Anfrage als Stichprobe zu erfassen.
Weitere Informationen zu Trace-Headern finden Sie unter
Protokolle für die Kontextweitergabe.
Ihre Anwendungen: Sie konfigurieren, wie die Instrumentierungslogik das Flag
sampledberücksichtigt. Wenn Sie beispielsweise OpenTelemetry verwenden, können Sie denParentBasedSampler 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 Sampling-Flag des übergeordneten Elements als Hinweis, während sie ihre eigenen Sampling-Ratenlimits erzwingen.
Messwerte und Traces mit Beispielen korrelieren
Sie können Messwertdaten mit Traces korrelieren, indem Sie Beispiele verwenden. Ein Exemplar ist eine repräsentative Stichprobe oder ein 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 Beispielen korrelieren.
In Dashboard-Diagrammen, in denen SQL-Abfrageergebnisse für Trace-Daten angezeigt werden, werden möglicherweise vom System generierte Beispiele angezeigt. 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 die Konfiguration von Anmeldedaten für Ihre Plattform erläutert.
APIs aktivieren
Standardmäßig Google Cloud sind für Projekte die Cloud Trace API und die Telemetry API aktiviert. Sie müssen nichts weiter tun. Sicherheitsbeschränkungen, die von Ihrer Organisation definiert wurden, 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.
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.
IAM-Rollen zuweisen
Die erforderlichen IAM-Rollen hängen davon ab, ob Sie Trace Daten in der Google Cloud Konsole 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 Konsole benötigen.
-
Bitten Sie Ihren Administrator, Ihnen die Cloud Trace-Agent (
roles/cloudtrace.agent) IAM-Rolle 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-Autor“ (
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 in Google Cloud ausgeführt werden und wenn sie an einem anderen Ort ausgeführt werden.
In ausführen Google Cloud
Wenn Ihre Anwendung in Google Cloudausgeführt wird, müssen Sie in der Regel keine Anmeldedaten zur Authentifizierung angeben. Einige Clientbibliotheken für Sprachen erfordern jedoch die Projekt-ID, auch wenn sie in gehostet werden Google Cloud.
Prüfen Sie, ob für Ihre Google Cloud Plattform der Zugriffsbereich der Cloud Trace API aktiviert ist. 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 die Google Cloud CLI verwenden, um einen GKE-Cluster zu erstellen, und das Flag --scopes angeben, muss der Bereich trace.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 ausgeführt wird Google Cloud, müssen Sie Anmeldedaten zur Authentifizierung
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 (ADC) für die Suche nach den Anmeldedaten Ihrer Anwendung. Sie können diese Anmeldedaten auf eine von drei Arten angeben:
Führen Sie
gcloud auth application-default loginaus.Platzieren Sie die Dienstkonto-Schlü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.jsonLinux:
$HOME/.config/gcloud/application_default_credentials.json
Legen Sie die Umgebungsvariable
GOOGLE_APPLICATION_CREDENTIALSauf 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"