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

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

预览版

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

如需端到端地监控和调试 Firestore 请求，您可以在客户端库中启用跟踪记录。客户端跟踪记录可提供有关应用体验到的性能的信号，以及有助于调试问题的分析洞见。

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

• 包含客户端发送 RPC 请求的时间和客户端收到 RPC 响应的时间的时间戳，包括网络和客户端系统造成的延迟
• 提供有关客户端及其配置的信息的属性（键值对）
• 与 span 中的关键事件相关联的日志
• 如果客户端发生崩溃，则为堆栈轨迹

OpenTelemetry

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

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

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

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

限制

客户端跟踪记录存在以下限制：

• 跟踪记录 span 适用于 Java 和 Node.js 客户端库。
• 客户端库不会为实时监听器生成轨迹 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。

配置客户端跟踪记录

本部分提供了客户端轨迹的配置示例。您可以将跟踪记录导出到收集器，也可以直接导出到可观测性后端。 您还可以通过以下方式配置客户端轨迹：

• 您可以使用 OpenTelemetry API 配置轨迹。这需要对应用进行代码更改。请参阅以下示例：
  • 使用 OpenTelemetry API 导出到收集器
  • 使用 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 导出器将轨迹直接导出到其后端。以下代码将客户端库配置为直接将跟踪记录 span 导出到 Cloud Trace，并将跟踪记录采样率设置为 10%。

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。您还需要设置其他配置设置，如代理配置中所述。请参阅以下示例。

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

运行 OpenTelemetry 收集器，并启用 OTLP gRPC 接收器。将代理的导出器设置为 otlp，并指定代理应将数据导出到的端点。以下示例使用 10% 的抽样比率，并将轨迹发送到监听本地主机端口 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

使用自动代理直接导出到可观测性后端

除了设置环境变量 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（管理员）

如需设置零代码插桩，请按照 JavaScript 插桩的 OpenTelemetry 说明操作。以下示例代码段可启用插桩并将跟踪记录发送到 OpenTelemetry 收集器：

npm install @opentelemetry/api
npm install @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 属性和事件。

跟踪 span 示例

事件日志示例

属性值示例

堆栈轨迹和异常事件示例

后续步骤

• 查看跟踪范围属性和事件的参考
• 了解服务器端监控