如需端到端监控和调试 Datastore 模式 Firestore (Datastore) 请求，您可以在 Java 客户端库中启用轨迹。客户端跟踪可以提供有关应用所体验的性能的信号，以及有助于调试问题的分析洞见。
客户端轨迹是通过从客户端执行 RPC 收集的，可提供以下信息：
- 包含客户端发送 RPC 请求和客户端收到 RPC 响应的时间戳的跨度，包括网络和客户端系统引入的延迟时间
- 用于显示客户端及其配置信息的属性（键值对）。
- 与跨度中的关键事件关联的日志。
- 客户端发生崩溃时的堆栈轨迹。
OpenTelemetry
Java 客户端库的轨迹是使用 OpenTelemetry API 插桩的。OpenTelemetry 是一项业界标准的开源可观测性框架。OpenTelemetry 提供了各种工具，例如插桩 API 和 SDK、收集器、特定于后端的导出器，以及抽样控制、span 限制等灵活的配置选项。
使用导出工具和收集器导出轨迹
在配置过程中，您可以将轨迹导出到可观测性后端。大多数可观测性服务提供商都提供可供您使用的导出器，例如 Cloud Trace。
除了导出器之外，OpenTelemetry 还建议设置收集器。借助收集器，您的服务可以快速分流数据，并让收集器负责处理重试、批处理和加密等其他处理。收集器会与您的应用一起运行。收集器会接收 OpenTelemetry 协议 (OTLP) 消息、处理这些消息，并将其导出到可观测性后端。
限制
轨迹跨度仅适用于 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。
配置客户端轨迹
本部分提供了客户端轨迹的示例配置。您可以导出到 Collector，也可以直接导出到可观测性后端。 您还可以使用以下选项配置客户端轨迹：
- 您可以使用 OpenTelemetry API 配置轨迹。这需要对应用进行代码更改。请参阅以下示例：
- 您可以使用自动代理配置轨迹，而无需更改代码。您需要设置环境变量
DATASTORE_ENABLE_TRACING=ON。您还需要设置其他配置设置，如代理配置中所述。请参阅以下示例：
使用 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
使用自动代理直接导出到可观测性后端
除了设置环境变量 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 示例
事件日志示例
属性值示例
