使用用戶端追蹤記錄監控成效

使用用戶端追蹤記錄監控成效

預先發布版

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要監控及偵錯端對端 Firestore 要求，可以在用戶端程式庫中啟用追蹤。用戶端追蹤功能可提供應用程式體驗的效能信號，以及有助於偵錯問題的洞察資料。

用戶端追蹤記錄是透過從用戶端執行 RPC 收集，可提供下列資訊：

• 時間戳記範圍，包括用戶端傳送 RPC 要求的時間，以及用戶端收到 RPC 回應的時間，包括網路和用戶端系統造成的延遲
• 屬性 (鍵/值組)，可顯示用戶端及其設定的相關資訊
• 與範圍內重要事件相關聯的記錄
• 如果用戶端發生當機情形，系統會提供堆疊追蹤記錄

OpenTelemetry

用戶端程式庫的追蹤記錄是使用 OpenTelemetry API 進行檢測。OpenTelemetry 是業界標準的開放原始碼可觀測性架構。OpenTelemetry 提供各種工具，例如檢測 API 和 SDK、收集器、後端專用匯出工具，以及彈性設定選項，例如取樣控制項和範圍限制。

使用匯出工具和收集器匯出追蹤記錄

在設定期間，您可以將追蹤記錄匯出至可觀測性後端。大多數可觀測性服務供應商都會提供匯出工具供您使用，例如 Cloud Trace。

除了匯出工具，OpenTelemetry 也建議設定 Collector。收集器可讓服務快速卸載資料，並處理重試、批次處理和加密等額外作業。Collector 會與應用程式並行執行。收集器會接收 OTLP 訊息、處理訊息，然後將訊息匯出至可觀測性後端。

限制

用戶端追蹤記錄有下列限制：

• Java 和 Node.js 用戶端程式庫提供追蹤範圍。
• 用戶端程式庫不會為即時監聽器產生追蹤範圍。

帳單

除了 Firestore 用量外，用戶端追蹤也可能會產生費用。

收集追蹤記錄或使用 OpenTelemetry 架構不會產生費用。

將追蹤記錄時距擷取到可觀測性後端可能會產生費用。 舉例來說，如果您使用 Cloud Trace 做為後端，系統會依據 Cloud Trace 定價向您收費。如果您使用其他可觀測性服務供應商，請瞭解他們的計費模式和相關費用。

如要進一步瞭解帳單，請根據流量，先從較小的追蹤取樣比例開始 (追蹤一小部分的 RPC)。

事前準備

事前準備：

• 請務必設定服務帳戶，讓應用程式在該帳戶下將追蹤記錄寫入可觀測性後端，並具備必要的身分與存取權管理角色：

  追蹤作業	IAM 角色
  讀取追蹤記錄	roles/cloudtrace.user
  寫入追蹤記錄	roles/cloudtrace.agent
  讀取/寫入追蹤記錄	roles/cloudtrace.admin

• 確認這項專案已啟用 Trace API。

設定用戶端追蹤記錄

本節提供用戶端追蹤的設定範例。您可以匯出至 Collector，或直接匯出至可觀測性後端。您也可以透過下列選項設定用戶端追蹤記錄：

• 您可以使用 OpenTelemetry API 設定追蹤記錄。這需要變更應用程式的程式碼。請參閱以下範例：
  • 使用 OpenTelemetry API 匯出至 Collector
  • 使用 OpenTelemetry API 直接匯出至可觀測性後端
• 您可以按照「零程式碼插碼」中的範例，設定追蹤記錄，完全不需要變更程式碼。

使用 OpenTelemetry API 將追蹤記錄匯出至 Collector

下列程式碼會設定用戶端程式庫，以 10% 的取樣率將 span 匯出至 OpenTelemetry Collector。

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。您也需要按照「代理程式設定」一文所述，設定其他設定。請參閱以下範例。

匯出至具有自動代理程式的收集器

執行 OpenTelemetry Collector，並啟用 OTLP gRPC 接收器。將代理程式的匯出工具設為 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

使用 Auto Agents 直接匯出至可觀測性後端

除了設定環境變數 FIRESTORE_ENABLE_TRACING=ON，您還需要為特定後端新增 OpenTelemetry Java 代理程式擴充功能。以下範例使用 Trace 匯出工具擴充功能，以及 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 中的顯示方式。如要進一步瞭解可能的屬性和值，請參閱「追蹤範圍屬性和事件」。

追蹤範圍範例

事件記錄範例

屬性值範例

堆疊追蹤和例外狀況事件範例

後續步驟

• 查看追蹤記錄範圍屬性和事件的參考資料
• 瞭解伺服器端監控