使用客户端轨迹监控性能
如需端到端监控和调试 Firestore 请求，您可以在客户端库中启用轨迹。客户端跟踪可以提供有关应用所体验的性能的信号，以及有助于调试问题的分析洞见。
客户端轨迹是通过从客户端执行 RPC 收集的，可提供以下信息：
- 包含客户端发送 RPC 请求和客户端收到 RPC 响应的时间戳的跨度，包括网络和客户端系统引入的延迟时间
- 用于显示客户端及其配置信息的属性（键值对）
- 与跨度中的关键事件相关联的日志
- 客户端发生崩溃时的堆栈轨迹
OpenTelemetry
客户端库的轨迹是使用 OpenTelemetry API 插桩的。OpenTelemetry 是一项业界标准的开源可观测性框架。OpenTelemetry 提供了各种工具，例如插桩 API 和 SDK、收集器、后端专用导出器，以及灵活的配置选项（例如抽样控制和 span 限制）。
使用导出工具和收集器导出轨迹
在配置过程中，您可以将轨迹导出到可观测性后端。大多数可观测性服务提供商都提供可供您使用的导出器，例如 Cloud Trace。
除了导出器之外，OpenTelemetry 还建议设置收集器。借助收集器，您的服务可以快速分流数据，并让收集器负责处理重试、批处理和加密等其他处理。收集器会与您的应用一起运行。收集器会接收 OTLP 消息、处理这些消息，并将其导出到可观测性后端。
限制
客户端轨迹存在以下限制：
- 轨迹跨度适用于 Java 和 Node.js 客户端库。
- 客户端库不会为实时监听器生成轨迹跨度。
结算
除了 Firestore 用量之外，客户端跟踪可能还会产生费用。
收集轨迹或使用 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 配置轨迹。这需要对应用进行代码更改。请参阅以下示例：
- 您可以按照零代码插桩中的示例操作，在不更改代码的情况下配置轨迹。
使用 OpenTelemetry API 将轨迹导出到收集器
以下代码会将客户端库配置为以 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 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();
Node.js（管理员）
import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
import pkg3 from "@opentelemetry/exporter-trace-otlp-grpc";
const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const { OTLPTraceExporter } = pkg3;
const provider = new NodeTracerProvider(
// Provide your chosen NodeTracerConfig such as sampler and span limit
{
sampler: new TraceIdRatioBasedSampler(0.1),
}
);
provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
provider.register();
// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
instrumentations: [
new GrpcInstrumentation(
// (optional): you can add GrpcInstrumentationConfig here
),
],
});
const settings: Settings = {
projectId: 'my-project-id',
preferRest: false,
openTelemetry: {
tracerProvider: trace.getTracerProvider()
}
};
// Initialize Firestore
const firestore = new Firestore(settings);
// Add app code here
// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
await provider
.shutdown()
.catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
使用 OpenTelemetry API 直接导出到可观测性后端
如果您的可观测性服务提供商支持 OTLP 提取，您可以使用其 OpenTelemetry 导出器直接将轨迹导出到其后端。以下代码会将客户端库配置为以 10% 的轨迹采样率直接将轨迹跨度导出到 Cloud Trace。
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();
Node.js（管理员）
import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";
import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const provider = new NodeTracerProvider(
// Provide your chosen NodeTracerConfig such as sampler and span limits
{
sampler: new TraceIdRatioBasedSampler(0.1),
}
);
provider.addSpanProcessor(new BatchSpanProcessor(new TraceExporter()));
provider.register();
// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
instrumentations: [
new GrpcInstrumentation(
// (optional): you can add GrpcInstrumentationConfig here
),
],
});
const settings: Settings = {
projectId: 'my-project-id',
preferRest: false,
openTelemetry: {
tracerProvider: trace.getTracerProvider()
}
};
// Initialize Firestore
const firestore = new Firestore(settings);
// ...
// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
await provider
.shutdown()
.catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
无代码插桩
请按照以下说明操作，在不更改代码的情况下配置轨迹：
Java（管理员）
您可以使用自动代理配置轨迹，而无需更改代码。您需要设置环境变量FIRESTORE_ENABLE_TRACING=ON。您还需要设置其他配置设置，如代理配置中所述。请参阅以下示例。
使用自动代理将数据导出到收集器
启用 OTLP gRPC 接收器，运行 OpenTelemetry 收集器。将代理的导出器设置为 otlp，并指定代理应将数据导出到的端点。以下示例使用 10% 的采样率，并将轨迹发送到监听 localhost 端口 4317 的 Collector。
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
使用自动代理直接导出到可观测性后端
除了设置环境变量 FIRESTORE_ENABLE_TRACING=ON 之外，您还需要为特定后端添加 OpenTelemetry Java 代理扩展。以下示例使用轨迹导出器扩展程序和 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 \
Node.js（管理员）
如需设置零代码插桩，请按照 OpenTelemetry 中的 JavaScript 插桩说明操作。以下示例代码段可启用插桩并将轨迹发送到 OpenTelemetry 收集器：
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
env \
FIRESTORE_ENABLE_TRACING=ON \
OTEL_TRACES_EXPORTER=otlp \
OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,grpc" \
OTEL_NODE_RESOURCE_DETECTORS="none" \
node --require @opentelemetry/auto-instrumentations-node/register my_app.js
轨迹示例
以下示例展示了跟踪信息在 Cloud Trace 中的显示方式。如需详细了解可能的属性和值，请参阅轨迹片段属性和事件。
跟踪 span 示例
事件日志示例
属性值示例
堆栈轨迹和异常事件示例
