Diese Seite 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.
Cloud Trace empfiehlt die Verwendung von OpenTelemetry. OpenTelemetry ist ein Open-Source-Produkt aus der Fusion von OpenCensus und OpenTracing.
Wann Sie Ihre Anwendung instrumentieren müssen
Damit Ihre Anwendung Traces an Cloud Trace senden kann, muss sie instrumentiert sein. Sie können Ihren Code mithilfe der Google-Clientbibliotheken instrumentieren. Es wird jedoch empfohlen, OpenTelemetry oder OpenCensus zur Instrumentierung Ihrer Anwendung zu verwenden. Dies sind Open-Source-Tracing-Pakete OpenTelemetry befindet sich aktiv in der Entwicklung und ist das bevorzugte Paket.
Tracing für Anwendungen instrumentieren
Es gibt drei Möglichkeiten, Tracing für Ihre Anwendungen zu implementieren:
Verwenden Sie OpenTelemetry und die zugehörige Cloud Trace-Clientbibliothek. Dies ist die empfohlene Methode zur Instrumentierung Ihrer Anwendungen.
Verwenden Sie OpenCensus, wenn für Ihre Sprache keine OpenTelemetry-Clientbibliothek verfügbar ist.
Verwenden Sie die Cloud Trace API und schreiben Sie benutzerdefinierte Methoden, um Tracing-Daten an Cloud Trace zu senden.
Empfohlene Clientbibliotheken
In der folgenden Tabelle ist die empfohlene Clientbibliothek für jede Programmiersprache aufgeführt:
Sprache | Empfohlene Clientbibliothek |
---|---|
Python | OpenCensus |
Java | OpenCensus |
Node.js | Cloud Trace API |
Go | OpenCensus |
C# .NET | Cloud Trace API |
PHP | OpenCensus |
Ruby | Cloud Trace API |
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
Sie müssen keine Authentifizierungsanmeldedaten für Ihre Anwendung oder Ihre Google Cloud-Projekt-ID in Ihrer Anwendung angeben, wenn Sie Google Cloud ausführen. Bei einigen Sprachen müssen Sie Ihre Google Cloud-Projekt-ID angeben, auch wenn Sie Google Cloud ausführen.
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
Cloud Trace erfasst nicht jede Anfrage. Wenn Sie beispielsweise Java und OpenCensus verwenden, wird nur von einer Anfrage pro 10.000 Anfragen eine verfolgt. Wenn Sie App Engine verwenden, werden Anfragen mit einer Rate von 0,1 Anfragen pro Sekunde für jede App Engine-Instanz erfasst. Wenn Sie die Cloud Trace API verwenden, können Sie Kundenraten konfigurieren. Einige Pakete, z. B. das Java OpenCensus-Paket, unterstützen die Konfiguration der Stichprobenrate.
Sie können das Tracing einer bestimmten Anfrage erzwingen, indem Sie der Anfrage einen X-Cloud-Trace-Context
-Header hinzufügen. Die Headerspezifikation lautet:
"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"
Wobei:
TRACE_ID
ist ein aus 32 Zeichen bestehender hexadezimaler Wert, der für eine Zahl mit 128 Bit steht. Er darf innerhalb Ihrer Anfragen nur einmal vorhanden sein, wenn Sie die Anfragen nicht bewusst bündeln möchten. Sie können UUIDs verwenden.SPAN_ID
ist die dezimale Darstellung der Span-ID (ohne Vorzeichen). Sie sollte zufällig in Ihrem Trace generiert und eindeutig sein. Legen Sie für nachfolgende AnfragenSPAN_ID
auf die Span-ID der übergeordneten Anfrage fest. Weitere Informationen zu verschachtelten Traces finden Sie in der Beschreibung vonTraceSpan
(REST, RPC).TRACE_TRUE
muss1
sein, damit diese Anfrage verfolgt wird. Geben Sie0
an, wenn die Anfrage nicht verfolgt werden soll.
So erzwingen Sie beispielsweise einen Trace mit curl:
curl "http://www.example.com" --header "X-Cloud-Trace-Context:
105445aa7843bc8bf206b12000100000/1;o=1"
Cloud Trace-Executors erstellen
OpenCensus erstellt Cloud Trace-Beispiele, wenn Zeitachsendaten für gRPC-Dienste geschrieben werden. Zur Anzeige dieser Beispiele erstellen Sie ein Diagramm und aktivieren deren Anzeige in der Symbolleiste des Diagramms. Weitere Informationen finden Sie unter Diagramm-Symbolleiste verwenden.
Wenn Sie eigene benutzerdefinierte Messwerte schreiben möchten, finden Sie weitere Informationen in den folgenden Ressourcen:
- Unter Benutzerdefinierte Messwerte verwenden erhalten Sie eine konzeptionelle Darstellung benutzerdefinierter Messwerte.
- Benutzerdefinierte Messwerte mit OpenCensus veranschaulicht, wie OpenCensus verwendet wird, um Zeitachsen zu schreiben.
- Unter Benutzerdefinierte Messwerte erstellen wird der Prozess zum Erstellen benutzerdefinierter Messwerte mithilfe der Cloud Monitoring API beschrieben.
Wenn Sie benutzerdefinierte Messwerte schreiben, können Sie Proben erstellen. Im folgenden Go-Code-Snippet wird gezeigt, wie ein einzelner Point
in einer Zeitachse erstellt wird. Das erste Element ist das Zeitintervall mit der Bezeichnung Interval
und das zweite der Wert. Der Wert ist eine Instanz eines TypedValue
-Objekts und muss in ein distributionValue
aufgelöst werden.
Google Cloud-Projekt konfigurieren
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. Wenn Sie die Zugriffsbereiche Ihres Google Cloud-Projekts geändert haben und Ihre Einstellungen prüfen möchten, gehen Sie so vor:
Rufen Sie in der Google Cloud Console APIs und Dienste auf:
Klicken Sie auf APIs und Dienste aktivieren
Geben Sie in der Suchleiste Trace API ein.
Wenn API aktiviert angezeigt wird, ist diese API bereits aktiviert und Sie müssen nichts tun. Klicken Sie andernfalls auf 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: