设置 Java 版 Cloud Trace

您可以使用 OpenCensus 为 Java 应用启用 Cloud Trace。OpenCensus 是一组用于收集兼容多个后端的跟踪记录数据和指标数据的插桩库。有关 Java 版 OpenCensus 的最新详情以及其他文档和示例,请参阅 census-instrumentation/opencensus-java

安装库

如需收集跟踪记录,请将 OpenCensus 跟踪和 Stackdriver 导出器添加到应用 Maven 或 Gradle 文件中:

Maven

<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>0.28.3</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.28.3</version>
  <exclusions>
    <exclusion>
      <groupId>io.grpc</groupId>
      <artifactId>grpc-api</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.28.3</version>
  <scope>runtime</scope>
</dependency>
<dependency>
   <groupId>joda-time</groupId>
   <artifactId>joda-time</artifactId>
   <version>2.10.10</version>
</dependency>
<dependency>
  <groupId>com.google.api</groupId>
  <artifactId>gax-grpc</artifactId>
  <version>2.4.1</version>
</dependency>

Gradle

compile 'io.opencensus:opencensus-api:0.28.3'
compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.28.3'
runtime 'io.opencensus:opencensus-impl:0.28.3'

配置 Stackdriver 导出器

如需导出收集的 Trace 数据,请使用 StackdriverTraceExporter 对象:

public static void createAndRegisterGoogleCloudPlatform(String projectId) throws IOException {
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder().setProjectId(projectId).build());
}

如果您是在 Google Cloud 基础架构上运行,则无需调用 setProjectID 并提供您的 Google Cloud 项目 ID。如果您未设置此字段,则 Java 版客户端库会自动从 Google Cloud 元数据服务器收集此数据。

如果您未在 Google Cloud 基础架构上运行,则必须向应用提供 Google Cloud 项目 ID。

如果您未明确设置 Google Cloud 项目 ID,则 google-cloud Java 库会自动确定环境变量 GOOGLE_CLOUD_PROJECT 是否已设置。如果设置了此变量,则该库将使用 GOOGLE_CLOUD_PROJECT 的值作为您的 Google Cloud 项目 ID。

如需了解详情,请转到 google-cloud-library 指定项目 ID。如需设置此环境变量,请执行以下操作:

Linux 或 macOS

export GOOGLE_CLOUD_PROJECT=your-project-id

Windows

set GOOGLE_CLOUD_PROJECT=your-project-id

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"

添加自定义 Trace span

虽然 OpenCensus 库包含针对几种常用 Web 框架和 RPC 框架的自动集成,但您也可以创建自定义跟踪记录:

private static final Tracer tracer = Tracing.getTracer();

public static void doWork() {
  // Create a child Span of the current Span.
  try (Scope ss = tracer.spanBuilder("MyChildWorkSpan").startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

private static void doInitialWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Doing initial work");
  // ...
}

private static void doFinalWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Hello world!");
  // ...
}

配置与 Cloud Logging 的集成

如需了解如何将 Cloud Trace 数据发送到 Cloud Logging,请参阅与 Cloud Logging 的集成

启用完全采样

默认情况下,在 10000 个跟踪记录中,只有 1 个跟踪记录会被采样

而在开发者环境中,这样的采样率可能过慢,不足以显示您的跟踪记录数据。要对所有跟踪记录进行采样,您可以使用 alwaysSample 选项。

如需启用完全采样,请使用 setSampler 方法并指定 alwaysSample 选项:

public static void doWorkFullSampled() {
  try (Scope ss =
      tracer
          .spanBuilder("MyChildWorkSpan")
          .setSampler(Samplers.alwaysSample())
          .startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

替换自动身份验证

您可以替换自动身份验证和项目选择。例如,以下示例说明了如何创建其凭据在创建后 60 秒过期的导出器:

public static void createAndRegisterWithToken(String accessToken) throws IOException {
  Date expirationTime = DateTime.now().plusSeconds(60).toDate();

  GoogleCredentials credentials =
      GoogleCredentials.create(new AccessToken(accessToken, expirationTime));
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder()
          .setProjectId("MyStackdriverProjectId")
          .setCredentials(credentials)
          .build());
}

配置平台

您可以在 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 的问题,请转到“问题排查”页面

资源