v1.traces 總覽

本文說明為何建議您使用 Telemetry (OTLP) API 將追蹤資料傳送至Google Cloud 專案，因為該 API 會實作 OpenTelemetry Protocol。此外，這項服務也提供應用程式檢測指引，以及查看追蹤資料的位置。使用其中一個 OpenTelemetry SDK 檢測應用程式時，或使用 OpenTelemetry Collector 時，您可以使用 Telemetry API。

建議使用 Telemetry API 的原因如下：

  • 這個 API 可與開放原始碼 OpenTelemetry 生態系統相容，且限制通常比 Cloud Trace API (專有 Google Cloud API) 更寬鬆

  • 追蹤資料的儲存格式通常與 OpenTelemetry 通訊協定定義的 proto 檔案一致。部分欄位可能會先從 OpenTelemetry 專屬資料類型轉換為 JSON 資料類型，再進行儲存。如要進一步瞭解儲存格式，請參閱追蹤資料的結構定義。

  • 您的檢測不依賴 Google Cloud專屬的匯出工具。

  • 部分功能 (例如應用程式監控) 只能在您將追蹤資料傳送至 Telemetry API 時，才能取得相關資訊。

OpenTelemetry 是 Google Cloud支援的開放原始碼專案， Google Cloud有專責工程師確保支援擷取及顯示遙測資料。

Google Cloud Observability 會先確認專案已啟用 Cloud Trace API，再儲存任何追蹤資料。 Google Cloud 也就是說，如果停用 Cloud Trace API，Google Cloud Observability 就會捨棄您傳送至 Telemetry API 的追蹤記錄資料。

最佳做法

將應用程式設為向Google Cloud 專案傳送追蹤記錄資料時，建議您使用匯出工具，將 OTLP 格式的資料寫入 Collector，然後將追蹤記錄資料傳送至 Telemetry API。在收集器中，只指定根網址：

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry 會偵測資料類型，並視情況自動附加 /v1/traces、/v1/metrics 或 /v1/logs。詳情請參閱「OTLP/HTTP 要求」。

如需將追蹤或指標資料匯出至 Telemetry API 的範例，請參閱下列文件：

如果無法使用收集器，可以改用含有程序內 OTLP 匯出器的 OpenTelemetry 程式庫，將遙測資料傳送至 Telemetry API。如要瞭解如何直接匯出追蹤記錄資料，請參閱「Cloud Trace exporter to the OTLP endpoint」(Cloud Trace 匯出工具至 OTLP 端點)。

驗證

您必須使用必要憑證設定匯出工具，才能將資料傳送至 Google Cloud 專案。舉例來說，使用收集器時，通常會使用 googleclientauth 擴充功能，透過 Google 憑證進行驗證。

如需使用直接匯出追蹤資料時的驗證範例，請參閱「設定驗證」。這個範例說明如何使用 Google Cloud 應用程式預設憑證 (ADC) 設定匯出工具，並在應用程式中加入特定語言的 Google Auth 程式庫。

如要使用 Telemetry API 將遙測資料傳送至 Google Cloud 專案，您也必須執行下列操作：

  • 設定配額專案。詳情請參閱「設定配額專案」。

  • 將下列 Identity and Access Management (IAM) 角色授予使用者或應用程式使用的服務帳戶：

    • 配額專案的服務使用情形用戶角色 (roles/serviceusage.serviceUsageConsumer)。
    • 專案的「Cloud 遙測資料寫入者」 (roles/telemetry.writer) 角色。這個角色可讓應用程式寫入記錄、指標和追蹤資料。

Cloud Trace 和資料落地

如果您因為有資料落地或影響等級 4 (IL4) 的需求而使用 Assured Workloads，請勿使用 Telemetry API 將追蹤範圍傳送至專案。

查看擷取資料的位置

您可以使用「Trace 探索工具」和「Observability Analytics」頁面查看追蹤記錄資料。詳情請參閱下列文章：

配額

如要瞭解與 Telemetry API 相關的配額，請參閱「Telemetry API 限制」。