Instrument für Cloud Trace

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 so instrumentieren, dass diese Daten erfasst werden.

Sie können Ihre Anwendung so instrumentieren, dass anwendungsspezifische Informationen erfasst werden. Mit verschiedenen Open-Source-Instrumentierungs-Frameworks können Sie Messwerte, Logs und Traces aus Ihrer Anwendung erfassen und diese Daten an einen beliebigen Anbieter, einschließlich Google Cloud, senden. Wir empfehlen die Verwendung eines anbieterneutralen Instrumentierungs-Frameworks auf Open-Source-Basis wie OpenTelemetry anstelle von anbieter- und produktspezifischen APIs oder Clientbibliotheken, um Ihre Anwendung zu instrumentieren.

Informationen zur Instrumentierung Ihrer Anwendungen mit anbieterneutralen Instrumentierungs-Frameworks finden Sie unter Instrumentierung und Beobachtbarkeit.

Anwendungen instrumentieren

Empfehlungen zur Instrumentierung Ihrer Anwendungen zum Erfassen von Logs, Messwerten und Traces finden Sie unter Instrumentierungsansatz auswählen.

Sie haben folgende Möglichkeiten, um Ihre Anwendungen zum Erfassen 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

Im Allgemeinen müssen Sie für Ihre Anwendung keine Anmeldedaten zur Authentifizierung bereitstellen und auch keine Google Cloud-Projekt-ID in Ihrer Anwendung angeben, wenn sie in Google Cloud ausgeführt wird. 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 verwenden oder Workload Identity aktivieren, müssen Sie außerdem Ihre Anwendung für die Verwendung von Workload Identity 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 jeden Span erfasst, ist es im Allgemeinen nicht möglich, das vollständige Tracing einer Anfrage zu erzwingen, da jede Komponente in einer End-to-End-Anfrage eine eigene Stichprobenentscheidung trifft. Sie können die Entscheidung jedoch auch beeinflussen, indem Sie dem Trace-Header ein sampled-Flag hinzufügen, bei dem dieses Flag auf true gesetzt ist. 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 Kontextverteilung.

Bei nachgelagerten Komponenten, deren Code Sie besitzen, müssen Sie bestimmen, ob die Instrumentierungslogik das Flag sampled berücksichtigt. Wenn Sie beispielsweise OpenTelemetry als Instrumentierung verwenden, können Sie mit dem ParentBased-Sampler dafür sorgen, dass das übergeordnete Sampled-Flag berücksichtigt wird.

Google Cloud-Dienste, die Tracing-Informationen in Cloud Trace aufzeichnen, akzeptieren in der Regel das übergeordnete Stichproben-Flag als Hinweis. Die meisten Dienste verwenden jedoch auch Ratenbegrenzungs-Sampling. Jeder Google Cloud-Dienst entscheidet, ob er Tracing unterstützt, wie das übergeordnete Flag für die Stichprobenerhebung verwendet wird und welche Ratenbegrenzung für die Stichprobenerhebung vorliegt.

Cloud Trace API aktivieren

Zur Verwendung von Cloud Trace muss die Cloud Trace API für Ihr Google Cloud-Projekt aktiviert sein. Mit dieser Einstellung kann Ihr Google Cloud-Projekt Trace-Daten von authentifizierten Quellen empfangen. Standardmäßig ist für das Google Cloud-Projekt die Cloud Trace API aktiviert. Sie müssen nichts weiter tun. Möglicherweise müssen Sie jedoch die Cloud Trace API aktivieren, wenn Sie die Zugriffsbereiche Ihres Google Cloud-Projekts geändert haben.

So aktivieren Sie die Cloud Trace API:

  1. Wählen Sie im Navigationsbereich der Google Cloud Console APIs und Dienste aus, klicken Sie auf APIs und Dienste aktivieren und aktivieren Sie dann die Cloud Trace API:

    Zu den Einstellungen für die Cloud Trace API

  2. Wenn API aktiviert angezeigt wird, ist die API bereits aktiviert. Falls nicht, klicken Sie auf die Schaltfläche Aktivieren.

Nächste Schritte

Detaillierte Konfigurationsinformationen, Beispiele und Links zu GitHub und anderen Open-Source-Repositories finden Sie auf der Einrichtungsseite für Ihre Sprache: