Überblick

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.

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.

In der folgenden Tabelle ist die empfohlene Instrumentierung für jede Programmiersprache aufgeführt:

Sprache Empfohlene Instrumentierung
C# .NET Cloud Trace API
Go OpenTelemetry
Java OpenTelemetry
Node.js OpenTelemetry
PHP OpenCensus
Python OpenTelemetry
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 nutzerdefinierte Raten konfigurieren. Einige Pakete, z. B. das Java OpenCensus-Paket, unterstützen die Konfiguration der Stichprobenrate.

Wenn Sie einen Mikrodienst mit einer Abtastrate konfigurieren, gilt diese Rate nur für Anfragen, die bei diesem Mikrodienst beginnen. Wenn Sie keine Abtastrate für einen Mikrodienst konfigurieren, bestimmt die Abtastrate des übergeordneten Kontexts die Abtastrate für den Mikrodienst.

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 Anfragen SPAN_ID auf die Span-ID der übergeordneten Anfrage fest. Weitere Informationen zu verschachtelten Traces finden Sie in der Beschreibung von TraceSpan (REST, RPC).

  • TRACE_TRUE muss 1 sein, damit diese Anfrage verfolgt wird. Geben Sie 0 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:

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.

import (
	"time"

	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
)

func createDataPointWithExemplar() *monitoringpb.Point {
	end := time.Now().Unix()
	dataPoint := &monitoringpb.Point{
		Interval: &monitoringpb.TimeInterval{
			StartTime: &googlepb.Timestamp{Seconds: end - 60},
			EndTime:   &googlepb.Timestamp{Seconds: end},
		},
		Value: &monitoringpb.TypedValue{Value: &monitoringpb.TypedValue_DistributionValue{
			DistributionValue: &distributionpb.Distribution{
				Count: 14,
				BucketOptions: &distributionpb.Distribution_BucketOptions{Options: &distributionpb.Distribution_BucketOptions_LinearBuckets{
					LinearBuckets: &distributionpb.Distribution_BucketOptions_Linear{NumFiniteBuckets: 2, Width: 3, Offset: 0},
				}},
				BucketCounts: []int64{5, 6, 3},
				Exemplars: []*distributionpb.Distribution_Exemplar{
					{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
					{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint
}

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:

  1. Rufen Sie in der Google Cloud Console APIs und Dienste auf:

    Rufen Sie "APIs und Dienste" auf.

  2. Klicken Sie auf APIs und Dienste aktivieren

  3. Geben Sie in der Suchleiste Trace API ein.

  4. 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: