使用客户端跟踪记录监控性能

预览

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

如需端到端监控和调试 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 价格支付费用。 如果您使用其他可观测性服务提供商，请了解其结算模式和相关费用。

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

准备工作

准备工作：

• 确保您已设置服务帐号，应用将在此账号下将跟踪记录写入可观测性后端，并具有必要的 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 客户端库配置为以 10% 的跟踪记录采样比率将跟踪记录 span 直接导出到 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();

    

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

运行 OpenTelemetry 收集器，并启用 OTLP gRPC 接收器。将代理的导出器设置为 otlp，并指定代理应将数据导出到的端点。以下示例使用 10% 的采样比率，并将跟踪记录发送到在 localhost 端口 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 代理扩展程序。以下示例使用 Trace 导出器扩展程序 和 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 示例

事件日志示例

属性值示例

后续步骤

• 查看 跟踪记录 span 属性和事件的参考。
• 了解服务器端监控。