v1.metrics 總覽

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

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

最佳做法

監測應用程式以將追蹤記錄資料傳送至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」。

驗證

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

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

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  
SUM (非單調，DELTA) 不支援 系統不支援 Delta-temporality UpDownCounter。
直方圖 (累計) 累積 DISTRIBUTION with explicit buckets /histogram  
指數直方圖 (累計) 累積 具有指數值區的 DISTRIBUTION /histogram  
直方圖 (差異) DELTA DISTRIBUTION with explicit buckets /histogram:delta  
指數直方圖 (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 就不會設定這些標籤。

Cloud Monitoring 和資料落地

如要瞭解指標資料的儲存方式，請參閱「Cloud Monitoring 的資料區域性」。

查看擷取資料的位置

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