Trace-Erfassung mit OpenTelemetry einrichten

In diesem Dokument erfahren Sie, wie Sie mit OpenTelemetry clientseitiges und End-to-End-Tracing einrichten. Bevor Sie sich für das End-to-End-Tracing anmelden können, müssen Sie das clientseitige Tracing einrichten. Weitere Informationen finden Sie unter Trace collection overview.

Hinweis

  • Damit das Dienstkonto, das Ihre Anwendung verwendet, die erforderlichen Berechtigungen zum Einrichten der Trace-Erfassung hat, bitten Sie Ihren Administrator, dem Dienstkonto, das Ihre Anwendung in Ihrem Projekt verwendet, die folgenden IAM-Rollen zuzuweisen:

  • Prüfen Sie, ob die Cloud Trace und Telemetry API in Ihrem Projekt aktiviert sind. Weitere Informationen zum Aktivieren von APIs finden Sie unter APIs aktivieren.

Clientseitiges Tracing konfigurieren

Konfigurieren Sie Ihre Anwendung, um Traces mit dem OpenTelemetry Protocol (OTLP) zu exportieren. Sie können Daten entweder an einen OpenTelemetry Collector oder direkt an Cloud Trace über die Telemetry API senden. Beide Methoden verwenden dieselben Abhängigkeiten und dieselbe Konfiguration. Sie unterscheiden sich nur im OTLP-Endpunkt, den der Exporter verwendet.

Traces mit dem OpenTelemetry Protocol exportieren

Konfigurieren Sie das OpenTelemetry SDK und den OTLP-Exporter, um Traces mit dem OpenTelemetry Protocol zu exportieren:

  1. Fügen Sie Ihrer Anwendung mit dem folgenden Code die erforderlichen Abhängigkeiten 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

    Node.js

    "@opentelemetry/exporter-trace-otlp-grpc": "^0.57.0",
"@opentelemetry/sdk-trace-base": "^1.26.0",
"@opentelemetry/sdk-trace-node": "^1.26.0",

    Python

    pip install opentelemetry-api opentelemetry-sdk
pip install opentelemetry-exporter-otlp

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

    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)

    Node.js

    const {NodeTracerProvider} = require('@opentelemetry/sdk-trace-node');
const {
  OTLPTraceExporter,
} = require('@opentelemetry/exporter-trace-otlp-grpc');
const {
  BatchSpanProcessor,
  TraceIdRatioBasedSampler,
} = require('@opentelemetry/sdk-trace-base');
const {Resource} = require('@opentelemetry/resources');
const {Spanner} = require('@google-cloud/spanner');

// Define a Resource with service metadata
const resource = new Resource({
  'service.name': 'my-service',
  'service.version': '1.0.0',
});

// Create an OTLP gRPC trace exporter
const traceExporter = new OTLPTraceExporter({
  url: 'http://localhost:4317', // Default OTLP gRPC endpoint
});

// Create a provider with a custom sampler
const provider = new NodeTracerProvider({
  sampler: new TraceIdRatioBasedSampler(1.0), // Sample 100% of traces
  resource,
  spanProcessors: [new BatchSpanProcessor(traceExporter)],
});

// Uncomment following line to register tracerProvider globally or pass it in Spanner object
// provider.register();

// Create the Cloud Spanner Client.
const spanner = new Spanner({
  projectId: projectId,
  observabilityOptions: {
    tracerProvider: provider,
    enableExtendedTracing: true,
    enableEndToEndTracing: true,
  },
});

    Python

    # Setup OpenTelemetry, trace and OTLP exporter.
tracer_provider = TracerProvider(sampler=ALWAYS_ON)
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")
tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Setup the Cloud Spanner Client.
spanner_client = spanner.Client(
    project_id,
    observability_options=dict(tracer_provider=tracer_provider, enable_extended_tracing=True, enable_end_to_end_tracing=True),
)

End-to-End-Tracing konfigurieren

In diesem Abschnitt finden Sie eine Anleitung zum Konfigurieren des End-to-End-Tracing in Spanner-Clientbibliotheken:

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

    Java

    Die vorhandenen clientseitigen Tracing-Abhängigkeiten reichen aus, um das End-to-End-Tracing zu konfigurieren. Sie benötigen keine zusätzlichen Abhängigkeiten.

    Go

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

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

    Node.js

    Die vorhandenen clientseitigen Tracing-Abhängigkeiten reichen aus, um das End-to-End-Tracing zu konfigurieren. Sie benötigen keine zusätzlichen Abhängigkeiten.

    Python

    Die vorhandenen clientseitigen Tracing-Abhängigkeiten reichen aus, um das End-to-End-Tracing zu konfigurieren. Sie benötigen keine zusätzlichen Abhängigkeiten.

  2. Melden Sie sich für das End-to-End-Tracing an.

    Java

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

    Go

    Verwenden Sie die Option EnableEndToEndTracing in der Clientkonfiguration, um sich anzumelden. 

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

    Node.js

    const spanner = new Spanner({
projectId: projectId,
observabilityOptions: {
tracerProvider: openTelemetryTracerProvider,
enableEndToEndTracing: true,
}
})

    Python

    observability_options={
"tracer_provider": tracer_provider,
"enable_end_to_end_tracing": True,
}
spanner = spanner.Client(project_id, observability_options=observability_options)

  3. Legen Sie die Trace-Kontextverteilung 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{})

    Node.js

    const {propagation} = require('@opentelemetry/api');
const {W3CTraceContextPropagator} = require('@opentelemetry/core');
propagation.setGlobalPropagator(new W3CTraceContextPropagator());

    Python

    from opentelemetry.propagate import set_global_textmap
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
set_global_textmap(TraceContextTextMapPropagator())

Attribute für das End-to-End-Tracing

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 Front-Ends, das Ihre Anwendungsanfrage verarbeitet.
gcp.spanner.server.query.fingerprint Der Attributwert ist der Abfrage-Fingerabdruck. Weitere Informationen zum Debuggen dieser Abfrage finden Sie in der TEXT_FINGERPRINT Spalte in den Abfragestatistiktabellen.
gcp.spanner.server.paxos.participantcount Die Anzahl der an der Transaktion beteiligten Teilnehmer. Weitere Informationen finden Sie unter Lebensdauer von Lese- und Schreibvorgängen in Spanner.
gcp.spanner.isolation_level Der Attributwert ist die Isolationsebene der Transaktion. Mögliche Werte sind SERIALIZABLE und REPEATABLE_READ. Weitere Informationen finden Sie unter Isolationsebenen – Übersicht.

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 Netzwerkprobleme vorliegen.
  • Die Cloud-Region des Spanner API-Front-Ends, in der Ihre Anwendungsanfragen verarbeitet werden. So können Sie regionsübergreifende Aufrufe zwischen Ihrer Anwendung und Spanner prüfen.

Im folgenden Beispiel wird Ihre Anwendungsanfrage vom Spanner API-Front-End 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