OTLP 擷取總覽

本文將介紹如何使用 Telemetry (OTLP) API telemetry.googleapis.com，該 API 會實作 OpenTelemetry 通訊協定。您可以透過 Telemetry API，將 OTLP 格式的記錄、指標和追蹤記錄資料擷取至 Google Cloud Observability：

  • OTLP 記錄檔記錄會轉換為記錄項目，然後轉送及儲存。如要瞭解轉換程序，請參閱本文的「OTLP 記錄擷取」一節。
  • 指標資料會擷取至 Cloud Monitoring。如要瞭解指標和標籤名稱，以及擷取限制，請參閱本文的「擷取 OTLP 指標」一節。
  • 追蹤資料的儲存格式通常與 OTLP 一致。詳情請參閱「OTLP 追蹤擷取」。

您可以從使用 SDK 的應用程式將遙測資料傳送至 Telemetry API，也可以從 OpenTelemetry Collector 匯出資料。

如果您使用 Google Kubernetes Engine，可以改用 Managed OpenTelemetry for GKE，不必手動部署及設定使用 Telemetry API 的 OpenTelemetry Collector。

通訊協定支援

OTLP 端點支援所有 OTLP 傳輸和序列化通訊協定，包括 http/protobuf、http/json 和 grpc。直接從使用 SDK 的應用程式匯出時，建議使用 gRPC OTLP 匯出工具，而非 HTTP 匯出工具，因為大多數 SDK 匯出工具都不支援動態權杖重新整理。

驗證

您必須使用必要憑證設定匯出工具，才能將資料傳送至 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) 角色。這個角色可讓應用程式寫入記錄、指標和追蹤資料。

OTLP 擷取

本節說明如何將記錄、指標和追蹤資料從 OTLP 轉換為 Google Cloud Observability 資料結構。

記錄資料擷取

使用 Telemetry API 擷取 OTLP 格式的記錄時，記錄資料會轉換為 Cloud Logging 記錄項目。JSON 格式的 OTLP 記錄要求一般具有下列結構：

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

每個 logRecords 陣列中的每個項目都會成為單一 Cloud Logging 記錄項目。resource 屬性會決定結果 LogEntry 中的受監控資源。如要進一步瞭解擷取 OTLP 格式記錄時必須提供的屬性，請參閱「OTLP 屬性至資源類型對應」。

為支援擷取 OTLP 格式的記錄，Cloud Logging LogEntry 結構包含額外欄位 otel。由於 OTLP 和 Cloud Logging 資料模型的結構不同，otel 欄位會保留來自傳入 OTLP 要求的資源、範圍和實體中繼資料副本。

舉例來說，如果您將下列 OTLP resourceLogs 酬載傳送至 Telemetry API，則每個產生的記錄項目都會包含 resource 欄位 (適用於受監控資源) 和 otel 欄位，如其他分頁所示：

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

由於 Cloud Logging 記錄項目是獨立的，且不會連結至外部資源結構定義，因此所有 OTLP 資源、範圍和實體中繼資料都會複製到每個記錄項目中。

擷取指標資料

只有在使用 OpenTelemetry Collector 0.140.0 以上版本時，才能透過 OTLP 傳送 Prometheus 指標。

使用 OpenTelemetry Collector 和 otlphttp 匯出工具將指標擷取至 Cloud Monitoring，或使用 OpenTelemetry SDK 直接傳送指標時，OTLP 指標會對應至 Cloud Monitoring 指標結構。如要瞭解這些對應關係，請參閱下列內容：

Google Cloud Observability 會將指標轉換為 Prometheus 時間序列格式。指標名稱不得有網域，或只能有 prometheus.googleapis.com 網域。轉換後，指標名稱會根據 OTLP 點種類型，包含 prometheus.googleapis.com 前置字串和額外後置字串。產生的 Cloud Monitoring 指標結構如下：

prometheus.googleapis.com/{metric_name}/{suffix}

此外，對於每個不重複的 OpenTelemetry 資源，轉換會新增 target_info 指標，其中包含 service.name、service.instance.id 和 service.namespace 以外的所有資源屬性。

由於 Cloud Monitoring 中的指標名稱和標籤鍵不支援完整 UTF-8，因此系統可能會拒絕指標資料：

  • 不符合規則運算式的指標名稱[a-zA-Z][a-zA-Z0-9_:./-]*會遭到拒絕。指標名稱只能使用 _:./- 中的特殊字元。
  • 如果資料點包含不符合規則運算式 [a-zA-Z_][a-zA-Z0-9_.]* 的屬性 (即標籤鍵)，系統會拒絕這類資料點。標籤鍵只能使用 _. 中的特殊字元。標籤值可使用所有特殊字元。

為避免指標因上述原因遭到拒絕，請使用 replace_pattern 函式轉換指標名稱和屬性。

擷取追蹤資料

無論您使用 Telemetry API 或 Cloud Trace API，傳入的追蹤資料都會以符合 OTLP 的格式儲存。不過，我們建議使用 Telemetry API，因為相較於 Cloud Trace API，Telemetry API 的擷取配額較高。

以下範例是應用程式可能傳送至 Google Cloud 專案的追蹤記錄資料：

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

每個 scopeSpans.spans 陣列中的每個項目都會成為單一儲存的範圍：

  • 每個範圍的 resource 欄位都包含 resourceSpans.resource.attributes 資料的副本。
  • 每個範圍的 instrumentation_scope 欄位都包含 scopeSpans.scope 資料的副本。
  • 每個範圍都對應 scopeSpans.spans 陣列中的一個項目。traceId、spanId 和 kind 等欄位會對應到追蹤架構中名稱相似的欄位。

如需詳細資訊，請參閱下列文件：

帳單

使用 Telemetry API 擷取的記錄、指標和追蹤資料費用，取決於遙測信號。如需完整資訊，請參閱帳單頁面。

記錄資料帳單

使用 Telemetry API 擷取記錄時，記錄量可能會發生變化，導致 Cloud Logging 儲存空間和帳單值有所變動。

如果符合下列兩項條件，專案的儲存空間和帳單就會出現最大變化： Google Cloud

  • resource 欄位包含高基數屬性或大量屬性。這些資源屬性會決定結果 LogEntry 中的受監控資源。
  • scopeLogs 欄位包含 logRecords 陣列中的大量項目。每個個別記錄項目的 scopeLogs.scope 欄位都會複製到 otel 欄位。

由於這項資源和範圍中繼資料會複製到每個個別的記錄檔項目，因此儲存的記錄檔量可能會增加。

為盡量減少儲存空間用量，建議採取下列做法：

  • 使用 OpenTelemetry Collector 處理器 (例如 transform 處理器)，在匯出資料前捨棄不必要的資源或範圍屬性。
  • 如果不需要在 otel 欄位中保留額外中繼資料，請使用舊版對應選項 gcp.use_legacy_mapping，避免系統填入 otel 欄位。

指標資料計費

系統會使用「擷取的 Prometheus 樣本」SKU 計算 OTLP 指標的費用，這與 Google Cloud Managed Service for Prometheus 指標的計費方式相同。

追蹤資料帳單

用來將追蹤資料傳送至專案的 API，不會影響該資料的費用計算方式。

查詢記錄、指標和追蹤記錄資料

您可以使用探索工具頁面 (Logs Explorer、Metrics Explorer 和 Trace Explorer) 查詢記錄、指標和追蹤記錄資料。您也可以使用 Observability Analytics 頁面，透過 SQL 分析記錄和追蹤記錄資料。

使用 Metrics Explorer 查詢指標資料時，下列提示或許能派上用場：

  • 重要事項：如要查詢含有特殊字元的指標名稱和標籤鍵 (冒號「:」和底線「_」除外)，請根據 PromQL 的 UTF-8 規格，將這些名稱和鍵放在大括號 ({}) 和引號 (") 中。舉例來說，下列查詢有效：

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • 查詢指數直方圖時保留 le 標籤，可能會傳回非預期的結果。預期會運作的查詢越典型 histogram_quantile(.99, sum by (le) (metric))。

  • 在特定情況下，差異指標可能無法正確查詢，例如差異非常稀疏。

限制與配額

遙測 API 限制適用於所有信號類型。

此外，也適用下列配額和限制：

  • 記錄檔資料：適用 Cloud Logging API 配額與限制。

  • 指標資料：適用 Cloud Monitoring API 配額和限制。舉例來說，指標最多只能有 200 個標籤。

    Telemetry API 擷取的指標預設配額為每分鐘 60,000 項要求。每個要求最多可包含 200 個點，因此這項配額實際上是每秒 200,000 個樣本的預設配額。您可以要求增加配額。

  • 追蹤記錄資料：沒有額外的配額或限制。

後續步驟