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

預覽

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

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

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

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

OpenTelemetry

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

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

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

除了匯出工具，OpenTelemetry 也建議設定收集器。服務可透過收集器快速卸載資料，並由收集器處理重試、批次處理和加密等額外作業。Collector 會與應用程式並行執行。收集器會接收 OpenTelemetry Protocol (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% 的取樣率將時距匯出至 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 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 用戶端程式庫，以 10% 的追蹤記錄取樣率，將追蹤記錄時距直接匯出至 Cloud Trace。您可以使用其他可觀測性服務供應商的匯出工具，直接匯出至後端。如果觀測後端支援 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 上監聽的收集器。

終端機

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

追蹤記錄時距範例

事件記錄範例

屬性值範例

後續步驟

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