Java 和 OpenTelemetry

此页面适用于希望使用 OpenTelemetry 收集 Java 应用的 Cloud Trace 数据的开发者。OpenTelemetry 是一组用于收集跟踪记录和指标数据的插桩库;这些库与多个后端协同工作。如需使用 OpenTelemetry 和 Java 收集跟踪记录,请执行以下操作(如本页所述):

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

如需了解版本信息,请参阅以下内容:

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

准备工作

  • 您必须使用 Java 8 或更高版本。
  • 为您的 Google Cloud 项目启用 Cloud Trace API:

    1. 点击下面的按钮,或者在 Google Cloud Console 中,选择 API 和服务,然后选择 Cloud Trace API

      转到 Trace API

    2. Cloud Trace API 页面上,如果显示了启用按钮,请点击该按钮。如果未显示此按钮,则表示所选项目已启用 Cloud Trace API。

安装 OpenTelemetry 软件包

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

  • 如需查看最近发布的 OpenTelemetry 依赖项列表,请参阅 MavenGradle

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

    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。除非您使用的是 Cloud Run,否则我们建议您使用此处理器。Cloud Run 不支持后台进程。

如需了解如何设置身份验证字段,请参阅适用于 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 Console 为您的环境配置访问权限范围,请参阅配置 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) 查找应用的凭据。您可以通过设置 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"

查看跟踪记录

部署后,您可以在 Cloud Console 跟踪记录查看器中查看跟踪记录。

转到“跟踪记录查看器”页面

问题排查

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

资源