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

預先發布版

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

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

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

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

OpenTelemetry

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

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

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

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

限制

追蹤範圍僅適用於 Java 用戶端程式庫。

帳單

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

收集追蹤記錄或使用 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 直接匯出至可觀測性後端
• 您可以使用自動代理程式設定追蹤記錄，不需要變更程式碼。您需要設定環境變數 DATASTORE_ENABLE_TRACING=ON。您也需要按照「代理程式設定」一文所述，設定其他設定。請參閱以下範例：
  • 匯出至具有自動代理程式的收集器
  • 使用 Auto Agents 直接匯出至可觀測性後端

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

下列程式碼會設定 Datastore Java 用戶端程式庫，以 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 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 用戶端程式庫設定為直接將追蹤跨度匯出至 Cloud Trace，追蹤取樣率為 10%。您可以使用其他可觀測性服務供應商的匯出工具，直接匯出至後端。如果可觀測性後端支援 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();

    

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

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

    

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

除了設定環境變數 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 中的顯示方式。如要進一步瞭解可能的屬性和值，請參閱「追蹤範圍屬性和事件」。

追蹤範圍範例

事件記錄範例

屬性值範例

後續步驟

• 請參閱追蹤範圍屬性和事件的參考資料。
• 瞭解伺服器端監控。