v1.metrics 總覽

本文說明如何將使用 Telemetry (OTLP) API 傳送至 Google Cloud 專案的指標資料，對應至 Cloud Monitoring 結構。這個 API 會實作 OpenTelemetry OTLP 通訊協定。使用 otlphttp 匯出工具和 OpenTelemetry Collector 檢測應用程式，或使用 OpenTelemetry SDK 時，您可以將資料傳送至這個 API。

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

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 with exponential buckets /histogram  
直方圖 (差異) DELTA DISTRIBUTION with explicit buckets /histogram:delta  
指數直方圖 (差異) DELTA DISTRIBUTION with exponential buckets /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 匯出工具不同：

  • 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 擷取的指標資料，可使用 Metrics Explorer 頁面查看。如要瞭解如何查看指標資料並繪製成圖表，請參閱「使用 Metrics Explorer 建立圖表」一文。