用 OTLP 將 OpenTelemetry 指標送入 Prometheus

設定 Prometheus 的 OTLP/HTTP 接收器和 Collector,核對寫入後的指標名稱、資源標籤與 Delta 聚合時間性。

最佳實務
遙測資料流入可觀測性後端的示意圖

結帳服務開始把 OpenTelemetry 指標送往新的後端。Collector 收到批次,Prometheus 儀表板卻沒有資料。先確認實際送出的 HTTP 請求。Prometheus 接收 OTLP 指標的路徑是 /api/v1/otlp/v1/metrics。請求若已抵達該路徑,先查看 Prometheus 實際儲存的指標名稱和標籤,再決定是否要改埋點。

把指標送到正確的接收網址

Prometheus 3.x 須明確啟用 OTLP 接收器。在本機測試時,先把下文的 Prometheus 設定存為 prometheus.yml,再將監聽位址限制在 loopback。

prometheus --web.enable-otlp-receiver --web.listen-address=127.0.0.1:9090 --config.file=prometheus.yml

使用支援環境變數設定的 SDK 直接送出指標時,可設定 OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf 和 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://127.0.0.1:9090/api/v1/otlp/v1/metrics。指標專用變數須填完整網址。若改用通用的 OTEL_EXPORTER_OTLP_ENDPOINT,填入基底網址即可,HTTP 匯出器會依訊號附加路徑。追蹤和日誌須各自設定目的地。

以下是 Collector 0.159.0 的本機設定,透過 OTLP/HTTP 收取指標,再轉送到 Prometheus。較舊的 Collector 可能使用 otlphttp 作為匯出器名稱。

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318
exporters:
  otlp_http:
    endpoint: http://127.0.0.1:9090/api/v1/otlp
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [otlp_http]

Collector 會在 endpoint 後面加上 /v1/metrics。若使用 metrics_endpoint,請填完整網址。接收端可另行設定 gRPC,接收應用程式透過 OTLP/gRPC 送來的資料,轉送到 Prometheus 的一端仍然使用 HTTP。Prometheus 2.47 引入實驗性接收器,須用 --enable-feature=otlp-write-receiver 啟用。請按實際部署版本核對啟動參數。Prometheus OTLP 指南 · OTLP 匯出器規格 · Collector HTTP 匯出器

查閱實際儲存的時間序列

假設結帳服務送出名為 checkout.requests 的累積單調和。Prometheus 3.16 採預設轉換策略時,查詢名稱為 checkout_requests_total。轉換會正規化指標和標籤名稱,並依類型和單位加上適用的後綴。即使版本支援 UTF-8,OTLP 的命名仍由轉換策略決定。調整策略可能改變儀表板和規則的選擇器,也可能讓原先以類型或單位區別的指標發生名稱衝突。

Prometheus 用 service.name 組成 job,若有 service.namespace,會將它放在前面。 instance 則來自 service.instance.id。例如命名空間為 shop、服務為 checkout、執行個體 ID 為 checkout-1 時,可查詢 checkout_requests_total{job="shop/checkout",instance="checkout-1"}。Prometheus 3.16 會在資源具有可映射為 job 或 instance 的識別屬性,且至少還有一個非識別屬性時,建立 target_info。用 job 和 instance 聯結時,需要只有一條匹配的資訊序列。屬性變更後,新舊序列有時會短暫同時可見。

如果資源已有環境屬性,而且每條告警都要依環境篩選,就把該屬性提升成指標標籤。Pod 名稱若無須出現在每條指標序列上,可以留在 target_info。採預設轉換策略時,下列設定會加入 deployment_environment_name 標籤。

otlp:
  translation_strategy: UnderscoreEscapingWithSuffixes
  promote_resource_attributes:
    - deployment.environment.name

新的標籤值組合會形成獨立的時間序列。即使同時存在的序列數沒有明顯增加,工作負載重啟造成的值更換仍可能讓序列頻繁建立和淘汰。用實際負載觀察活躍序列數、新增序列的速度和記憶體餘裕。Prometheus 資源屬性轉換 · Prometheus 3.16 轉換程式(英文) · 可觀測性資料的高基數

遷移儀表板前先決定聚合時間性

累積計數器記錄起點至今的總數,Delta 資料點則記錄單一區間的增量。既有儀表板若對累積計數器使用 rate(),可優先讓 SDK 輸出累積值,或交由指定的 Collector 轉換。轉換器須保存狀態,同一資料流要穩定地送往同一處。重啟轉換器或切換路由都可能影響累積結果。

Prometheus 3.2 加入實驗性的 otlp-deltatocumulative,把轉換狀態留在記憶體,重啟後狀態會消失。3.4 加入實驗性的 otlp-native-delta-ingestion,直接儲存原始增量。兩個開關互斥。若要查詢原始增量,須依部署版本的 Delta 行為調整查詢。Prometheus 功能開關 · 版本變更紀錄

分開處理延遲批次和重複寫入

多個 Collector 副本可能讓批次亂序抵達。同一資料流的不同批次若由不同副本轉送,先量測抵達延遲,再評估 storage.tsdb.out_of_order_time_window 的範圍。若兩個送出端重複寫入同一批樣本,或不同資料流誤用同一個執行個體 ID,先修正路由或識別碼。擴大亂序視窗只會讓範圍內的延遲樣本得以寫入。

開放 loopback 以外的寫入前,先配置 TLS,限制可寫入的來源。除了匯出失敗、重試和佇列狀態,也要查看 Prometheus 丟棄的樣本和告警使用的序列。用 Remote Write 送往長期儲存時,該佇列須獨立監控。應用程式推送 OTLP 的可用性也須獨立確認,抓取時產生的 up 不涵蓋該路徑。監控 OpenTelemetry Collector

切換儲存前先核對數值

已有觀測雲工作空間時,可讓 DataKit 的 OpenTelemetry 採集器(簡體中文)在設定的端點接收 OTLP 指標,也可以用 DataKit Prom 採集器(簡體中文)抓取應用程式既有的 /metrics。追蹤的轉送路徑和從追蹤產生的 APM 指標,需要和應用程式計數器分開確認。

若遷移期間平行寫入兩個後端,對照同一服務、同一時間範圍和同一埋點的資料。先核對一次已知的請求數變化及延遲直方圖,再移轉告警。使用觀測雲的 PromQL 查詢模式(簡體中文)協助比對時,也要檢查儲存後的名稱、標籤和分桶邊界,再沿用查詢。

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

在线开通,按量计费,真正的云服务!

立即開始

选择观测云版本

代码托管平台