用 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 查詢模式(簡體中文)協助比對時,也要檢查儲存後的名稱、標籤和分桶邊界,再沿用查詢。
