此页面由 Cloud Translation API 翻译。

从轨迹导出器迁移到 OTLP 端点
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

本文档介绍了如何将使用 OpenTelemetry 插桩且依赖于 Google Cloud 导出器的应用迁移为使用 OpenTelemetry 的 OTLP 导出器。这两种配置都会将遥测数据发送到您的 Google Cloud 项目。本文档中的步骤适用于 OpenTelemetry SDK 执行的进程内导出。

本文档介绍了使用手动插桩时如何导出轨迹数据。本指南适用于 Java、Go 和 Python，不适用于将日志或指标数据发送到 Google Cloud 项目。

为什么应进行迁移

OpenTelemetry SDK 会生成 OTLP 格式的日志、指标和跟踪记录数据。当应用使用 Google Cloud 导出器将数据导出到 Google Cloud 项目时，该导出器会执行以下步骤：

将记录的数据从 OTLP 格式转换为 Cloud Logging API、Cloud Monitoring API 或 Cloud Trace API 定义的专有格式。
将转换后的数据发送到适当的 API，然后存储在您的 Google Cloud 项目中。

对于轨迹数据，我们建议您迁移应用，以使用遥测 (OTLP) API 导出数据，因为这种导出不需要数据转换。数据转换可能会导致部分数据丢失。例如，专有格式对某些字段的限制可能较低，或者某些 OLTP 字段可能无法映射到专有格式的字段。

手动插桩迁移指南

本部分介绍了如何修改应用，以便其使用 Telemetry 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 配置为使用 OpenTelemetry OTLP 导出器，而不是跟踪记录导出器。 Google Cloud 所需的更改因语言而异。

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 导出器导出轨迹。接下来，您需要配置导出设置，以将这些轨迹发送到您的 Google Cloud 项目。

如需配置身份验证，请执行以下操作：

为导出调用配置身份验证标头。
配置所需的 OpenTelemetry 资源属性和 OTLP 标头。
配置导出器端点。

本部分详细介绍了这些步骤。

为导出调用配置身份验证标头

如需使用您的 Google Cloud 应用默认凭据 (ADC) 配置导出器，请添加特定于语言的 Google 身份验证库。

Java

如需向 Google Cloud Observability 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

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

Go

如需向 Google Cloud Observability 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

// 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

如需向 Google Cloud Observability 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

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

接下来，更新用于构建 OTLP span 导出程序的应用代码，以便将从库中检索到的授权令牌添加到标头中。此步骤因语言而异，但所有语言的实现方式都类似。

Java

我们建议您在使用 OpenTelemetry SDK Autoconfigure 模块时使用 Google Cloud Authentication Extension。如需查看使用此扩展程序的完整示例，请参阅 OTLP 轨迹与 Google 身份验证示例。

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(() -> {
                try {
                    credentials.refreshIfExpired();
                } catch (IOException e) {
                    // Handle authentication error
                    throw new RuntimeException(e);
                }
                return Map.of("Authorization", "Bearer " + credentials.getAccessToken().getTokenValue());
            })
            .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。
OTEL_EXPORTER_OTLP_HEADERS：配置此环境变量以添加 x-goog-user-project 标头。该值应为将消耗服务配额的 Google Cloud 项目的 ID。通常，此值设置为与 gcp.project_id 键相同的值。

示例：

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"
export OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=QUOTA_PROJECT_ID"

如需详细了解 OpenTelemetry 环境变量，请参阅常规 SDK 配置。

配置导出器端点

将 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量的值设置为 Google Cloud的 OTLP 端点。

示例：

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

如需详细了解 OpenTelemetry 环境变量，请参阅常规 SDK 配置。

所需权限

您可以使用 Identity and Access Management (IAM) 角色和权限，让您或服务账号能够将轨迹数据写入 Telemetry API，并将这些数据存储在您的 Google Cloud 项目中。例如，如果您仅被授予 Cloud Trace 角色或权限，那么您将无法使用 Telemetry API 写入数据。

如需获得让示例应用写入日志、指标和跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：
- Telemetry Writer (roles/telemetry.tracesWriter)
- Logs Writer (roles/logging.logWriter)
- Monitoring Metric Writer (roles/monitoring.metricWriter)

如需获得查看日志、指标和跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：
- Logs Viewer (roles/logging.viewer)
- Monitoring Viewer (roles/monitoring.viewer)
- Cloud Trace User (roles/cloudtrace.user)
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如需了解详情，请参阅应用默认凭据的工作原理和为本地开发环境设置应用默认凭据 (ADC)。

必需的 API

Telemetry API 默认处于停用状态。您必须启用此 API。以下信息介绍了向 Google Cloud 项目发送遥测数据以及查看此类数据所需的 API：

Google Cloud 控制台

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

Enable the APIs

Google Cloud CLI

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

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

从轨迹导出器迁移到 OTLP 端点 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

为什么应进行迁移

手动插桩迁移指南

添加依赖项

Java

Go

Python

将 Google Cloud 导出器替换为 OTLP 导出器

Java

Go

Python

配置身份验证

为导出调用配置身份验证标头

Java

Go

Python

Java

Go

Python

配置所需的 OpenTelemetry 资源属性和 OTLP 标头

配置导出器端点

所需权限

必需的 API

Google Cloud 控制台

Google Cloud CLI

从轨迹导出器迁移到 OTLP 端点
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。