Configurare la raccolta delle tracce utilizzando OpenTelemetry

Questo documento mostra come configurare il monitoraggio lato client e end-to-end utilizzando OpenTelemetry. Devi configurare il monitoraggio lato client prima di poter attivare il monitoraggio end-to-end. Per ulteriori informazioni, consulta la panoramica della raccolta dei traccianti.

Prima di iniziare

  • Per assicurarti che l'account di servizio utilizzato dalla tua applicazione disponga delle autorizzazioni necessarie per configurare la raccolta dei traccianti, chiedi all'amministratore di concedere all'account di servizio utilizzato dalla tua applicazione il ruolo IAM Agente Cloud Trace (roles/cloudtrace.agent) nel tuo progetto.

  • Verifica che l'API Cloud Trace sia abilitata nel tuo progetto. Per ulteriori informazioni sull'attivazione delle API, consulta Attivare le API.

Configurare il monitoraggio lato client

Per configurare il monitoraggio lato client, devi esportare le tracce. Puoi esportare le tracce in un collector o direttamente in un backend di osservabilità. Puoi configurare il monitoraggio utilizzando le API OpenTelemetry.

Esportare le tracce in un collector utilizzando le API OpenTelemetry

Per esportare le tracce in un raccoglitore utilizzando le API OpenTelemetry, configura l'SDK OpenTelemetry e l'esportatore OLTP:

  1. Aggiungi le dipendenze necessarie all'applicazione utilizzando il seguente codice:

    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>

    Vai

    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. Configura l'oggetto OpenTelemetry e abilita il monitoraggio.

    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();

    Vai

    
// 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),
)

Esporta direttamente in un backend di osservabilità utilizzando le API OpenTelemetry

Per configurare le librerie client di Spanner in modo da esportare direttamente gli intervalli di traccia in Cloud Trace o in un altro backend del provider di servizi di osservabilità, segui questi passaggi:

  1. Aggiungi le dipendenze necessarie all'applicazione utilizzando il seguente codice:

    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>

    Vai

    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

    Node.js

    "@google-cloud/opentelemetry-cloud-trace-exporter": "^2.4.1",
"@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-gcp-trace

  2. Configura l'oggetto OpenTelemetry e abilita il monitoraggio.

    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();

    Vai

    
// 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)

    Node.js

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

const traceExporter = new TraceExporter();

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

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

// Set global propagator to propogate the trace context for end to end tracing.
const {propagation} = require('@opentelemetry/api');
const {W3CTraceContextPropagator} = require('@opentelemetry/core');
propagation.setGlobalPropagator(new W3CTraceContextPropagator());

const spanner = new Spanner({
  projectId: projectId,
  observabilityOptions: {
    tracerProvider: provider,
    // Enable extended tracing to allow your SQL statements to be annotated.
    enableExtendedTracing: true,
    // Enable end to end tracing.
    enableEndToEndTracing: true,
  },
});

    Python

    # Setup OpenTelemetry, trace and Cloud Trace exporter.
tracer_provider = TracerProvider(sampler=ALWAYS_ON)
trace_exporter = CloudTraceSpanExporter(project_id=project_id)
tracer_provider.add_span_processor(BatchSpanProcessor(trace_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),
)

Configura il monitoraggio end-to-end

Questa sezione fornisce istruzioni per configurare il monitoraggio end-to-end (anteprima) nelle librerie client di Spanner:

  1. Aggiungi le dipendenze necessarie all'applicazione utilizzando il seguente codice:

    Java

    Le dipendenze di monitoraggio lato client esistenti sono sufficienti per configurare il monitoraggio end-to-end. Non sono necessarie dipendenze aggiuntive.

    Vai

    Oltre alle dipendenze necessarie per il monitoraggio lato client, è necessaria anche la seguente dipendenza:

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

    Node.js

    Le dipendenze di monitoraggio lato client esistenti sono sufficienti per configurare il monitoraggio end-to-end. Non sono necessarie dipendenze aggiuntive.

    Python

    Le dipendenze di monitoraggio lato client esistenti sono sufficienti per configurare il monitoraggio end-to-end. Non sono necessarie dipendenze aggiuntive.

  2. Attiva il monitoraggio end-to-end.

    Java

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

    Vai

    Utilizza l'opzione EnableEndToEndTracing nella configurazione del client per attivare la funzionalità. 

    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 = dict(
tracer_provider=tracer_provider,
enable_end_to_end_tracing=True,
)
spanner = spanner.NewClient(project_id, observability_options=observability_options)

  3. Imposta la propagazione del contesto della traccia in OpenTelemetry.

    Java

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

    Vai

    // 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())

Attributi di monitoraggio end-to-end

Le tracce end-to-end possono includere le seguenti informazioni:

Nome dell'attributo Descrizione
service.name Il valore dell'attributo è sempre spanner_api_frontend.
cloud.region La Google Cloud regione cloud del frontend dell'API Spanner che gestisce la richiesta dell'applicazione.
gcp.spanner.query.fingerprint Il valore dell'attributo è l'impronta della query. Per eseguire ulteriormente il debug di questa query, consulta la colonna TEXT_FINGERPRINT nelle tabelle Statistiche sulle query.
gcp.spanner.participants.count Il numero di partecipanti coinvolti nella transazione. Per ulteriori informazioni, consulta la sezione Durata di letture e scritture di Spanner.

Traccia di esempio

Una traccia end-to-end ti consente di visualizzare i seguenti dettagli:

  • La latenza tra la tua applicazione e Spanner. Puoi calcolare la latenza della rete per verificare se ci sono problemi di rete.
  • La regione cloud del frontend dell'API Spanner da cui vengono eseguite le richieste dell'applicazione. Puoi utilizzarlo per verificare la presenza di chiamate tra regioni tra la tua applicazione e Spanner.

Nell'esempio seguente, la richiesta dell'applicazione viene gestita dal frontend dell'API Spanner nella regione us-west1 e la latenza della rete è di 8,542 ms (55,47 ms - 46,928 ms).

Visualizza una traccia end-to-end.

Passaggi successivi