Diese Seite wurde von der Cloud Translation API übersetzt.

Übersicht über die Instrumentierung 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.

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.

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 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"

Dabei gilt:

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.
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, um die Anfrage nicht zu verfolgen.

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 kann Cloud Trace-Beispiele erstellen, wenn es Zeitachsendaten für gRPC-Dienste schreibt. Beispiele sind Beispielpunkte, die an Verteilungsmessungen angehängt werden können. Sie haben beispielsweise die Möglichkeit, ein Latenzmesswert mit einem Label für eine URL zu versehen. Sie können dem Messwert kein URL-Label hinzufügen, da der Messwert dann eine hohe Kardinalität hätte und dies zu Leistungsproblemen führt. Sie können aber ein Beispiel erstellen, mit dem die URL aufgezeichnet wird. Weitere Informationen finden Sie unter Exemplar.

So rufen Sie Beispiele auf:

Diagramm zu einem Verteilungswert und setzen Sie den Diagrammtyp auf Heatmap-Diagramm. Sie können ein Diagramm in einem Dashboard erstellen oder den Metrics Explorer verwenden.
Wählen Sie in der Symbolleiste des Diagramms in der Symbolleiste des Diagramms Trace-Beispiele aus. Beispiele finden Sie unter Diagrammsymbolleiste.

Zur Erstellung von Beispielen können Sie eigene benutzerdefinierte Messwerte schreiben oder Bibliotheken wie OpenCensus verwenden. Allgemeine Informationen zu benutzerdefinierten Messwerten finden Sie hier:

Im folgenden Codebeispiel wird gezeigt, wie ein Beispiel geschrieben wird:

Erstellen Sie die zusätzlichen Informationen für die Anzahl der Buckets:
- Das Objekt SpanContext speichert eine Projekt-ID, eine Trace-ID und eine Span-ID. Diese Felder müssen mit den Werten eines Trace übereinstimmen, der an Cloud Trace gesendet wurde. Cloud Monitoring verwendet diese Felder, um den anzuzeigenden Trace zu ermitteln.
- Das Objekt DroppedLabels definiert die zusätzlichen Labels. Im folgenden Codebeispiel wird ein Label hinzugefügt. Der Schlüssel ist "Label" der Wert ist "Dropped". In dem oben beschriebenen Beispiel für den Latenzmesswert könnte ein Label mit dem Schlüssel „URL&“ hinzugefügt werden.
Schreiben Sie einen Point in die Zeitachse:
- Das Feld TimeInterval definiert die Start- und Endzeiten für den Punkt.
- Das Feld „DistributionValue“ gibt die Daten an. Die Daten enthalten die Definition der Distribution-Buckets und die Bucket-Werte. Dieses Feld enthält auch alle Beispiele, die mit den Daten geschrieben werden sollen. Im Beispiel werden zwei Beispiele geschrieben, von denen eines den Span-Kontext und die verworfenen Labelobjekte enthält.

Auf GitHub ansehen Feedback

import (
	"fmt"
	"time"

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

// Generates metric TimeSeries points containing Exemplars with attached tracing span.
func createDataPointWithExemplar(projectID string) (*monitoringpb.Point, error) {
	// projectID := "my-cloud-project-id"
	end := time.Now().Unix()
	traceId := "0000000000000001"
	spanId := "00000001"
	spanCtx, err := anypb.New(&monitoringpb.SpanContext{
		SpanName: fmt.Sprintf("projects/%s/traces/%s/spans/%s", projectID, traceId, spanId),
	})
	if err != nil {
		return nil, err
	}
	droppedLabels, err := anypb.New(&monitoringpb.DroppedLabels{
		Label: map[string]string{"Label": "Dropped"},
	})
	if err != nil {
		return nil, err
	}
	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}, Attachments: []*anypb.Any{spanCtx, droppedLabels}},
					{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint, nil
}

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:

Gehen Sie in der Google Cloud Console zu APIs und Dienste:

Zu den APIs und Diensten
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.

Weitere Informationen

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