如需端到端地监控和调试 Datastore 模式 Firestore (Datastore) 请求，您可以在 Java 客户端库中启用轨迹。客户端跟踪可以提供有关应用体验到的性能的信号，以及有助于调试问题的分析洞见。
通过从客户端执行 RPC 收集的客户端轨迹可提供以下信息：
- 包含以下时间戳的 span：客户端发送 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 配置跟踪记录。这需要对应用进行代码更改。请参阅以下示例：
- 您可以使用自动代理配置轨迹，而无需更改代码。您需要设置环境变量
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 示例
事件日志示例
属性值示例
