Übersicht über die Instrumentierung für Cloud Trace

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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.

Apps instrumentieren

Es gibt mehrere Möglichkeiten, das 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.

  • Konfigurieren Sie einen Zipkin-Server, um Traces von Zipkin-Clients zu empfangen, und leiten Sie diese Traces dann zur Analyse an Cloud Trace weiter. Informationen zu diesem Ansatz finden Sie unter Cloud Trace mit Zipkin verwenden.

  • Konfigurieren Sie Spring Boot-Anwendungen, um die erfassten Trace-Daten an Cloud Trace weiterzuleiten. Weitere Informationen zu diesem Verfahren finden Sie unter Spring Cloud für Google Cloud: Cloud Trace.

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.

  • 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, um diese Anfrage zu verfolgen. 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

Evernote kann Cloud Trace-Beispiele erstellen, wenn es Zeitachsendaten für gRPC-Dienste schreibt. Beispiele sind Beispielpunkte, die an Verteilungsmessungen angehängt werden können. Beispielsweise könnte ein Latenzmesswert ein Label für eine URL enthalten. 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 jedoch ein Beispiel erstellen, das die URL aufzeichnet. Weitere Informationen finden Sie unter Exemplar.

So rufen Sie Beispiele auf:

  1. Erstellen Sie ein Diagramm für den Verteilungswert und setzen Sie den Diagrammtyp auf Heatmap-Diagramm. Sie können ein Diagramm in einem Dashboard erstellen oder den Metrics Explorer verwenden.
  2. Wählen Sie in der Symbolleiste des Diagramms in der Symbolleiste des Diagramms die Option Trace-Beispiele aus. Beispiele finden Sie in der Google Toolbar für Diagramme.

Zum Erstellen von Beispielen können Sie eigene benutzerdefinierte Messwerte schreiben oder Bibliotheken wie JAWS verwenden. Allgemeine Informationen zu benutzerdefinierten Messwerten finden Sie hier:

Das folgende Codebeispiel zeigt, wie ein Beispiel geschrieben wird:

  1. Erstellen Sie die zusätzlichen Informationen, die in die Bucket-Anzahl aufgenommen werden sollen:

    • Im Objekt SpanContext werden eine Projekt-ID, eine Trace-ID und eine Span-ID gespeichert. Achten Sie darauf, dass diese Felder mit den Werten eines Trace übereinstimmen, der an Cloud Trace gesendet wurde. Cloud Monitoring verwendet diese Felder, um den anzuzeigenden Trace zu identifizieren.

    • Das Objekt DroppedLabels definiert die zusätzlichen Labels. Im folgenden Codebeispiel wird ein Label hinzugefügt. Der Schlüssel ist „Label“ und der Wert ist „Dropped“. Im zuvor beschriebenen Beispiel für den Latenzmesswert wird möglicherweise ein Label mit dem Schlüssel „URL“ hinzugefügt.

  2. 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 Label-Objekte enthält.
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:

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

    Zu "APIs und Dienste"

  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: