Trace 내보내기 도구에서 OTLP 엔드포인트로 이전

이 문서에서는 OpenTelemetry로 계측되고 Google Cloud 내보내기 도구를 사용하는 애플리케이션을 OpenTelemetry의 OTLP 내보내기 도구를 사용하도록 이전하는 방법을 설명합니다. 두 구성 모두 Google Cloud 프로젝트에 원격 분석을 전송합니다. 이 문서의 단계는 OpenTelemetry SDK에서 실행하는 인프로세스 내보내기에 관한 것입니다.

이 문서에서는 수동 계측을 사용할 때 추적 데이터를 내보내는 방법을 설명합니다. Java, Go, Python에 제공되는 이 안내는 Google Cloud 프로젝트로 로그 또는 측정항목 데이터를 전송하는 데 적용되지 않습니다.

이전해야 하는 이유

OpenTelemetry SDK는 OTLP 형식으로 로그, 측정항목, trace 데이터를 생성합니다. 애플리케이션이 Google Cloud 내보내기를 사용하여 해당 데이터를Google Cloud 프로젝트로 내보내면 내보내기는 다음 단계를 실행합니다.

  1. 기록된 데이터를 OTLP 형식에서 Cloud Logging API, Cloud Monitoring API 또는 Cloud Trace API에서 정의한 독점 형식으로 변환합니다.
  2. 변환된 데이터를 적절한 API로 전송하며, 이 데이터는 Google Cloud 프로젝트에 저장됩니다.

추적 데이터의 경우 데이터 변환이 필요하지 않으므로 원격 분석 (OTLP) API를 사용하여 데이터를 내보내도록 애플리케이션을 이전하는 것이 좋습니다. 데이터 변환으로 인해 일부 데이터가 손실될 수 있습니다. 예를 들어 독점 형식의 특정 필드에는 하한이 적용될 수 있으며 일부 OTLP 필드는 독점 형식의 필드에 매핑되지 않을 수 있습니다.

시작하기 전에

애플리케이션을 마이그레이션하여 OTLP 엔드포인트로 추적 데이터를 전송하기 전에 원격 분석 API를 사용 설정하고 필요한 Identity and Access Management (IAM) 역할이 부여되었는지 확인하세요. 서비스 계정에 IAM 역할을 부여해야 할 수도 있습니다.

원격 분석 API 사용 설정

프로젝트에 원격 분석 API, Cloud Logging API, Cloud Monitoring API, Cloud Trace API가 사용 설정되어 있는지 확인합니다. 원격 분석 API는 기본적으로 사용 중지되어 있습니다.

Google Cloud 콘솔

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Google Cloud CLI

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

권한 구성

수동 계측 마이그레이션 가이드

이 섹션에서는 원격 분석 API를 사용하여 추적 데이터를 Google Cloud 프로젝트로 전송하도록 애플리케이션을 수정하는 방법을 설명합니다. 이 엔드포인트로 측정항목 또는 로그 데이터를 전송할 수 없습니다.

종속 항목 추가

첫 번째 단계는 애플리케이션에 OpenTelemetry의 OTLP 추적 내보내기 도구의 종속 항목을 추가하는 것입니다. 애플리케이션 및 빌드 시스템에 적합한 종속 항목 버전을 선택합니다.

Java

Gradle 빌드 시스템을 사용하는 Java 애플리케이션의 경우:

// build.gradle
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.47.0")

Go

Golang 애플리케이션의 경우 go.mod 파일에 다음 종속 항목이 있는지 확인합니다.

// go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.34.0
  // Alternatively, for export using http/protobuf protocol, use:
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.34.0
)

Python

Python 애플리케이션의 경우 다음 종속 항목을 설치하거나 requirements.txt 파일을 업데이트합니다.

# Requirements.txt - use appropriate versions
#
# OTLP exporter that uses grcp protocol for export
opentelemetry-exporter-otlp-proto-grpc==1.30.0
grpcio==1.70.0
# Alternatively, for export using http/protobuf protocol, use:
opentelemetry-exporter-otlp-proto-http==1.30.0

Google Cloud 내보내기 도구 사용을 OTLP 내보내기 도구로 대체

OpenTelemetry SDK가 Google Cloud 추적 내보내기 도구 대신 OpenTelemetry OTLP 내보내기 도구를 사용하도록 애플리케이션 코드를 업데이트합니다. 필요한 변경사항은 언어에 따라 다릅니다.

Java

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Initialize the OTLP gRPC exporter
    SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

    // Initialize OpenTelemetry tracer provider
    SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
        .setResource(resource)
        .setSampler(Sampler.traceIdRatioBased(0.02))
        .addSpanProcessor(
            BatchSpanProcessor.builder(otlpGrpcSpanExporter)
                .setScheduleDelay(100, TimeUnit.MILLISECONDS)
                .build());

    // Configure OpenTelemetry SDK instacne to use the tracer provider
    // configured with OTLP exporter
    OpenTelemetrySdk openTelemetrySdk =
        OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .build();
}

Go

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    // other dependencies
)

// Initializes OpenTelemetry with OTLP exporters
func init() {
    ctx := context.Background()

    // Initialize the OTLP gRPC exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        panic(err)
    }
    // initialize OpenTelemetry tracer provdier
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.02)),
        sdktrace.WithBatcher(exporter)
    )

    // configure OpenTelemetry SDK instance to use the tracer provider
    // configured with OTLP exporter
    otel.SetTracerProvider(tp)
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Initialize the OTLP gRPC or http exporter
    otlp_grpc_exporter = OTLPSpanExporter()

    # Initialize OpenTelemetry TracerProvider
    trace_provider = TracerProvider(resource=resource).add_span_processor(
    BatchSpanProcessor(otlp_grpc_exporter)
    )

    # Configure OpenTelemetry tracing API with the initialized tracer provider
    trace.set_tracer_provider(trace_provider)

인증 구성

OpenTelemetry SDK 구성의 이전 변경사항을 통해 애플리케이션은 gRPC 또는 HTTP를 사용하여 OpenTelemetry OTLP 내보내기 도구를 사용하여 trace를 내보내도록 구성됩니다. 그런 다음 이러한 트레이스를 Google Cloud 프로젝트로 전송하도록 내보내기를 구성해야 합니다.

인증을 구성하려면 다음 단계를 따르세요.

  1. 내보내기 호출에 대한 인증 헤더를 구성합니다.
  2. 필요한 OpenTelemetry 리소스 속성 및 OTLP 헤더를 구성합니다.
  3. 내보내기 도구 엔드포인트를 구성합니다.

이 섹션에서는 각 단계를 자세히 설명합니다.

내보내기 호출의 인증 헤더 구성

Google Cloud 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 내보내기 도구를 구성하려면 언어별 Google 인증 라이브러리를 추가하세요.

Java

Trace에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

// build.gradle
// Google Auth Library
implementation("com.google.auth:google-auth-library-oauth2-http:1.32.1")

Go

Trace에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

// go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.70.0
    // When using http based OTLP exported, use explicit auth library
    golang.org/x/oauth2 v0.26.0
)

Python

Trace에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

# requirements.txt
# Google Auth Library
google-auth==2.38.0

다음으로, 라이브러리에서 가져온 승인 토큰을 헤더에 추가하도록 OTLP 스팬 내보내기 도구를 생성하는 애플리케이션 코드를 업데이트합니다. 이 단계는 언어에 따라 다르지만 구현은 모든 언어에서 비슷합니다.

Java

OpenTelemetry SDK Autoconfigure module을 사용하는 경우 Google Cloud Authentication Extension을 사용하는 것이 좋습니다. 이 확장 프로그램을 사용하는 전체 예시는 Google 인증을 사용한 OTLP 추적 예시를 참고하세요.

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

import com.google.auth.oauth2.GoogleCredentials;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Retrieve and store application-default credentials
    GoogleCredentials credentials;
    try {
       credentials = GoogleCredentials.getApplicationDefault();
    } catch (IOException e) {
      // Handle authentication error
      throw new RuntimeException(e);
    }

    // Update gRPC span exporter to add the authorization headers
    // If you are using the Autoconfigure module, we recommend using
    // Google Cloud Authentication Extension.
    // See https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-auth-extension
    SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setHeaders(
                () -> {
                  Map<String, List<String>> gcpHeaders;
                  try {
                    credentials.refreshIfExpired();
                    gcpHeaders = credentials.getRequestMetadata();
                  } catch (IOException e) {
                    // Handle authentication error
                    throw new RuntimeException(e);
                  }
                  Map<String, String> flattenedHeaders =
                      gcpHeaders.entrySet().stream()
                          .collect(
                              Collectors.toMap(
                                  Map.Entry::getKey,
                                  entry ->
                                      entry.getValue().stream()
                                          .filter(Objects::nonNull)
                                          .filter(s -> !s.isEmpty())
                                          .collect(Collectors.joining(",")),
                                  (v1, v2) -> v2));
                  return flattenedHeaders;
                })
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

  // Other OpenTelemetry configuration remains unaffected
}

Go

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/oauth"
)

// Initializes OpenTelemetry with OTLP exporters
func init() {
    ctx := context.Background()

    // Retrieve and store Google application-default credentials
    creds, err := oauth.NewApplicationDefault(ctx)
    if err != nil {
        panic(err)
    }

    // Update the previously created OTLP gRPC span exporter to
    // add authorization headers
    exporter, err := otlptracegrpc.New(
        ctx,
        otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds))
    )

    // Other OpenTelemetry configuration remains unaffected.
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
from google.auth.transport.grpc import AuthMetadataPlugin

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Retrieve and store Google application-default credentials
    credentials, project_id = google.auth.default()
    # Request used to refresh credentials upon expiry
    request = google.auth.transport.requests.Request()

    # Supply the request and credentials to AuthMetadataPlugin
    # AuthMeatadataPlugin inserts credentials into each request
    auth_metadata_plugin = AuthMetadataPlugin(
        credentials=credentials, request=request
    )

    # Initialize gRPC channel credentials using the AuthMetadataPlugin
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Update the previously created OTLP gRPC span exporter to add authorization
    # credentials
    otlp_grpc_exporter = OTLPSpanExporter(credentials=channel_creds)

    # Other OpenTelementry configuration remains unaffected

필수 OpenTelemetry 리소스 속성 및 OTLP 헤더 구성

다음 OpenTelemetry 환경 변수를 설정합니다.

  • OTEL_RESOURCE_ATTRIBUTES: OpenTelemetry 리소스 속성에서 gcp.project_id 키를 설정하도록 이 환경 변수를 구성합니다. 값은 Google Cloud 프로젝트의 ID여야 합니다.

예:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

OpenTelemetry 환경 변수에 대한 자세한 내용은 일반 SDK 구성을 참고하세요.

내보내기 도구 엔드포인트 구성

OTEL_EXPORTER_OTLP_ENDPOINT 환경 변수의 값을 Google Cloud의 OTLP 엔드포인트로 설정합니다.

예:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com

OpenTelemetry 환경 변수에 대한 자세한 내용은 일반 SDK 구성을 참고하세요.