OTLP 協定詳解:OpenTelemetry 的傳輸方式與設定

比較 OTLP/gRPC 和 OTLP/HTTP,解讀部分成功與重試,並設定 DataKit 接收追蹤、指標及日誌的端點。

最佳實務
應用程式效能監控中的服務追蹤與指標示意

匯出器連得到 Collector,資料仍可能送錯路徑。即使收到 HTTP 200,接收端也可能拒絕了批次中的一部分。要找出資料漏在哪一段,得同時檢查匯出器送了什麼,以及接收端確認收到什麼。

OTLP(OpenTelemetry Protocol)是 OpenTelemetry 用來編碼與傳輸遙測資料的協定。 訊息以 Protobuf 定義,支援 gRPC 和 HTTP。追蹤、指標和日誌的傳輸規範已穩定,Profiles 仍在開發中。傳送與接收兩端支援同一種訊號、傳輸方式及編碼時,就能透過 OTLP 交換資料。

OTLP 重點速覽

  • OTLP 定義編碼與傳輸。資料的儲存和查詢由後端處理。
  • gRPC 使用二進位 Protobuf。接收端支援時,OTLP/HTTP 也可使用 OTLP 的 JSON 編碼。
  • 個別 Span、指標和日誌記錄會依資源(Resource)與埋點範圍(Scope)分組。
  • DataKit 可接收 OTLP 追蹤、指標和日誌,預設 HTTP 連接埠是 9529,路徑以 /otel/v1/ 開頭。

OTLP 如何傳送一批資料?

  1. 組成請求。 SDK 匯出器或 Collector 會將遙測資料整理成 OTLP 匯出請求。
  2. 送出請求。 gRPC 使用一元呼叫,HTTP 使用 POST。依傳送端和接收端的設定選擇 gzip 壓縮、TLS 和驗證方式。
  3. 讀取回應。 完全成功代表當前接收端接受了這個批次。OTLP/HTTP 的完全成功和部分成功都回傳 HTTP 200。如果有 partial_success 欄位,要看拒收數量和診斷訊息。也可能拒收數為零,只有警告。收到這類回應後,匯出器不得重送同一個請求。

OTLP/HTTP 將 429、502、503、504 列為可重試的 HTTP 錯誤碼。有 Retry-After 時依其指示等待,否則採用指數退避。其他 4xx 和 5xx 不重試。例如遇到 400 時應先檢查請求內容。OTLP/gRPC 則依 gRPC 狀態碼與錯誤詳細資訊判斷,例如 UNAVAILABLE 可以重試。

收件確認只涵蓋相鄰的傳送端和接收端。Collector 接受資料後,還需要確認後端有沒有收到並儲存。如果確認回應在網路上遺失,重送還可能讓同一批資料出現兩次。OTLP 規範(英文)

OTLP 資料模型

追蹤、指標與日誌使用同樣的外層結構,實際的 Protobuf 欄位依訊號而異。

Export<Signal>ServiceRequest
└── resource_<signal>[]
    ├── resource (service.name, host.name, …)
    └── scope_<signal>[]
        ├── scope (name, version, …)
        └── spans[] / metrics[] / log_records[]

Span 包含 trace_id、span_id、適用時的父 Span ID,以及狀態和屬性等欄位。指標有 Sum、Gauge、Histogram、ExponentialHistogram 等類型。日誌記錄可包含事件時間、嚴重度、內容和屬性,也可帶上追蹤上下文。

以追蹤為例,Protobuf 欄位是 resource_spans 和 scope_spans。OTLP JSON 使用 traceId 這類 lowerCamelCase 欄位名,Trace ID 和 Span ID 用十六進位字串,列舉值用整數。若自行組裝 JSON,先確認輸出符合這些規則。

gRPC 和 HTTP 怎麼選?

比較項目 OTLP/gRPC OTLP/HTTP
標準預設連接埠 4317 4318
請求與連線 透過 gRPC 連線發出一元匯出請求 HTTP POST,可重複使用連線
編碼 二進位 Protobuf 二進位 Protobuf 或 OTLP JSON,視接收端而定
代理伺服器需求 必須能正確轉送 gRPC 必須允許 POST、路徑與 Content-Type
除錯 使用能讀取相應服務定義的 gRPC 用戶端 用 curl POST 正確編碼的有效內容

先選 SDK、代理伺服器與接收端都支援的方式。兩種都能用時,再以實際的批次大小和壓縮設定比較輸送量與資源用量。用 HTTP 傳送二進位 Protobuf 時,Content-Type 是 application/x-protobuf。標準預設路徑分別是 /v1/traces、/v1/metrics、/v1/logs,設定要以實際接收端為準。

如何從應用程式接入 OTLP?

  1. 從應用程式直接匯出。 以 OpenTelemetry SDK(英文) 或受支援的自動埋點產生遙測資料,再按接收端設定匯出協定和端點。
  2. 經 Collector 轉送。 OpenTelemetry Collector(英文) 接收資料後,依管線設定批次處理、篩選或去識別敏感資料,再匯出到後端。
  3. 轉換現有追蹤格式。 Collector 發行版若包含 Jaeger 或 Zipkin 接收器,可以啟用符合傳送端格式的接收器,再經 OTLP 匯出。先核對原有協定、欄位對應和追蹤上下文。

若要送到觀測雲,先啟用 DataKit 的 OpenTelemetry 收集器(簡體中文) 和所需訊號的匯出器。gRPC 範例使用 127.0.0.1:4317 回送位址。從另一台主機或網路命名空間傳送時,要讓傳送端能連到設定的接收位址。HTTP 選用 http/protobuf,預設連接埠是 9529,三個預設路徑為 /otel/v1/traces、/otel/v1/metrics、/otel/v1/logs。

下列範例適用於可信任的測試網路和 DataKit 預設 HTTP 路徑,使用明文連線。請將主機名稱換成實際位址。

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://datakit-host:9529/otel

通用 HTTP 端點是基礎 URL,符合規範的匯出器會附加各訊號的路徑。若設定 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 等個別訊號變數,則要填入完整 URL,例如 http://datakit-host:9529/otel/v1/traces。指標和日誌也是同樣的規則。憑證或驗證資訊由接收端或閘道的要求決定,觀測雲工作空間則由 DataKit 的實際接入設定決定。OTLP 匯出器設定(英文)

送出一批可辨識的測試資料,再分別查詢各訊號是否出現在預期工作空間。Collector 已設定的篩選和敏感資料處理仍會在匯出前執行。若要從日誌查看追蹤,還需要相符的 Trace ID,以及查得到的追蹤資料。

常見問題

怎麼保護 OTLP 連線? 資料要經過不受信任的網路時,請設定 TLS 並驗證接收端憑證。身分驗證依部署而定,例如使用閘道要求的標頭,或在支援的環境使用雙向 TLS。

OTLP 會成為效能瓶頸嗎? 編碼、壓縮、網路和接收處理都有成本。較大的批次可以降低每次請求的開銷,也可能增加等待時間或記憶體用量。gzip 可以省頻寬,但會消耗 CPU。調整時一起觀察匯出延遲、佇列用量和拒收數。

新版匯出器可以連舊版接收端嗎? Protobuf 能相容部分結構變更,例如較舊的接收端可以忽略不認識的欄位。仍應確認兩端都支援實際使用的訊號、編碼與選用功能。

可以只用觀測雲作為 OTLP 後端嗎? 若 DataKit 的接入方式涵蓋所需訊號與處理條件,就可以將這些遙測資料送往觀測雲。按訊號確認查詢、保留與告警所需的資料。

延伸閱讀

參考資料 OTLP 規範(英文) · 觀測雲 OpenTelemetry 接入文件(簡體中文) · DataKit 文件(簡體中文) · 觀測雲 APM(簡體中文)

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

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

立即開始

选择观测云版本

代码托管平台