Java 和 OpenTelemetry

此页面适用于希望使用 OpenTelemetry 收集 Java 应用的 Cloud Trace 数据的开发者。OpenTelemetry 是一个供应商中立的插桩框架，可用于收集跟踪记录和指标数据。如需了解如何对代码进行插桩，请参阅插桩和可观测性。

  • 安装 OpenTelemetry 软件包。
  • 配置应用以将 span 导出到 Cloud Trace。
  • 配置您的平台。

如需了解版本信息，请参阅以下内容：

如需了解 OpenTelemetry 参考内容，请参阅以下内容：

有关适用于 Java 的 OpenTelemetry 的最新详细信息以及其他文档和示例，请参阅 OpenTelemetry。

准备工作

  • 您必须使用 Java 8 或更高版本。

  • 在 Google Cloud 控制台的导航面板中，选择 API 和服务，点击启用 API 和服务，然后启用 Cloud Trace API：

    转到 Cloud Trace API 设置

  • 如果系统显示 API 已启用，则表示此 API 已经启用。如未显示，请点击启用按钮。

安装 OpenTelemetry 软件包

如需收集跟踪记录，请将 OpenTelemetry 跟踪和适用于 OpenTelemetry 的 Cloud Trace 导出器添加到应用的 Maven 或 Gradle 文件中：

  • 如需查看最近发布的 OpenTelemetry 依赖项列表，请参阅 Maven 和 Gradle。

  • 如需了解所需的导出器依赖项，请参阅下表：

    Maven

    <dependency>
  <groupId>com.google.cloud.opentelemetry</groupId>
  <artifactId>exporter-trace</artifactId>
  <version>0.15.0</version>
</dependency>

    前面的语句指定了导出器版本。请务必选择最新的导出器版本。

    Gradle

    implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'

    上一个语句指定了导出器版本。请务必选择最新的导出器版本。

配置将 span 导出到 Cloud Trace

如需导出收集的 Trace 数据，请使用 TraceExporter 对象。下面说明了如何使用默认配置创建此对象：

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

您还可以指定配置，然后将其传递给导出器。例如，以下代码用于设置 Google Cloud 项目：

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

配置导出器后，请设置 TracerProvider：

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

在前面的示例中，调用 BatchSpanProcessor 会将提供程序配置为通过后台进程发送 span。

如需了解如何设置身份验证字段，请参阅适用于 OpenTelemetry 的 Cloud Trace 导出器的设置部分。

创建 span

如需了解如何配置应用以捕获跟踪记录 span，请参阅 OpenTelemetry 跟踪记录。本页面介绍了如何进行以下所有操作：

  • 创建 span
  • 创建嵌套的 Span
  • 设置 span 属性
  • 使用事件创建 span
  • 创建包含链接的 span

配置采样

如需了解如何配置跟踪记录的采样时间，请参阅 OpenTelemetry Sampler。本页介绍您可以使用的采样选项。

示例应用

如需查看示例应用，请参阅 TraceExporterExample.java。

配置平台

您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

在 Google Cloud 上运行

当您的应用在 Google Cloud 上运行时，您无需向客户端库提供服务账号形式的身份验证凭据。但是，您需要确保 Google Cloud Platform 已启用 Cloud Trace API 访问权限范围。

如需查看受支持的 Google Cloud 环境的列表，请参阅环境支持。

对于以下配置，默认的访问权限范围设置会启用 Cloud Trace API：

  • App Engine 柔性环境

  • App Engine 标准环境

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

如果您使用自定义访问权限范围，则必须确保已启用 Cloud Trace API 访问权限范围：

  • 如需了解如何使用 Google Cloud 控制台为您的环境配置访问权限范围，请参阅配置 Google Cloud 项目。

  • 对于 gcloud 用户，请使用 --scopes 标志指定访问权限范围，并添加 trace.append Cloud Trace API 访问权限范围。例如，如需创建仅启用了 Cloud Trace API 的 GKE 集群，请执行以下操作：

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

在本地和其他位置运行

如果您的应用在 Google Cloud 之外运行，则必须向客户端库提供服务账号形式的身份验证凭据。该服务账号必须包含 Cloud Trace Agent 角色。如需查看说明，请参阅创建服务账号。

Google Cloud 客户端库使用应用默认凭据 (ADC) 查找应用的凭据。

您可以通过以下三种方式之一提供这些凭据：

  • 运行：gcloud auth application-default login

  • 将服务帐号放置在操作系统的默认路径中。 下面列出了 Windows 和 Linux 的默认路径：

    • Windows：%APPDATA%/gcloud/application_default_credentials.json

    • Linux：$HOME/.config/gcloud/application_default_credentials.json

  • 将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号的路径：

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell：

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

查看跟踪记录

在 Google Cloud 控制台的导航面板中，选择 Trace，然后选择 Trace 探索器：

转到 Trace 探索器

问题排查

如需了解如何排查 Cloud Trace 的问题，请转到“问题排查”页面。

资源