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

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

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

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

OpenTelemetry

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

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

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

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

限制

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

  • 跟踪记录 span 适用于 Java 和 Node.js 客户端库。
  • 客户端库不会为实时监听器生成跟踪范围。

结算

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

收集轨迹或使用 OpenTelemetry 框架不会产生任何费用。

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

为了更好地了解结算，请先根据流量设置较小的跟踪记录采样比率（跟踪一小部分远程过程调用）。

准备工作

准备工作：

  • 确保您为应用向可观测性后端写入轨迹所使用的服务账号设置了必要的 Identity and Access Management 角色：

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

  • 验证此项目是否已启用 Trace 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'