从 Trace 导出器迁移到 OTLP 端点

本文档介绍了如何配置 OpenTelemetry SDK 将跟踪记录数据进程内导出到您的 Google Cloud 项目 。Java、Go、Python 和 Node.js 的示例展示了如何在使用手动插桩时配置 SDK 以将跟踪记录数据发送到 Telemetry (OTLP) API。对于 每种语言，该页面都提供了有关如何使用 OTLP 导出器通过 受支持的导出协议发送跟踪记录数据的信息。

本页面中所述的插桩仅适用于跟踪记录数据。它 不会将日志或指标数据发送到您的 Google Cloud 项目。

如果您的应用依赖 OpenTelemetry 收集器将跟踪记录数据发送到您的 Google Cloud 项目，则本文档不适用：

为什么应进行迁移

OpenTelemetry SDK 会以通常与OpenTelemetry 协议定义的 proto 文件一致的格式生成日志、指标和跟踪记录数据。不过，在存储之前，字段可能会从 OpenTelemetry 特定的数据类型转换为 JSON 数据类型。

当应用使用 Google Cloud 导出器将该数据导出到 Google Cloud 项目时，该导出器会执行以下步骤：

  1. 将记录的数据从 OTLP 格式转换为由 Cloud Logging API、Cloud Monitoring API 或 Cloud Trace API 定义的专有格式。
  2. 将转换后的数据发送到相应的 API，随后存储在您的 Google Cloud 项目中。

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

可用示例

本页面中引用的示例应用可在 GitHub 中找到。 大多数应用都配置为使用 gRPC 导出跟踪记录数据，这意味着它们通过 HTTP/2 连接使用 gRPC 线格式使用 protobuf 编码的数据。此外，还为配置为通过 HTTP 连接将跟踪记录数据导出为 protobuf 编码的数据的应用提供了示例代码：

  • Java 应用

    示例应用配置为通过 HTTP 连接将跟踪记录导出为 protobuf 编码的数据。 如果您偏好使用 gRPC，则此示例中的插桩适用。不过，您需要修改自动配置模块使用的系统属性。示例应用指定了 http/protobuf 导出器。如需使用 gRPC，请将此设置更改为 grpc。

    我们建议您的 Java 应用（如示例应用）使用 OpenTelemetry SDK 自动配置模块 来配置 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

  1. 登录您的 Google Cloud 账号。如果您是新手 Google Cloud， 请创建一个账号来评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. 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

  6. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

配置权限

手动插桩迁移指南

本部分介绍了如何修改应用，使其能够使用 Telemetry API 将跟踪记录数据发送到您的 Google Cloud 项目。您无法将指标或日志数据发送到此端点。

添加依赖项

第一步是在应用中添加 OpenTelemetry OTLP 跟踪记录导出器的依赖项。选择适合您的应用和构建系统的依赖项版本。

Java

对于 Java 应用，请在 build.gradle 脚本中添加以下依赖项：

implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.62.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.62.0")

Go

本部分说明了在使用 gRPC 进行导出时需要对依赖项进行的更改。如果您通过 HTTP 连接使用 protobuf 编码的数据进行导出，请将 otlptracehttp 软件包作为依赖项。如需了解详情， 请参阅使用 HTTP 的 Go 应用。

对于使用 gRPC 进行导出的 Go 应用，请更新 go.mod 文件以添加以下依赖项：

require (
	// ...
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0
)

Python

本部分说明了在使用 gRPC 进行导出时需要对依赖项进行的更改。如果您通过 HTTP 连接使用 protobuf 编码的数据进行导出，请将 opentelemetry-exporter-otlp-proto-http 软件包作为要求。如需了解详情，请参阅Python 代码库。

对于使用 gRPC 进行导出的 Python 应用，请安装以下依赖项或更新 requirements.txt 文件：

opentelemetry-exporter-otlp-proto-grpc==1.42.1
grpcio==1.80.0

Node.js

本部分说明了在使用 gRPC 进行导出时需要对依赖项进行的更改。如果您通过 HTTP 连接使用 protobuf 编码的数据进行导出，请将 @opentelemetry/exporter-trace-otlp-proto 软件包作为依赖项。如需了解详情，请参阅Node.js 应用。

对于使用 gRPC 导出跟踪记录数据的 Node.js 应用，请添加以下依赖项：

"@opentelemetry/exporter-trace-otlp-grpc": "0.221.0",
"@grpc/grpc-js": "1.14.4"

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

更新您的应用代码，以便 OpenTelemetry SDK 配置为使用 OpenTelemetry OTLP 导出器，而不是 Google Cloud 跟踪记录导出器。所需的更改因语言而异。

Java

对于 Java 应用，请执行以下操作：

  1. 添加以下 import 语句：

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

  2. 更新应用代码以使用 OpenTelemetry SDK 自动配置模块 来配置 SDK：

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

  // ...
}

  3. 配置自动配置模块在运行时使用的系统属性。该模块使用这些属性来引导 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=otlptrace-example',
	'-Dotel.exporter.otlp.protocol=http/protobuf