遷移至 OTLP 匯出工具

本文說明如何修改使用現有匯出器 (在本例中為 googlemanagedprometheus 匯出器) 的 OpenTelemetry Collector 設定，改用 otlphttp 匯出器和 Telemetry (OTLP) API telemetry.googleapis.com。

只有使用 OpenTelemetry Collector 0.140.0 以上版本時，才能使用 Prometheus 指標的 OTLP。

啟用 Telemetry API

otlphttp 匯出工具會寫入 Telemetry API，因此您必須在專案中啟用該 API。執行下列指令，啟用 Telemetry API：

gcloud services enable telemetry.googleapis.com

授權 Kubernetes 服務帳戶

Kubernetes 服務帳戶必須具備使用 Telemetry API 的權限。下列指令會將必要的 Identity and Access Management (IAM) 角色授予 Kubernetes 服務帳戶。這些指令假設您使用 Workload Identity Federation for GKE：

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
  --role=roles/telemetry.metricsWriter \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

將 PROJECT_ID 變數替換為 Google Cloud 專案 ID。

如果服務帳戶的格式不同，您可以使用 Google Cloud Managed Service for Prometheus 說明文件中的指令授權服務帳戶，並進行下列變更：

將服務帳戶名稱 gmp-test-sa 替換為您的服務帳戶。
執行指令，授予 roles/telemetry.metricsWriter 角色。

設定 `PROJECT_ID` 環境變數

在收集器部署作業中設定 PROJECT_ID 環境變數。結果如下所示：

env:
- name: PROJECT_ID
  value: PROJECT_ID

找出要更換的匯出者

在設定檔中，找出匯出工具和使用匯出工具的服務：

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

為 `otlphttp` 匯出工具新增設定

在這個步驟中，您要將 otlphttp 匯出工具和 metricstarttime 處理器新增至設定。這個額外的匯出工具會導致收集器重複寫入指標。

如果您使用 OTLP 原生指標，雙重寫入不會造成問題，因為這兩種方法建立的指標描述元結構不同。這兩項指標各不相同。
如果您使用 Prometheus 指標，則在移除 googlemanagedpromethusexporter 之前，會看到衝突。

更新後的設定如下所示：

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

指標雙重寫入完成後，請更新資訊主頁和快訊政策，使用 otlphttp 匯出工具產生新的指標名稱。otlphttp 匯出工具不會將指標重新命名為「Prometheus 樣式」，而是使用底線取代。

移除先前匯出工具的設定

更新資訊主頁和快訊，改為參照 otlphttp 匯出的指標後，請從設定中移除舊的匯出工具 (本例為 googlemanagedprometheus)。修訂後的設定如下所示：

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

視需要遷移資訊主頁和快訊政策

如果您只使用 googlemanagedprometheus 匯出工具匯出 Prometheus 指標資料，切換至 OTLP 匯出工具後，現有的資訊主頁和快訊政策仍可繼續運作。

不過，如果您使用 googlemanagedprometheus 匯出工具收集及傳送原本使用 OTLP 發出的資料，或是擷取含有 UTF-8 字元的 Prometheus 指標，則必須更新資訊主頁和快訊，改用 UTF-8 指標名稱。

這是因為使用 OTLP 匯出的指標與使用 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 後置字元。

如要進一步瞭解指標之間的差異，請參閱「googlemanagedprometheus 匯出工具與 Telemetry API 之間的差異」。

由於轉換規則不適用於含有 UTF-8 字元的指標，因此您需要重新編寫資訊主頁和快訊政策，使用新的指標名稱，或合併新舊指標名稱。

我們不建議編寫處理器規則來重新建立這些轉換，繼續編寫 UTF-8 指標，就好像這些指標是由 googlemanagedprometheus 匯出工具收集一樣。這樣做可保留回溯相容性，但會犧牲前瞻相容性，而且您無法輕鬆使用參照 UTF-8 指標名稱的開放原始碼資產。