追蹤記錄 (OTLP) API 總覽

本文說明 Telemetry (OTLP) API，該 API 會實作 OpenTelemetry OTLP 通訊協定。這個 API 適用於使用 OpenTelemetry SDK 檢測的應用程式，或使用任何 OpenTelemetry Collector 的應用程式。

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

追蹤資料和 Telemetry API

本節提供 Telemetry API 和追蹤記錄的相關資訊。

使用 Telemetry API 的好處

使用 Telemetry API 時，資料會以與 OpenTelemetry OTLP 通訊協定定義的 proto 檔案大致一致的格式儲存。不過，欄位可能會在儲存前，從 OpenTelemetry 專屬資料類型轉換為 JSON 資料類型。此外，Telemetry API 的限制也適用。 這些限制通常比 Cloud Trace API 的限制寬鬆。最後，您的檢測工具不依賴 Google Cloud專屬的匯出工具。

如要進一步瞭解儲存格式，請參閱追蹤資料的結構定義。

Telemetry API 的使用時機

建議您使用 Telemetry API，將追蹤資料傳送至專案 Google Cloud 。這個 API 與開放原始碼 OpenTelemetry 生態系統相容，且限制通常比 Cloud Trace API (專屬Google Cloud API) 更寬鬆。部分功能 (例如應用程式監控) 需仰賴僅在追蹤資料傳送至 Telemetry API 時提供的資訊。

將應用程式檢測結果傳送至Google Cloud 專案時，建議您採取下列任一做法：

  • 使用將 OTLP 寫入 Collector 的匯出工具，然後將追蹤記錄資料傳送至 Telemetry API。
  • 使用 OpenTelemetry 程式庫支援的程序內 OTLP 匯出器，將遙測資料傳送至 Telemetry API。沒有符合這項設定的收集器。

如要瞭解如何使用 Telemetry API，請參閱「從 Cloud Trace 匯出工具遷移至 OTLP 端點」。

驗證

匯出者必須獲得授權，才能將資料傳送至您的 Google Cloud 專案。舉例來說，您可以在應用程式中加入特定語言的 Google Auth 程式庫，藉此使用 Google Cloud 應用程式預設憑證 (ADC) 設定匯出工具。如需詳細資訊和程式碼範例，請參閱「設定驗證」。

Cloud Trace 和資料落地

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

指標資料和 Telemetry API

本節說明 Cloud Monitoring 如何處理透過 otlphttp 匯出工具和 OpenTelemetry Collector 擷取的指標，或透過使用其中一個 OpenTelemetry SDK 檢測的應用程式擷取的指標。

Cloud Monitoring 中的 OTLP 指標

使用 OpenTelemetry Collector 和 otlphttp 匯出工具將指標擷取至 Cloud Monitoring，或使用 OpenTelemetry SDK 直接傳送指標時，系統會將 OTLP 指標對應至 Cloud Monitoring 指標結構。本節說明下列事項：

受監控資源對應

所有指標點都會使用 Prometheus 對應，以 Google Cloud Managed Service for Prometheus 的形式寫入。

Prometheus 對應

Prometheus 指標必須使用受監控的資源類型 prometheus_target。

prometheus_target 資源類型上的下列標籤用於架構化，並有效率地儲存 Monarch 內的資料。您為這些屬性指定的值越精確，查詢能力和擴充性就越好。

強烈建議您盡可能明確設定這些標籤的值，雖然我們已實作備援邏輯，可在沒有明確值的情況下使用。

下表依優先順序列出標籤的值來源：

prometheus-target 標籤 使用的值 (依優先順序)
location (必要元素)
  • location 屬性
  • cloud.availability_zone 屬性
  • cloud.region 屬性
cluster
  • cluster 屬性
  • k8s.cluster.name 屬性
  • __gce__，如果 cloud.platform 屬性是 gcp_compute_engine
  • __run__，如果 cloud.platform 屬性是 gcp_cloud_run
  • 空字串
namespace
  • namespace 屬性
  • k8s.namespace.name 屬性
  • service.namespace 屬性
  • 空字串
job
  • job 屬性
  • "service.namespace" + "/" + service.namespace 屬性
  • service.name 屬性
  • service.name 屬性， 如果不是 unknown_service:foo
  • faas.name 屬性
  • k8s.deployment.name 屬性
  • k8s.statefulset.name 屬性
  • k8s.job.name 屬性
  • k8s.cronjob.name 屬性
  • service.name 屬性，如果 unknown_service:foo
  • 空字串
instance
如果為空白，則拒絕該點
  • instance 屬性
  • service.instance.id 屬性
  • faas.instance 屬性
  • k8s.pod.name:k8s.container.name 屬性
  • k8s.pod.name 屬性 (如果沒有容器名稱)
  • host.id 屬性

指標對應

指標會轉換為 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 以外的所有資源屬性。

所有 OTLP INT64 指標都會在 Cloud Monitoring 中轉換為 DOUBLE 值類型，即使收集器將值類型指定為 INT64 也是如此。進行這項變更的原因是，時間序列進入 Monarch 後，您就無法變更值類型。支援 INT64 值最常見的後果是發生衝突，而解決衝突的唯一方法是刪除指標。

Prometheus 指標對應

指標類型對應如下：

  • OTLP Gauge 會對應至 Cloud Monitoring Gauge。
  • OTLP Sum 對應如下：
    • 如果 is_monotonic 設為 false，則為 Cloud Monitoring 計量表。
    • 傳送至 Cloud Monitoring 的累計資料，前提是 aggregation_temporality 設為 AGGREGATION_TEMPORALITY_CUMULATIVE。
    • Cloud Monitoring delta 當 aggregation_temporality 設為 AGGREGATION_TEMPORALITY_DELTA 時。
  • OTLP 直方圖會對應至 Cloud Monitoring distribution，指標類型為累計或增量，視 aggregation_temporality 的值而定。
  • OTLP 摘要指標會擴展為每個元件的個別時間序列：count、sum 和每個 quantile。
    • 計數和總和指標的名稱分別會加上 _count 或 _sum 後置字元，並以 DOUBLE 類型的 Cloud Monitoring cumulative 指標形式寫入。
    • 每個分位數都會成為自己的 gauge 時間序列，類型為 DOUBLE，並帶有 quantile 標籤。

下表彙整指標對應：

OTLP 點類型 監控 指標類型 監控 值類型 字尾 附註
GAUGE GAUGE DOUBLE /gauge  
GAUGE (metric.metadata["prometheus.type"]="unknown") GAUGE DOUBLE /unknown Prometheus Unknowns 會由 OpenTelemetry Collector 分成計數器和計量表。
SUM (monotonic, CUMULATIVE) 累積 DOUBLE /counter  
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown") 累積 DOUBLE /unknown:counter Prometheus Unknowns 會由 OpenTelemetry Collector 分成計數器和計量表。
SUM (monotonic, DELTA) DELTA DOUBLE /delta  
SUM (非單調遞增，CUMULATIVE) GAUGE DOUBLE /gauge  
直方圖 (累計) 累積 DISTRIBUTION with explicit buckets /histogram  
指數直方圖 (累計) 累積 具有指數值區的 DISTRIBUTION /histogram  
直方圖 (差異) DELTA DISTRIBUTION with explicit buckets /histogram:delta  
指數直方圖 (差異) DELTA 具有指數值區的 DISTRIBUTION /histogram:delta  
SUMMARY
(sum,
count,
quantile)		  
累積
累積
量表		  
DOUBLE
DOUBLE
DOUBLE		  
_sum/summary:counter
_count/summary
/summary		 摘要資料點會寫入多個時間序列，分別代表計數、總和和每個計算出的分位數。系統也會產生附有 quantile 標籤的分位數指標。

googlemanagedprometheus 匯出工具與 Telemetry API 的差異

Telemetry API (telemetry.googleapis.com) 處理指標的方式與 googlemanagedprometheus Exporter 不同：

  • Telemetry API 允許在指標名稱中使用半形句號 (.) 和斜線 (/) 字元。googlemanagedprometheus 匯出工具會將所有這類字元例項轉換為底線 (_) 字元。舉例來說，名為 prometheus.googleapis.com/foo.bar/gauge 的 OTLP 指標會由 OTLP 匯出工具逐字匯出，但會由 googlemanagedprometheus 匯出工具匯出為 prometheus.googleapis.com/foo_bar/gauge。

    指標擷取完畢後，Cloud Monitoring 會根據名稱建立指標描述元。由於擷取路徑處理句號 (.) 和斜線 (/) 字元的方式不同，因此使用 googlemanagedprometheus 匯出工具擷取的指標，與使用 otlphttp 匯出工具擷取的指標，其產生的指標描述元也會有所不同。如果同時使用這兩種擷取路徑，就會有兩組指標；如要查詢完整結果，必須手動合併 Prometheus 和 OTLP 版本的指標結果。

  • 如果指標名稱包含單位，Telemetry API 不會附加單位；如果指標是計數器，Telemetry API 也不會附加 _total 後置字元。因此，使用 Telemetry API 匯出的指標為 prometheus.googleapis.com/foo/counter，但 googlemanagedprometheus 匯出工具匯出的指標為 prometheus.googleapis.com/foo_seconds_total/counter。這項差異也適用於 _total 和 _ratio 後置字元。

  • API 會合成 sum_of_squared_deviation 值，以供從指數直方圖衍生而來的分佈值使用。指數直方圖的匯出工具不會設定這個欄位。googlemanagedprometheus

  • API 會將所有整數點值轉換為 Prometheus 指標的雙精度值。

  • 如果 scope_version 或 scope_name 標籤的值為空白，API 就不會設定這些標籤。

查看擷取資料的位置

透過 Telemetry API 擷取的追蹤資料，可使用追蹤記錄探索器頁面查看。如要瞭解如何查看追蹤記錄資料，請參閱下列說明：

透過 Telemetry API 擷取的指標資料，可使用 Metrics Explorer 頁面查看。如要瞭解如何查看指標資料並繪製成圖表，請參閱「使用 Metrics Explorer 建立圖表」一文。

VPC Service Controls 支援

服務名稱為 telemetry.googleapis.com 的 Telemetry API 服務支援 VPC Service Controls。您為 Telemetry API 服務建立的任何 VPC Service Controls 限制，只會套用至該服務。這些限制不適用於任何其他服務，包括 cloudtrace.googleapis.com 服務等，這些服務也能擷取追蹤資料。

如要瞭解詳情，請參考下列資源：