Google Cloud Observability 支援 OTLP

您可以使用 Telemetry (OTLP) API，將 OTLP 格式的記錄、指標和追蹤記錄資料擷取至 Google Cloud Observability，該 API 會實作 OpenTelemetry Protocol。這個 API 可讓您從 OpenTelemetry SDK 和收集器收集不限供應商的遙測資料，而不必使用自訂 Google Cloud 匯出工具。

使用 Telemetry API 將遙測資料傳送至專案時，Google Cloud Observability 會按照下列方式處理各個信號：

  • 記錄資料：將 OTLP 記錄轉換為記錄項目，並轉送至儲存空間。
  • 指標資料：將指標資料對應至 Cloud Monitoring 中的 Prometheus 時間序列。
  • 追蹤記錄資料：以通常與 OTLP 一致的格式儲存分散式追蹤記錄。

如果您在 Google Kubernetes Engine 執行工作負載，可以使用 GKE 專用代管 OpenTelemetry，不必手動部署及管理 OpenTelemetry 收集器。

通訊協定支援

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) 角色授予使用者，或應用程式使用的服務帳戶：

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 資源、範圍和實體中繼資料都會複製到每個記錄項目。

指標資料擷取

Prometheus 指標的 OTLP 僅適用於 OpenTelemetry Collector 0.140.0 以上版本。

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

Google Cloud Observability 會將指標轉換為 Prometheus 時間序列格式。指標名稱不得有網域，或必須使用 prometheus.googleapis.com 網域。轉換後，指標名稱會包含 prometheus.googleapis.com 前置字串，以及根據 OTLP 點類型附加的後置字串。產生的 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。

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

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

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

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

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

帳單

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

記錄資料計費

使用 Telemetry API 擷取記錄時，記錄量可能會有所變化，因此 Cloud Logging 儲存空間和帳單金額也可能隨之變動。

如果符合下列兩項條件， Google Cloud 專案的儲存空間和計費方式會發生最大變化：

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

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

如要盡可能減少儲存空間，建議採取下列做法：

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

指標資料計費

OTLP 指標的計費項目為「Prometheus Samples Ingested」SKU，與 Google Cloud Managed Service for Prometheus 指標使用的 SKU 相同。

追蹤記錄資料計費

您用來將追蹤記錄資料傳送至專案的 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)) 查詢應可正常運作。

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

限制與配額

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

此外，也須遵守下列配額和限制：

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

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

    Telemetry API 擷取的指標預設配額為每分鐘 60,000 項要求。每項要求的批次大小上限為 200 個資料點，因此這項配額的有效預設配額為每秒 200,000 個樣本。您可以要求提高配額。

  • 追蹤記錄資料：不適用其他配額或限制。

後續步驟