Trace 내보내기 도구에서 OTLP 엔드포인트로 마이그레이션

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

이 문서에서는 수동 계측을 사용할 때 trace 데이터를 내보내는 방법을 설명합니다. 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 프로젝트에 저장됩니다.

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

참고: Telemetry API는 trace 데이터만 허용합니다. 이 엔드포인트를 사용하여 측정항목 또는 로그 데이터를 Google Cloud 프로젝트로 전송할 수 없습니다.

시작하기 전에

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

결제 및 Telemetry API 사용 설정

참고: Telemetry API는 기본적으로 사용 중지되어 있습니다.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

권한 구성

• 샘플 애플리케이션이 로그, 측정항목, trace 데이터를 프로젝트로 전송하도록 허용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

  • Cloud 원격 분석 trace 작성자(roles/telemetry.tracesWriter)
  • 로그 작성자(roles/logging.logWriter)
  • 모니터링 측정항목 작성자(roles/monitoring.metricWriter)
  참고: 애플리케이션이 서비스 계정을 사용하는 기본 애플리케이션 사용자 인증 정보 (ADC)를 사용하도록 구성하는 경우 서비스 계정에 이전 IAM 역할을 부여하세요. 자세한 내용은 애플리케이션 기본 사용자 인증 정보의 작동 방식 및 로컬 개발 환경을 위한 애플리케이션 기본 사용자 인증 정보 (ADC) 설정을 참고하세요.

• 로그, 측정항목, trace 데이터를 보는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

  • 로그 뷰어(roles/logging.viewer)
  • 모니터링 뷰어(roles/monitoring.viewer)
  • Cloud Trace 사용자(roles/cloudtrace.user)

  역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

  커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

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

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

종속 항목 추가

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

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 trace 내보내기 도구 대신 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 모듈을 사용하는 경우 Google Cloud Authentication Extension을 사용하는 것이 좋습니다. 이 확장 프로그램을 사용하는 전체 예시는 Google 인증을 사용한 OTLP Trace 예시를 참조하세요.

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 리소스 속성 구성

프로젝트를 지정하는 키-값 쌍을 OTEL_RESOURCE_ATTRIBUTES 환경 변수에 추가합니다. 키에는 gcp.project_id을 사용합니다. 값에는 Google Cloud 프로젝트의 ID를 사용합니다.

예:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

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

할당량 프로젝트 ID 설정

할당량 프로젝트는 Google Cloud API 요청 사용량을 추적하는 프로젝트입니다. 원격 분석 API는 클라이언트 기반 API이므로 인증 방법에 따라 할당량 프로젝트가 자동으로 식별되는지 여부가 결정됩니다. 예를 들어 인증에 서비스 계정을 사용하는 경우 할당량 프로젝트를 지정할 필요가 없습니다. 하지만 사용자 인증 정보가 인증에 사용되는 경우 할당량 프로젝트를 지정해야 합니다.

환경 변수를 사용하여 할당량 프로젝트를 설정할 수 있습니다. 프로그래밍 언어에 설정할 환경 변수를 확인하려면 환경 변수를 사용하여 할당량 프로젝트 설정을 참고하세요.

예를 들어 Go의 경우 다음과 같이 할당량 프로젝트를 설정할 수 있습니다.

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

인증 오류를 해결하는 방법은 사용자 인증 정보가 작동하지 않음을 참고하세요.

참고: 키 x-goog-user-project를 사용하는 키-값 쌍으로 OTEL_EXPORTER_OTLP_HEADERS 환경 변수를 업데이트하지 마세요. 이 구성으로 인해 요청에 중복 값이 발생할 수 있으며, 이로 인해 API 명령어가 실패합니다.

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

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

예시:

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

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