이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

이 문서에서는 OpenTelemetry SDK를 사용하여 Google Cloud 프로젝트로 trace 데이터를 프로세스 내에서 내보내는 방법을 설명합니다. Java, Go, Python, Node.js의 예에서는 수동 계측을 사용할 때 추적 데이터를 원격 분석 (OTLP) API로 전송하도록 SDK를 구성하는 방법을 보여줍니다. 각 언어의 페이지에서는 OTLP 내보내기 도구를 사용하여 지원되는 내보내기 프로토콜을 통해 추적 데이터를 전송하는 방법을 설명합니다.

이 페이지에 설명된 계측은 추적 데이터에만 적용됩니다. Google Cloud 프로젝트로 로그 또는 측정항목 데이터를 전송하지 않습니다.

애플리케이션에서 OpenTelemetry 수집기를 사용하여 Google Cloud 프로젝트로 trace 데이터를 전송하는 경우 이 문서는 적용되지 않습니다.

계측 샘플은 수집기 기반 계측 샘플을 참고하세요.
수집기에 대한 자세한 내용은 Google 기반의 OpenTelemetry Collector를 참고하세요.

마이그레이션해야 하는 이유

OpenTelemetry SDK는 일반적으로 OpenTelemetry OTLP 프로토콜에 의해 정의된 proto 파일과 일치하는 형식으로 로그, 측정항목, trace 데이터를 생성합니다. 하지만 필드는 저장 전에 OpenTelemetry 전용 데이터 유형에서 JSON 데이터 유형으로 변환될 수 있습니다.

애플리케이션이 Google Cloud 내보내기 도구를 사용하여 해당 데이터를 Google Cloud 프로젝트로 내보내면 내보내기 도구는 다음 단계를 실행합니다.

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

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

사용 가능한 샘플

이 페이지에 언급된 샘플 애플리케이션은 GitHub에서 제공됩니다. 대부분의 애플리케이션은 gRPC를 사용하여 추적 데이터를 내보내도록 구성되어 있습니다. 즉, HTTP/2 연결을 통해 gRPC 와이어 형식을 사용하여 protobuf로 인코딩된 데이터를 사용합니다. HTTP 연결을 통해 추적 데이터를 protobuf 인코딩 데이터로 내보내도록 구성된 애플리케이션의 예시 코드도 제공됩니다.

Java 애플리케이션

샘플 애플리케이션은 HTTP 연결을 통해 protobuf로 인코딩된 데이터로 트레이스를 내보내도록 구성되어 있습니다. gRPC를 사용하려면 이 샘플의 계측을 적용하면 됩니다. 하지만 자동 구성 모듈이 사용하는 시스템 속성을 수정해야 합니다. 샘플 애플리케이션은 http/protobuf 내보내기 도구를 지정합니다. gRPC를 사용하려면 이 설정을 grpc로 변경하세요.

샘플 애플리케이션과 같은 Java 애플리케이션은 OpenTelemetry SDK Autoconfigure 모듈을 사용하여 SDK를 구성하는 것이 좋습니다.
gRPC를 사용하는 Go 애플리케이션 및 HTTP를 사용하는 Go 애플리케이션

Go 저장소가 두 개 있습니다. 한 저장소에서 샘플 애플리케이션은 gRPC를 사용합니다. 다른 저장소의 샘플은 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용합니다.
Python 애플리케이션

이 저장소에는 두 가지 샘플이 있습니다. 하나는 gRPC용이고 다른 하나는 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용합니다.
Node.js 애플리케이션

이 저장소에는 두 가지 샘플이 있습니다. 하나는 gRPC용이고 다른 하나는 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용합니다.

시작하기 전에

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

결제 및 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.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

권한 구성

애플리케이션에서 사용하는 서비스 계정에 다음 IAM 역할을 부여합니다.
- Cloud 원격 분석 trace 작성자 (roles/telemetry.tracesWriter)
- 로그 작성자 (roles/logging.logWriter) |
- 모니터링 측정항목 작성자(roles/monitoring.metricWriter)
애플리케이션 기본 사용자 인증 정보 (ADC)에 대해 알아보려면 애플리케이션 기본 사용자 인증 정보의 작동 방식 및 로컬 개발 환경을 위한 애플리케이션 기본 사용자 인증 정보 (ADC) 설정을 참고하세요.

로그, 측정항목, trace 데이터를 보는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
- 로그 뷰어(roles/logging.viewer)
- 모니터링 뷰어(roles/monitoring.viewer)
- Cloud Trace 사용자(roles/cloudtrace.user)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참고하세요.

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

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

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

종속 항목 추가

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

Java

Java 애플리케이션의 경우 build.gradle 스크립트에 다음 종속 항목을 추가합니다.

// use the latest versions
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.56.0")

Go

이 섹션에서는 내보내기에 gRPC를 사용할 때 종속 항목을 변경해야 하는 사항을 설명합니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 otlptracehttp 패키지를 종속 항목으로 포함합니다. 자세한 내용은 HTTP를 사용하는 Go 애플리케이션을 참고하세요.

내보내기에 gRPC를 사용하는 Go 애플리케이션의 경우 다음 종속 항목을 포함하도록 go.mod 파일을 업데이트합니다.

// go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.38.0
)

Python

이 섹션에서는 내보내기에 gRPC를 사용할 때 종속 항목을 변경해야 하는 경우를 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 opentelemetry-exporter-otlp-proto-http 패키지를 요구사항으로 포함합니다. 자세한 내용은 Python 애플리케이션을 참고하세요.

내보내기에 gRPC를 사용하는 Python 애플리케이션의 경우 다음 종속 항목을 설치하거나 requirements.txt 파일을 업데이트합니다.

# Requirements.txt - use appropriate versions
#
# OTLP exporter that uses grcp protocol for export
opentelemetry-exporter-otlp-proto-grpc==1.39.0
grpcio==1.76.0

Node.js

이 섹션에서는 내보내기에 gRPC를 사용할 때 종속 항목을 변경해야 하는 경우를 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 @opentelemetry/exporter-trace-otlp-proto 패키지를 종속 항목으로 포함합니다. 자세한 내용은 Node.js 애플리케이션을 참고하세요.

Node.js 애플리케이션의 경우 gRPC를 사용하여 내보내려면 다음 종속 항목을 추가합니다.

"@opentelemetry/exporter-trace-otlp-grpc": "0.203.0",
"@grpc/grpc-js": "1.13.4",

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

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

Java

Java 애플리케이션의 경우 다음을 실행합니다.

다음 import 문을 추가합니다.

import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

OpenTelemetry SDK Autoconfigure 모듈을 사용하여 SDK를 구성하도록 애플리케이션 코드를 업데이트합니다.

public static void main(String[] args) {
    // Configure the OpenTelemetry pipeline with Auto configuration
    openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
    ...
}

런타임에 자동 구성 모듈이 사용하는 시스템 속성을 구성합니다. 이 모듈은 이러한 속성을 사용하여 SDK를 부트스트랩합니다. 시스템 속성 대신 환경 변수를 사용할 수도 있습니다. 자세한 내용은 환경 변수 및 시스템 속성을 참고하세요.

샘플 애플리케이션은 build.gradle 스크립트에서 시스템 속성을 정의합니다.

// You can switch the desired protocol here by changing `otel.exporter.otlp.protocol`.
def autoconf_config = [
  '-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com',
  '-Dotel.traces.exporter=otlp',
  '-Dotel.logs.exporter=none',
  '-Dotel.metrics.exporter=none',
  '-Dotel.service.name=my-service',
  '-Dotel.exporter.otlp.protocol=http/protobuf',
  '-Dotel.java.global-autoconfigure.enabled=true',
  // ID of your Google Cloud Project, required by the auth extension
  '-Dgoogle.cloud.project=PROJECT_ID',
]

// Now pass the config as JVM arguments to your java application:
application {
        // Replace with the fully qualified name of your Main class.
  mainClassName = 'com.example.Main'
  applicationDefaultJvmArgs = autoconf_config
}

gRPC를 사용하여 추적 데이터를 내보내려면 OTLP 프로토콜을 http/protobuf로 설정하는 대신 grpc로 설정하세요.

Go

이 섹션에서는 내보내기에 gRPC를 사용할 때 적용해야 하는 변경사항을 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 otlptracehttp 패키지를 가져와야 하며 해당 옵션으로 내보내기 도구를 구성해야 합니다. 자세한 내용은 HTTP를 사용하는 Go 애플리케이션을 참고하세요.

내보내기에 gRPC를 사용하는 Go 애플리케이션의 경우 다음 import 문을 추가합니다.

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

또한 초기화 코드를 업데이트하여 gRPC 내보내기 도구로 TraceProvider를 구성합니다.


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

// creds: configure Application Default Credentials

// Initialize the OTLP gRPC exporter
exporter, err := otlptracegrpc.New(ctx)
if err != nil {
  panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
  panic(err)
}

tp := sdktrace.NewTracerProvider(
  // For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
  // In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
  sdktrace.WithSampler(sdktrace.AlwaysSample()),
  sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

이 섹션에서는 내보내기에 gRPC를 사용할 때 적용해야 하는 변경사항을 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 opentelemetry.exporter.otlp.proto.http 패키지에서 가져와야 하며 해당 옵션으로 내보내기 도구를 구성해야 합니다. 자세한 내용은 Python 애플리케이션을 참고하세요.

내보내기에 gRPC를 사용하는 Python 애플리케이션의 경우 다음 가져오기를 추가합니다.

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

또한 초기화 코드를 업데이트하여 gRPC 내보내기 도구로 TraceProvider를 구성합니다.

# Initialize OpenTelemetry with OTLP exporters

# channel_creds: configure Application Default Credentials

trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        credentials=channel_creds,
        endpoint="https://telemetry.googleapis.com:443/v1/traces",
    )
)
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer("my.tracer.name")

Node.js

이 섹션에서는 내보내기에 gRPC를 사용할 때 적용해야 하는 변경사항을 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 @opentelemetry/exporter-trace-otlp-proto 패키지를 가져옵니다. 자세한 내용은 Node.js 애플리케이션을 참고하세요.

내보내기에 gRPC를 사용하는 Node.js 애플리케이션의 경우 다음 가져오기를 추가합니다.

import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';

또한 초기화 코드를 업데이트하여 gRPC 내보내기 도구로 TraceProvider를 구성합니다.


// Express App that exports traces via gRPC with protobuf
async function main() {
  // authenticatedClient: configure Application Default Credentials

  // Configure the TraceExporter
  const sdk = new NodeSDK({
    traceExporter: new OTLPTraceExporter({
      credentials: credentials.combineChannelCredentials(
        credentials.createSsl(),
        credentials.createFromGoogleCredential(authenticatedClient),
      ),
    }),
  });
  sdk.start();
}

인증 구성

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

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

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

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

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

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

Java

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

OpenTelemetry SDK Autoconfigure 모듈을 사용하는 Java 애플리케이션의 경우 Google Cloud Authentication Extension도 사용하는 것이 좋습니다.

// build.gradle
implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha")

Go

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

내보내기에 gRPC를 사용하는 Go 애플리케이션의 경우 다음 종속 항목을 포함하도록 go.mod 파일을 업데이트합니다.

// go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.75.1
)

내보내기에 HTTP를 사용하는 Go 애플리케이션의 경우 다음 종속 항목을 포함하도록 go.mod 파일을 업데이트합니다.

// go.mod file
require (
    // When using http based OTLP exported, use explicit auth library
  golang.org/x/oauth2 v0.31.0
)

Python

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

Python 애플리케이션의 경우 다음 가져오기를 추가합니다.

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

Node.js

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

Node.js 애플리케이션의 경우 다음 종속 항목을 추가합니다.

"google-auth-library": "9.15.1",

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

Java

OpenTelemetry SDK Autoconfigure 모듈과 Google Cloud Authentication Extension을 사용하는 Java 애플리케이션이 있는 경우 애플리케이션 초기화 중에 특별한 단계를 실행할 필요가 없습니다. 자동 구성 모듈은 ADC를 구성하는 데 필요한 단계를 자동으로 실행합니다.

Go

이 섹션에서는 내보내기에 gRPC를 사용할 때 적용해야 하는 변경사항을 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 otlptracehttp 패키지를 가져오고 내보내기를 otlptracehttp 객체로 구성해야 합니다. 자세한 내용은 HTTP를 사용하는 Go 애플리케이션을 참고하세요.

내보내기에 gRPC를 사용하는 Go 애플리케이션의 경우 다음 import 문을 추가합니다.

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    // other dependencies
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/oauth"
)

또한 gRPC 내보내기 도구를 인스턴스화하기 전에 초기화 코드를 업데이트하여 ADC를 구성합니다.

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

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

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
  panic(err)
}

// Other OpenTelemetry configuration remains unaffected.

Python

이 섹션에서는 내보내기에 gRPC를 사용할 때 적용해야 하는 변경사항을 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 기본 사용자 인증 정보를 사용하세요. BatchSpanProcessor를 인스턴스화할 때도 이러한 사용자 인증 정보를 전달해야 합니다. 자세한 내용은 Python 애플리케이션을 참고하세요.

내보내기에 gRPC를 사용하는 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

또한 gRPC 내보내기 도구를 인스턴스화하기 전에 ADC를 구성하도록 초기화 코드를 업데이트합니다.

credentials, _ = google.auth.default()
request = google.auth.transport.requests.Request()
resource = Resource.create(attributes={SERVICE_NAME: "otlp-gcp-grpc-sample"})

auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(),
    grpc.metadata_call_credentials(auth_metadata_plugin),
)

# Configure the TraceProvider

Node.js

이 섹션에서는 내보내기에 gRPC를 사용할 때 적용해야 하는 변경사항을 보여줍니다. 내보내기를 위해 HTTP 연결을 통해 protobuf로 인코딩된 데이터를 사용하는 경우 여기 설명된 내용과 약간 다른 변경사항을 적용해야 합니다. 자세한 내용은 Node.js 애플리케이션에 포함된 app-http-proto-export.ts 파일을 참고하세요.

내보내기에 gRPC를 사용하는 Node.js 애플리케이션의 경우 다음 가져오기를 추가합니다.

import {AuthClient, GoogleAuth} from 'google-auth-library';
import {credentials} from '@grpc/grpc-js';

또한 gRPC 내보내기 도구를 인스턴스화하기 전에 초기화 코드를 업데이트하여 ADC를 구성합니다.

async function getAuthenticatedClient(): Promise<AuthClient> {
  const auth: GoogleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  return await auth.getClient();
}

// Express App that exports traces via gRPC with protobuf
async function main() {
  const authenticatedClient: AuthClient = await getAuthenticatedClient();

  // Configure the TraceExporter
}

필수 OpenTelemetry 리소스 속성 구성

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

예:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Java를 사용하고 샘플 Java 애플리케이션과 같이 Google Cloud 인증 확장 프로그램을 사용하도록 애플리케이션을 구성하는 경우 OpenTelemetry 리소스 속성의 일부로 프로젝트 ID를 설정할 필요가 없습니다. 하지만 이 속성을 설정해도 해롭지는 않습니다.

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

할당량 프로젝트 ID 설정

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

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

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

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

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

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

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

예:

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

Java 및 자동 구성 모듈을 사용하는 경우 샘플 Java 애플리케이션에서와 같이 시스템 속성을 사용하여 내보내기 도구 엔드포인트를 설정할 수 있습니다. 해당 구성에 대해 내보내기 프로그램 환경 변수를 설정할 필요가 없습니다.

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

Trace 내보내기 도구에서 OTLP 엔드포인트로 마이그레이션 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

마이그레이션해야 하는 이유

사용 가능한 샘플

시작하기 전에

결제 및 Telemetry API 사용 설정

권한 구성

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

종속 항목 추가

Java

Go

Python

Node.js

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

Java

Go

Python

Node.js

인증 구성

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

Java

Go

Python

Node.js

Java

Go

Python

Node.js

필수 OpenTelemetry 리소스 속성 구성

할당량 프로젝트 ID 설정

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

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