使用客户端轨迹监控性能

预览版

此功能 受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

如需端到端地监控和调试 Datastore 模式 Firestore (Datastore) 请求，您可以在 Java 客户端库中启用轨迹。客户端跟踪记录可提供有关应用体验到的性能的信号，以及有助于调试问题的分析洞见。

客户端跟踪记录通过从客户端执行 RPC 来收集，可提供以下信息：

• 包含客户端发送 RPC 请求的时间和客户端收到 RPC 响应的时间的时间戳，包括网络和客户端系统造成的延迟
• 提供有关客户端及其配置的信息的属性（键值对）。
• 与 span 中的关键事件相关联的日志。
• 如果客户端发生崩溃，则为堆栈轨迹。

OpenTelemetry

Java 客户端库的跟踪记录通过 OpenTelemetry API 进行插桩。OpenTelemetry 是一项业界标准，也是一个开源可观测性框架。OpenTelemetry 提供各种工具，例如插桩 API 和 SDK、收集器、特定于后端的导出器，以及灵活的配置选项，例如采样控制、span 限制等。

使用导出器和收集器导出跟踪记录

在配置过程中，您可以将跟踪记录导出到可观测性后端。大多数可观测性服务提供商都会提供导出器供您使用，例如 Cloud Trace。

除了导出器之外，OpenTelemetry 还建议设置收集器。借助收集器，您的服务可以快速分流数据，并让收集器负责其他处理工作，例如重试、批处理和加密。收集器与您的应用一起运行。收集器接收 OpenTelemetry 协议 (OTLP) 消息、处理消息，并将其导出到可观测性后端。

限制

跟踪记录 span 仅适用于 Java 客户端库。

结算

除了 Datastore 用量之外，客户端跟踪记录可能会产生费用。

收集轨迹或使用 OpenTelemetry 框架不会产生任何费用。

将跟踪记录 span 注入到可观测性后端可能需支付费用。例如，如果您使用 Cloud Trace 作为后端，则需按 Cloud Trace 价格支付费用。 如果您使用其他可观测性服务提供商，请了解其结算模式和相关费用。

为了更好地了解结算，请先根据流量设置较小的跟踪记录采样比率（跟踪一小部分 RPC）。

准备工作

准备工作：

• 确保您为应用向可观测性后端写入轨迹所使用的服务账号设置了必要的 Identity and Access Management 角色：

  跟踪操作	IAM 角色
  读取轨迹	roles/cloudtrace.user
  写入轨迹	roles/cloudtrace.agent
  读写轨迹	roles/cloudtrace.admin

• 验证此项目是否已启用 Trace API。

配置客户端跟踪记录

本部分提供了客户端轨迹的配置示例。您可以将跟踪记录导出到收集器，也可以直接导出到可观测性后端。 您还可以通过以下方式配置客户端轨迹：

• 您可以使用 OpenTelemetry API 配置轨迹。这需要对应用进行代码更改。请参阅以下示例：
  • 使用 OpenTelemetry API 导出到收集器
  • 使用 OpenTelemetry API 直接导出到可观测性后端
• 您可以使用自动代理配置轨迹，而无需更改代码。您需要设置环境变量 DATASTORE_ENABLE_TRACING=ON。您还需要按照代理配置中的说明设置其他配置。请参阅以下示例：
  • 导出到具有自动代理的收集器
  • 使用自动代理直接导出到可观测性后端

使用 OpenTelemetry API 将轨迹导出到收集器

以下代码将 Datastore Java 客户端库配置为以 10% 的抽样比将 span 导出到 OpenTelemetry 收集器。

Java

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
  OtlpGrpcSpanExporter
  .builder()
  .setEndpoint("http://localhost:4317") // Replace with your OTLP endpoint
  .build();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
  BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

    

使用 OpenTelemetry API 直接导出到可观测性后端

以下代码将 Java 客户端库配置为直接将跟踪记录 span 导出到 Cloud Trace，并将跟踪记录抽样比率设置为 10%。您可以使用其他可观测性服务提供商的导出器直接导出到其后端。如果您的可观测性后端支持 OTLP 提取，您可以使用 OpenTelemetry OtlpGrpcSpanExporter 导出到后端，而不是使用自定义导出器。

Java

// TraceExporter needed for this use case
import com.google.cloud.opentelemetry.trace.TraceExporter;

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());
SpanExporter gcpTraceExporter = TraceExporter.createWithDefaultConfiguration();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
SpanProcessor gcpBatchSpanProcessor =
  BatchSpanProcessor.builder(gcpTraceExporter).build();

// Export directly to Cloud Trace with 10% trace sampling ratio
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

    

使用自动代理导出到收集器

运行 OpenTelemetry 收集器，并启用 OTLP gRPC 接收器。将代理的导出器设置为 otlp，并指定代理应将数据导出到的端点。以下示例使用 10% 的抽样比，并将轨迹发送到监听本地主机端口 4317 的收集器。

终端

DATASTORE_ENABLE_TRACING=ON                            \
java                                                   \
-javaagent:path/to/opentelemetry-javaagent.jar         \
-Dotel.traces.exporter=otlp                            \
-Dotel.exporter.otlp.endpoint="http://localhost:4317"  \
-Dotel.traces.sampler=traceidratio                     \
-Dotel.traces.sampler.arg=0.1                          \
-Dotel.service.name="My App"                           \
-jar myapp.jar

    

使用自动代理直接导出到可观测性后端

除了设置环境变量 DATASTORE_ENABLE_TRACING=ON 之外，您还需要为特定后端添加 OpenTelemetry Java 代理扩展程序。以下示例使用了跟踪记录导出器扩展程序和 10% 的跟踪记录抽样比率。

终端

DATASTORE_ENABLE_TRACING=ON                                                \
java                                                                       \
-javaagent:path/to/opentelemetry-javaagent.jar                             \
-Dotel.javaagent.extensions=/path/to/exporter-auto-0.26.0-alpha-shaded.jar \
-Dotel.traces.exporter=google_cloud_trace                                  \
-Dotel.traces.sampler=traceidratio                                         \
-Dotel.traces.sampler.arg=0.1                                              \
-Dotel.service.name="My Application"                                       \
-jar myapp.jar

    

跟踪记录示例

以下示例展示了跟踪信息在 Cloud Trace 中的显示方式。 如需详细了解可能的属性和值，请参阅跟踪 span 属性和事件。

跟踪 span 示例

事件日志示例

属性值示例

后续步骤

• 查看轨迹跨度属性和事件的参考。
• 了解服务器端监控。