此页面由 Cloud Translation API 翻译。

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

如需端到端监控和调试 Firestore 请求，您可以在 Java 客户端库中启用轨迹。客户端跟踪可以提供您的应用体验到的性能的有助于调试问题。

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

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

OpenTelemetry

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

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

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

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

限制

客户端轨迹存在以下限制：

跟踪记录 span 适用于 Java 客户端库。
客户端库不会为实时监听器生成跟踪 span。

结算

除了 Firestore 使用量之外，客户端跟踪还可能会产生费用。

收集跟踪记录或使用 OpenTelemetry 不收取任何费用框架。

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

要更好地了解结算，请先查看以较低的跟踪采样率（跟踪较小比例的 RPC）为基础您的流量

准备工作

准备工作：

请务必设置您的应用将轨迹写入可观测性后端的服务账号，并为其授予必要的 Identity and Access Management 角色：

跟踪记录操作 IAM 角色

读取轨迹 roles/cloudtrace.user

写入轨迹 roles/cloudtrace.agent

读写轨迹 roles/cloudtrace.admin
请验证是否已对此项目启用 Trace API。

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

配置客户端轨迹

本部分提供了客户端轨迹的示例配置。您可以导出到收集器或直接导出到可观测性后端。您还可以使用以下选项配置客户端轨迹：

您可以使用 OpenTelemetry API 配置轨迹。这需要输入代码对应用的更改请参阅以下示例：
- 使用 OpenTelemetry API 导出到收集器
- 使用 OpenTelemetry API 直接导出到可观测性后端
您可以使用自动代理配置轨迹，而无需更改代码。您需要设置环境变量 FIRESTORE_ENABLE_TRACING=ON。您还需要指定其他配置设置如代理配置中所述。请参阅以下示例：
- 使用自动代理将数据导出到收集器
- 使用自动代理直接导出到可观测性后端

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

以下代码将 Firestore 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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

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

启用 OTLP gRPC 接收器，运行 OpenTelemetry 收集器。将代理的导出器设置为 otlp，并指定代理应将数据导出到的端点。以下示例使用 10% 的采样率，跟踪到监听 localhost 端口 4317 的收集器。

终端


FIRESTORE_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 直接导出到可观测性后端

除了设置环境变量 FIRESTORE_ENABLE_TRACING=ON 之外，您还需要为特定后端添加 OpenTelemetry Java 代理扩展。以下示例使用 Trace 导出器扩展程序轨迹采样率为 10%。

终端


FIRESTORE_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                                              \