Trace-Erfassung mit OpenTelemetry einrichten

In diesem Dokument erfahren Sie, wie Sie clientseitiges und End-to-End-Tracing mit OpenTelemetry einrichten. Sie müssen das clientseitige Tracing einrichten, bevor Sie das End-to-End-Tracing aktivieren können. Weitere Informationen finden Sie unter Übersicht zur Trace-Erfassung.

Hinweise

  • Damit das von Ihrer Anwendung verwendete Dienstkonto die erforderlichen Berechtigungen zum Einrichten der Trace-Erfassung hat, bitten Sie Ihren Administrator, dem Dienstkonto die IAM-Rolle Cloud Trace-Agent (roles/cloudtrace.agent) für Ihr Projekt zuzuweisen.

Clientseitiges Tracing konfigurieren

Wenn Sie die clientseitige Aufrufabfolge konfigurieren möchten, müssen Sie Traces exportieren. Sie können Traces in einen Collector oder direkt in ein Observability-Backend exportieren. Sie können die Tracing-Funktion mit OpenTelemetry APIs konfigurieren.

Traces mit OpenTelemetry APIs in einen Collector exportieren

Wenn Sie Traces mit OpenTelemetry APIs in einen Collector exportieren möchten, konfigurieren Sie das OpenTelemetry SDK und den OTLP-Exporter:

  1. Fügen Sie Ihrer Anwendung die erforderlichen Abhängigkeiten mit dem folgenden Code hinzu:

    Java

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

    Go

    go.opentelemetry.io/otel v1.28.0
go.opentelemetry.io/otel/sdk v1.28.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.28.0

  2. Konfigurieren Sie das OpenTelemetry-Objekt und aktivieren Sie die Tracing-Funktion.

    Java

    Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
    OtlpGrpcSpanExporter
        .builder()
        .setEndpoint(otlpEndpoint) // Replace with your OTLP endpoint
        .build();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register as GlobalOpenTelemetry.
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

    Go

    
// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

// Enable OpenTelemetry traces by setting environment variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING
// to the case-insensitive value "opentelemetry" before loading the client library.

ctx := context.Background()

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new OTLP exporter.
defaultOtlpEndpoint := "http://localhost:4317" // Replace with the endpoint on which OTLP collector is running
traceExporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithEndpoint(defaultOtlpEndpoint))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(traceExporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

Direkter Export in ein Observability-Backend mit OpenTelemetry APIs

So konfigurieren Sie Spanner-Clientbibliotheken, um Trace-Bereiche direkt in Cloud Trace oder in das Backend eines anderen Anbieters von Observability-Diensten zu exportieren:

  1. Fügen Sie Ihrer Anwendung die erforderlichen Abhängigkeiten mit dem folgenden Code hinzu:

    Java

    <dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-common</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
<groupId>com.google.cloud.opentelemetry</groupId>
<artifactId>exporter-trace</artifactId>
<version>0.30.0</version>
</dependency>

    Go

    go.opentelemetry.io/otel v1.28.0
go.opentelemetry.io/otel/sdk v1.28.0
github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace v1.24.1

  2. Konfigurieren Sie das OpenTelemetry-Objekt und aktivieren Sie die Tracing-Funktion.

    Java

    Resource resource = Resource
    .getDefault().merge(Resource.builder().put("service.name", "My App").build());

SpanExporter traceExporter = TraceExporter.createWithConfiguration(
    TraceConfiguration.builder().setProjectId(projectId).build()
);

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
    BatchSpanProcessor.builder(traceExporter).build();

// Create a new tracer provider
sdkTracerProvider = SdkTracerProvider.builder()
    // Use Otlp exporter or any other exporter of your choice.
    .addSpanProcessor(otlpGrpcSpanProcessor)
    .setResource(resource)
    .setSampler(Sampler.traceIdRatioBased(0.1))
    .build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider).build();

// Enable OpenTelemetry traces before Injecting OpenTelemetry
SpannerOptions.enableOpenTelemetryTraces();

// Inject OpenTelemetry object via Spanner options or register it as global object.
// To register as the global OpenTelemetry object,
// use "OpenTelemetrySdk.builder()....buildAndRegisterGlobal()".
SpannerOptions options = SpannerOptions.newBuilder()
    .setOpenTelemetry(openTelemetry)
    .build();
Spanner spanner = options.getService();

    Go

    
// Ensure that your Go runtime version is supported by the OpenTelemetry-Go
// compatibility policy before enabling OpenTelemetry instrumentation.

// Enable OpenTelemetry traces by setting environment variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING
// to the case-insensitive value "opentelemetry" before loading the client library.

// Create a new resource to uniquely identify the application
res, err := resource.Merge(resource.Default(),
	resource.NewWithAttributes(semconv.SchemaURL,
		semconv.ServiceName("My App"),
		semconv.ServiceVersion("0.1.0"),
	))
if err != nil {
	log.Fatal(err)
}

// Create a new cloud trace exporter
exporter, err := traceExporter.New(traceExporter.WithProjectID(projectID))
if err != nil {
	log.Fatal(err)
}

// Create a new tracer provider
tracerProvider := sdktrace.NewTracerProvider(
	sdktrace.WithResource(res),
	sdktrace.WithBatcher(exporter),
	sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.1)),
)

// Register tracer provider as global
otel.SetTracerProvider(tracerProvider)

End-to-End-Analyse konfigurieren

In diesem Abschnitt finden Sie eine Anleitung zum Konfigurieren der End-to-End-Analyse (Vorabversion) in Spanner-Clientbibliotheken:

  1. Fügen Sie Ihrer Anwendung die erforderlichen Abhängigkeiten mit dem folgenden Code hinzu:

    Java

    Die vorhandenen clientseitigen Abhängigkeiten für die Tracing-Funktion reichen aus, um die End-to-End-Tracing-Funktion zu konfigurieren. Es sind keine zusätzlichen Abhängigkeiten erforderlich.

    Go

    Zusätzlich zu den Abhängigkeiten, die Sie für die clientseitige Analyse benötigen, ist auch die folgende Abhängigkeit erforderlich:

    go.opentelemetry.io/otel/propagation v1.28.0

  2. Aktivieren Sie das End-to-End-Tracing.

    Java

    SpannerOptions options = SpannerOptions.newBuilder()
  .setOpenTelemetry(openTelemetry)
  .setEnableEndToEndTracing(/* enableEndtoEndTracing= */ true)
  .build();

    Go

    Aktivieren Sie die Option EnableEndToEndTracing in der Clientkonfiguration. 

    client, _ := spanner.NewClientWithConfig(ctx, "projects/test-project/instances/test-instance/databases/test-db", spanner.ClientConfig{
SessionPoolConfig: spanner.DefaultSessionPoolConfig,
EnableEndToEndTracing:      true,
}, clientOptions...)

  3. Legen Sie die Weitergabe des Trace-Kontexts in OpenTelemetry fest.

    Java

    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
  .setTracerProvider(sdkTracerProvider)
  .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
  .buildAndRegisterGlobal();

    Go

    // Register the TraceContext propagator globally.
otel.SetTextMapPropagator(propagation.TraceContext{})

End-to-End-Tracing-Attribute

End-to-End-Traces können die folgenden Informationen enthalten:

Attributname Beschreibung
service.name Der Attributwert ist immer spanner_api_frontend.
cloud.region Die Google Cloud -Cloud-Region des Spanner API-Frontends, das Ihre Anwendungsanfrage verarbeitet.
gcp.spanner.query.fingerprint Der Attributwert ist der Abfragefingerabdruck. Weitere Informationen zur Fehlerbehebung bei dieser Abfrage finden Sie in der Spalte TEXT_FINGERPRINT in den Abfragestatistiktabellen.
gcp.spanner.participants.count Die Anzahl der an der Transaktion beteiligten Teilnehmer. Weitere Informationen finden Sie unter Lebensdauer von Lese- und Schreibvorgängen in Cloud Spanner.

Beispiel-Trace

In einem End-to-End-Trace können Sie die folgenden Details sehen:

  • Die Latenz zwischen Ihrer Anwendung und Spanner. Sie können die Netzwerklatenz berechnen, um festzustellen, ob es Netzwerkprobleme gibt.
  • Die Cloud-Region des Spanner API-Front-Ends, von der aus Ihre Anwendungsanfragen gesendet werden. So können Sie nach regionenübergreifenden Aufrufen zwischen Ihrer Anwendung und Spanner suchen.

Im folgenden Beispiel wird Ihre Anwendungsanfrage vom Spanner API-Frontend in der Region us-west1 verarbeitet und die Netzwerklatenz beträgt 8,542 ms (55,47 ms – 46,928 ms).

End-to-End-Trace ansehen

Nächste Schritte