OpenTelemetry를 사용하여 trace 수집 설정

이 문서에서는 OpenTelemetry를 사용하여 클라이언트 측 및 엔드 투 엔드 trace를 설정하는 방법을 설명합니다. 엔드 투 엔드 trace를 선택하려면 먼저 클라이언트 측 trace를 설정해야 합니다. 자세한 내용은 Trace 컬렉션 개요를 참조하세요.

시작하기 전에

• 애플리케이션에서 사용하는 서비스 계정에 trace 수집을 설정하는 데 필요한 권한이 있는지 확인하려면 관리자에게 애플리케이션에서 사용하는 서비스 계정에 프로젝트에 대한 Cloud Trace 에이전트(roles/cloudtrace.agent) IAM 역할을 부여해 달라고 요청하세요.

  중요: 이 역할은 사용자 계정이 아닌 애플리케이션에서 사용하는 서비스 계정에 부여해야 합니다. 역할을 올바른 주 구성원에게 부여하지 않으면 권한 오류가 발생할 수 있습니다.

• 프로젝트에 Cloud Trace API가 사용 설정되어 있는지 확인합니다. API 사용 설정에 관한 자세한 내용은 API 사용 설정을 참고하세요.

클라이언트 측 trace 구성

클라이언트 측 trace를 구성하려면 trace를 내보내야 합니다. 수집기로 내보내거나 관측 가능성 백엔드로 trace를 직접 내보낼 수 있습니다. OpenTelemetry API를 사용하여 trace를 구성할 수 있습니다.

OpenTelemetry API를 사용하여 수집기로 trace 내보내기

OpenTelemetry API를 사용하여 수집기로 trace를 내보내려면 OpenTelemetry SDK 및 OLTP 내보내기 도구를 구성합니다.

1. 다음 코드를 사용하여 필요한 종속 항목을 애플리케이션에 추가합니다.

   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. OpenTelemetry 객체를 구성하고 trace를 사용 설정합니다.

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

OpenTelemetry API를 사용하여 관측 가능성 백엔드로 직접 내보내기

Cloud Trace 또는 다른 관측 가능성 서비스 제공업체 백엔드로 trace 스팬을 직접 내보내도록 Spanner 클라이언트 라이브러리를 구성하려면 다음 단계를 따르세요.

1. 다음 코드를 사용하여 필요한 종속 항목을 애플리케이션에 추가합니다.

   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

   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. OpenTelemetry 객체를 구성하고 trace를 사용 설정합니다.

   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)

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

엔드 투 엔드 trace 구성

이 섹션에서는 Spanner 클라이언트 라이브러리에서 엔드 투 엔드 추적을 구성하는 방법을 안내합니다.

1. 다음 코드를 사용하여 필요한 종속 항목을 애플리케이션에 추가합니다.

   Java

   기존 클라이언트 측 trace 종속 항목은 엔드 투 엔드 trace를 구성하는 데 충분합니다. 추가 종속 항목은 필요하지 않습니다.

   Go

   클라이언트 측 trace에 필요한 종속 항목 외에도 다음 종속 항목도 필요합니다.

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

   Node.js

   기존 클라이언트 측 trace 종속 항목은 엔드 투 엔드 trace를 구성하는 데 충분합니다. 추가 종속 항목은 필요하지 않습니다.

   Python

   기존 클라이언트 측 trace 종속 항목은 엔드 투 엔드 trace를 구성하는 데 충분합니다. 추가 종속 항목은 필요하지 않습니다.

2. 엔드 투 엔드 trace를 선택합니다.

   Java

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

   Go

   클라이언트 구성에서 EnableEndToEndTracing 옵션을 사용하여 선택합니다.

   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.Client(project_id, observability_options=observability_options)

3. OpenTelemetry에서 trace 컨텍스트 전파를 설정합니다.

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

엔드 투 엔드 trace 속성

엔드 투 엔드 trace에는 다음 정보가 포함될 수 있습니다.

속성 이름	설명
service.name	속성 값은 항상 spanner_api_frontend입니다.
cloud.region	애플리케이션 요청을 처리하는 Spanner API 프런트엔드의 Google Cloud 클라우드 리전입니다.
gcp.spanner.server.query.fingerprint	속성 값은 쿼리 지문입니다. 이 쿼리를 추가로 디버그하려면 쿼리 통계 표에서 TEXT_FINGERPRINT 열을 참고하세요.
gcp.spanner.server.paxos.participantcount	트랜잭션과 관련된 참여자 수입니다. 자세한 내용은 Spanner 읽기 및 쓰기 수명을 참고하세요.
gcp.spanner.isolation_level	속성 값은 트랜잭션의 격리 수준입니다. 가능한 값은 SERIALIZABLE 및 REPEATABLE_READ입니다. 자세한 내용은 격리 수준 개요를 참고하세요.

샘플 trace

엔드 투 엔드 trace를 사용하면 다음 세부정보를 확인할 수 있습니다.

• 애플리케이션과 Spanner 간의 지연 시간입니다. 네트워크 지연 시간을 계산하여 네트워크 문제가 있는지 확인할 수 있습니다.
• 애플리케이션 요청이 처리되는 Spanner API 프런트엔드 클라우드 리전입니다. 이를 사용하여 애플리케이션과 Spanner 간의 리전 간 호출을 확인할 수 있습니다.

다음 예시에서 애플리케이션 요청은 us-west1 리전의 Spanner API 프런트엔드에서 처리되고 있으며 네트워크 지연 시간은 8.542밀리초(55.47밀리초 - 46.928밀리초)입니다.

다음 단계

• OpenTelemetry에 대한 자세한 내용은 OpenTelemetry 문서 참고하기