Configurar a coleta de rastros usando o OpenTelemetry

Este documento mostra como configurar o rastreamento do lado do cliente e de ponta a ponta usando o OpenTelemetry. É necessário configurar o rastreamento do lado do cliente antes de ativar o rastreamento de ponta a ponta. Para mais informações, consulte Visão geral da coleta de trace.

Antes de começar

  • Para garantir que a conta de serviço usada pelo seu aplicativo tenha as permissões necessárias para configurar a coleta de rastros, peça ao administrador para conceder à conta de serviço usada pelo seu aplicativo o papel do IAM Agente do Cloud Trace (roles/cloudtrace.agent) no projeto.

Configurar o rastreamento do lado do cliente

Para configurar o rastreamento do lado do cliente, é necessário exportar os rastros. É possível exportar rastros para um coletor ou diretamente para um back-end de observabilidade. É possível configurar o rastreamento usando APIs do OpenTelemetry.

Exportar rastros para um coletor usando APIs do OpenTelemetry

Para exportar rastros para um coletor usando APIs do OpenTelemetry, configure o SDK do OpenTelemetry e o exportador OLTP:

  1. Adicione as dependências necessárias ao app usando o seguinte código:

    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. Configure o objeto OpenTelemetry e ative o rastreamento.

    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)

Exportar diretamente para um back-end de observabilidade usando APIs do OpenTelemetry

Para configurar as bibliotecas de cliente do Spanner a fim de exportar diretamente os intervalos de rastreamento para o Cloud Trace ou outro back-end de provedor de serviços de observabilidade, siga estas etapas:

  1. Adicione as dependências necessárias ao app usando o seguinte código:

    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. Configure o objeto OpenTelemetry e ative o rastreamento.

    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)

Configurar o rastreamento completo

Esta seção fornece instruções para configurar o rastreamento de ponta a ponta (pré-lançamento) nas bibliotecas de cliente do Spanner:

  1. Adicione as dependências necessárias ao app usando o seguinte código:

    Java

    As dependências de rastreamento do lado do cliente já são suficientes para configurar o rastreamento de ponta a ponta. Você não precisa de dependências adicionais.

    Go

    Além das dependências necessárias para o rastreamento do lado do cliente, você também precisa da seguinte dependência:

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

  2. Ative o rastreamento completo.

    Java

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

    Go

    Use a opção EnableEndToEndTracing na configuração do cliente para ativar. 

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

  3. Defina a propagação do contexto de rastreamento no OpenTelemetry.

    Java

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

    Go

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

Atributos de rastreamento completo

Os rastros de ponta a ponta podem incluir as seguintes informações:

Nome do atributo Descrição
service.name O valor do atributo é sempre spanner_api_frontend.
cloud.region A região do Google Cloud da API Spanner que atende à solicitação do aplicativo.
gcp.spanner.query.fingerprint O valor do atributo é a impressão digital da consulta. Para depurar essa consulta, consulte a coluna TEXT_FINGERPRINT nas tabelas de estatísticas de consulta.
gcp.spanner.participants.count O número de participantes envolvidos na transação. Para mais informações, consulte Vida útil das leituras e gravações do Spanner.

Exemplo de rastreamento

Um trace de ponta a ponta permite conferir os seguintes detalhes:

  • A latência entre seu aplicativo e o Spanner. Você pode calcular a latência da rede para saber se há problemas de rede.
  • A região da nuvem do front-end da API Spanner em que as solicitações do aplicativo estão sendo atendidas. Você pode usar isso para verificar chamadas entre regiões entre seu aplicativo e o Spanner.

No exemplo a seguir, a solicitação do aplicativo está sendo atendida pelo front-end da API Spanner na região us-west1 e a latência da rede é de 8,542 ms (55,47 ms - 46,928 ms).

Acessar um trace de ponta a ponta.

A seguir