使用客户端轨迹监控性能

如需端到端监控和调试 Datastore 模式 Firestore (Datastore) 请求，您可以执行以下操作： 在 Java 客户端库中启用跟踪记录。客户端跟踪可以提供 您的应用体验到的性能的 有助于调试问题。

客户端轨迹是通过从客户端执行 RPC 收集的，可提供以下信息：

  • 包含客户端发送 RPC 请求时间的时间戳和 客户端收到 RPC 响应的时间，包括由 网络和客户端系统
  • 显示客户端相关信息的属性（键值对） 其配置。
  • 与 span 中的关键事件关联的日志。
  • 客户端发生崩溃时的堆栈轨迹。

OpenTelemetry

Java 客户端库的轨迹是使用 OpenTelemetry API 插桩的。OpenTelemetry 是一项业界标准的开源可观测性框架。OpenTelemetry 提供了丰富的工具，例如 Instrumentation API 和 SDK、收集器、特定于后端的导出器和灵活的配置选项 例如抽样控制、跨度限制等。

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

在配置过程中，您可以将跟踪记录导出到 一个可观测性后端大多数可观测性服务提供商都提供可供您使用的导出器，例如 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 将跟踪记录导出到收集器

以下代码会将 Datastore Java 客户端库配置为以 10% 的采样率将跨度导出到 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 客户端库配置为直接导出跟踪记录 以 10% 的跟踪记录采样率跨 Cloud Trace 传输数据。您可以使用其他可观测性服务提供商的导出程序直接导出到其后端。如果您的可观测性后端支持 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();

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

启用 OTLP gRPC 接收器，运行 OpenTelemetry 收集器。将 代理的导出器导出到 otlp，并指定代理应向其所在的端点 导出数据。以下示例使用 10% 的采样率，并将轨迹发送到监听 localhost 端口 4317 的 Collector。

终端

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

使用 Auto Agent 直接导出到可观测性后端

除了设置环境变量 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 示例

从 Cloud Trace 查看的跟踪跨度。

事件日志示例

从 Cloud Trace 查看的跟踪跨度事件日志。

属性值示例

从 Cloud Trace 查看的跟踪片段的属性值。

后续步骤