OpenTelemetry 完整教學 2026:API 慢在哪一次看穿

分散式追蹤的門檻不在概念,而在設定細節。這篇在一台 2 核心 VPS 實測部署 OpenTelemetry Collector 0.165.0 加 Jaeger,量出兩層 batch 造成的 4.5 秒延遲、20% 取樣的真實命中率與記憶體佔用,並列出五個實測踩到的坑。

  • Dennis
  • 9 分鐘閱讀
OpenTelemetry 完整教學 2026:API 慢在哪一次看穿

一句話結論

OpenTelemetry(以下簡稱 OTel)是一套廠商中立的可觀測性標準:你的應用只負責產生 trace/metric/log 並用 OTLP 協定送出去,要存到 Jaeger、Tempo、Prometheus 或雲端服務,之後再換即可。實際部署的門檻不在概念,而在設定細節——這篇把設定檔、指令與實測數字全部攤開。

為什麼日誌不夠用

症狀只有日誌有分散式追蹤
「這支 API 慢」每支函式自己印時間戳,靠人工加總一個 trace 裡列出每個 span 的耗時,一眼看出瓶頸在哪一段
「A 服務呼叫 B 服務」兩邊日誌時間對不起來,時區還可能不同同一個 trace ID 貫穿兩邊,parent-child 關係明確
「只有 3% 的請求慢」grep 到手軟用 trace 的 duration 排序,直接抓尾巴
「是資料庫還是程式碼慢」分不出來資料庫的 client span 就掛在請求底下

OTel 的定位常被誤解成「一套工具」,其實它有三層:SDK(在應用裡)→ Collector(獨立的代理程式)→ Backend(Jaeger、Tempo 等)。本文的實作就是這三層各跑一份。

三個信號與它們的關係

信號回答什麼問題常見後端
Traces這次請求經過哪些服務、每一段花多久Jaeger、Tempo、Zipkin
Metrics一段時間的趨勢(QPS、延遲分位、錯誤率)Prometheus、Mimir
Logs某一刻發生什麼事(含 trace ID 關聯)Loki、Elasticsearch

三者可以互相跳轉:從 metric 的尖峰找到對應時間的 trace,再從 trace 找到那次的 log。這就是為什麼「先把 trace 做好」通常投資報酬率最高——它是唯一能直接回答「慢在哪一段」的信號。

一表看懂:每個元件負責什麼

元件跑在哪責任本文版本
SDK(opentelemetry-sdk)應用行程內產生 span、取樣、批次送出Python 1.45.2
自動 instrumentation應用行程內攔截 Flask、requests 等框架自動產生 span0.66b2
Collector獨立容器接收 OTLP、轉換、批次、匯出到一個或多個後端contrib 0.165.0
Backend獨立容器儲存與查詢Jaeger all-in-one

一個常見疑問:應用不能直接送 Jaeger 嗎? 可以,Jaeger 自己就開 OTLP 埠。但多一層 Collector 有三個好處:應用只認一個 endpoint、要換後端不必改程式、可以在中間統一補資源屬性與做取樣決策。生產環境幾乎都留這一層。

實作:15 分鐘跑起來

以下四份檔案放在同一個目錄,全部都在一台 2 vCPU 的 VPS 上實測過。

1. docker-compose.yaml

services:
  collector:
    image: otel/opentelemetry-collector-contrib:0.165.0
    command: ["--config=/etc/otel/collector.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/collector.yaml:ro
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
      - "13133:13133" # health_check
    depends_on:
      - jaeger
    restart: unless-stopped

  jaeger:
    image: jaegertracing/all-in-one:latest
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - "16686:16686" # Jaeger UI
    restart: unless-stopped

版本請固定 tag(這裡用 0.165.0,2026-11-07 發布)。用 latest 在教學或 CI 裡等於每天換一次考試題目。

2. collector.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 256
    spike_limit_mib: 64
  batch:
    timeout: 1s
    send_batch_size: 512
  resource:
    attributes:
      - key: deployment.environment
        value: demo
        action: upsert

exporters:
  debug:
    verbosity: normal
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  telemetry:
    metrics:
      level: normal
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, resource, batch]
      exporters: [otlp/jaeger, debug]

四個地方值得記住:

  • processors 的順序是實際執行順序。memory_limiter 一定放第一個(先擋住記憶體爆掉),batch 放最後(把資料變大再送出去最省)。
  • debug exporter 是最好用的除錯工具,它會把收到的每一個 span 印在 Collector 的日誌裡。沒有它,你只能對著空白的 Jaeger 猜。
  • otlp/jaeger 這種寫法是「具名 exporter」,同一種類型可以宣告多個(例如同時送 Jaeger 與雲端)。
  • tls: insecure: true 只適用容器內的明碼連線,跨主機一定要拿掉。

改完設定先驗語法,不要直接重啟:

docker run --rm -v ./collector.yaml:/etc/c.yaml \
  otel/opentelemetry-collector-contrib:0.165.0 validate --config=/etc/c.yaml

這道指令在本文實測回傳 exit code 0、無輸出(沒有錯誤就是成功)。設定寫錯時它會直接指出是哪個欄位不對,比看容器重啟 20 次快得多。

3. 一支會被追蹤的 Flask 服務

import os
import time

import requests
from flask import Flask, jsonify

app = Flask(__name__)
INVENTORY_URL = os.environ.get("INVENTORY_URL", "http://127.0.0.1:8100/inventory")


def check_cart(items):
    time.sleep(0.05)
    return len(items) > 0


def reserve_stock(sku, qty):
    """真的發一個 HTTP 呼叫,讓 OTel 自動產生 client span。"""
    try:
        requests.get(f"{INVENTORY_URL}?sku={sku}&qty={qty}", timeout=1.0)
    except Exception:
        pass
    time.sleep(0.03)


def write_order(order_id):
    time.sleep(0.02)
    return order_id


@app.get("/checkout")
def checkout():
    items = ["SKU-A", "SKU-B"]
    if not check_cart(items):
        return jsonify({"error": "empty cart"}), 400
    reserve_stock("SKU-A", 1)
    write_order("ORD-1001")
    return jsonify({"ok": True, "order": "ORD-1001"})


@app.get("/inventory")
def inventory():
    time.sleep(0.01)
    return jsonify({"sku": "SKU-A", "stock": 42})


@app.get("/slow")
def slow():
    time.sleep(0.4)
    return jsonify({"ok": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8100)

4. 啟動與送第一批 trace

docker compose up -d

python3 -m venv .venv && . .venv/bin/activate
pip install opentelemetry-distro opentelemetry-exporter-otlp flask requests
opentelemetry-bootstrap -a install   # 自動安裝對應的 instrumentation 套件

OTEL_SERVICE_NAME=order-service \
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
opentelemetry-instrument python app.py

opentelemetry-instrument 是關鍵:它是一個啟動器,會在你指定的 python 前面插入自動 instrumentation,不需要改一行應用程式碼。這裡的環境變數決定了三件事:服務名稱、送到哪裡、用什麼協定。

送幾個請求,然後打開 http://<主機>:16686:

for i in 1 2 3; do curl -s -o /dev/null http://127.0.0.1:8100/checkout; done
curl -s -o /dev/null http://127.0.0.1:8100/slow

實測:你會看到什麼

實測結果如下(2 vCPU VPS,Collector 與 Jaeger 都跑在同一台):

端點trace 裡的 span 數總耗時
GET /checkout3 個約 116–118 ms
GET /slow1 個400.9 ms

/checkout 那 3 個 span 是最值得理解的部分:

  1. GET /checkout(server span,約 118 ms)——請求的根
  2. GET(client span,約 15 ms)——requests 套件被自動攔截產生的對外呼叫
  3. GET /inventory(server span,約 11 ms)——下游服務自己的 server span

第 2 與第 3 個 span 證明了一件事:trace context 透過 HTTP 標頭自動傳遞。requests 會自動注入 traceparent,Flask 的 instrumentation 會自動解析,所以你什麼都不用寫,跨服務的父子關係就接起來了。這是 OTel 最實用的魔法,也是為什麼「先裝自動 instrumentation」通常比手刻 span 划算。

要看實際的 JSON 而不是 UI:

curl -s "http://127.0.0.1:16686/api/services"
curl -s "http://127.0.0.1:16686/api/traces?service=order-service&limit=5"

關鍵設定:為什麼你的 span 要等好幾秒才出現

這是本文最重要的一段,也是最容易讓人誤判「OTel 壞了」的地方。

OTel 有兩層批次,兩層都會延遲資料出現在 UI 的時間。 第一層是 SDK 的 BatchSpanProcessor(預設每 5 秒 flush 一次),第二層是 Collector 的 batch processor(本文原先設 5 秒)。實測三種組合,方法是「送出請求後每 0.1 秒輪詢 Jaeger API,直到新 trace 出現」:

SDK flush 間隔Collector batch timeout實測可見延遲(3 次)平均
預設 5000 ms5 s0.63 s、4.08 s約 2.4 s(依落在窗口哪個位置,變異很大)
500 ms5 s2.15 s、4.42 s、4.51 s3.70 s
500 ms1 s0.43 s、0.53 s、0.53 s0.50 s

第二列的結果最反直覺:把 SDK 的 flush 調快,整體反而沒變快,因為瓶頸在下游的 Collector batch。這個量測順序很重要——如果只調 SDK,你會以為「調了沒用」而放棄。

對應的設定:

# SDK 端(Python)
export OTEL_BSP_SCHEDULE_DELAY=500     # 毫秒
# Collector 端
processors:
  batch:
    timeout: 1s

生產環境的取捨:不要把所有東西都調成 1 秒。批次越大、次數越少,後端壓力越小;把 flush 調快的代價是更多的請求數。診斷用的環境調快,長期收集的環境維持 5 秒是合理的。

取樣:不要什麼都收

全收的代價是流量與儲存。Python SDK 內建幾種取樣器,用環境變數就能切換:

OTEL_TRACES_SAMPLER=traceidratio OTEL_TRACES_SAMPLER_ARG=0.2

實測:設定 20%、送出 40 個請求,Jaeger 實際收到 10 條 trace(25%)。樣本小的時候比例會晃動,這是二項分布的隨機性,不是設定錯。

取樣器適用情境
always_on開發、除錯、低流量服務
traceidratio高流量服務的降量(依 trace ID 雜湊,同一個 trace 的決策一致,不會出現「半條 trace」)
parentbased_*微服務的標準做法:尊重上游決策,避免服務之間取樣不一致
tail sampling(Collector 端)想要「保留所有錯誤與慢請求」時——決策發生在 Collector,看得到整條 trace 才判斷

traceidratio 的關鍵性質是決策可重現:同一個 trace ID 在任何服務算出來的結果都一樣,所以不會出現 A 服務記、B 服務漏的斷裂。

五個實測踩到的坑

坑症狀原因與修法
服務名變成 unknown_service:pythonJaeger 的下拉選單多出一個詭異的名字,你的服務找不到沒設 OTEL_SERVICE_NAME。實測確實會出現這個預設值,改設環境變數即可
協定與埠不對,回 415用 HTTP 協定打 gRPC 的埠,請求被拒4317 是 gRPC、4318 是 HTTP。實測對 :4318/v1/traces 送錯 Content-Type 會回 415,OTEL_EXPORTER_OTLP_PROTOCOL 要與埠一致
容器裡連不到宿主機的 Collector應用在容器內、Collector 在宿主機,怎麼都送不到OTEL_EXPORTER_OTLP_ENDPOINT 預設是 localhost,在容器裡指的是容器自己。改用服務名(compose)或 host.docker.internal
UI 全空但程式沒報錯以為設定沒生效兩個檢查點:Collector 日誌有沒有 debug exporter 的輸出(有代表收到了)、Jaeger 的 /api/services(有代表存進去了)。中間斷在哪一段就修那一段
opentelemetry-instrument python 用錯直譯器啟動就 ModuleNotFoundError,看起來像套件沒裝啟動器會用 PATH 上的 python。實測在 venv 裡仍失敗,要寫成 opentelemetry-instrument .venv/bin/python app.py

第三個坑還有一個變形:用 latest 拉映像。本文實測時 Collector 的 validate 子指令、telemetry.metrics.level 這類設定欄位都跟版本有關,滾動更新會讓去年的教學突然失效。

資源成本:先量再決定要不要上

同一台 2 vCPU VPS、閒置狀態下的記憶體:

容器記憶體
Collector(contrib 0.165.0)41.8 MiB
Jaeger all-in-one14.63 MiB

這是「什麼都沒在收」的基準值。真實成本主要取決於每秒 span 數 × 每 span 大小,以及後端保留策略。以一個日請求百萬級的服務來說,Jaeger all-in-one 用記憶體內儲存絕對不夠——它設計上是示範與短期查詢用的,正式環境要接 Elasticsearch/Cassandra,或改用 Tempo 這類以物件儲存為底的後端。

正式環境的三個決策

  1. Agent 還是 Gateway? 每台主機跑一個 Collector 當 agent(貼近應用、分擔流量),再集中到一個 gateway(統一補屬性、做尾端取樣)。規模小的時候一個 Collector 就夠,但不要讓應用直接打後端,否則未來換後端要改所有服務。
  2. 尾端取樣放哪裡? 想「錯誤全留、慢請求全留」就得在 Collector 做 tail sampling,這需要整條 trace 都經過同一個 Collector 實例(或做 load balancing 時用 trace ID 做一致性雜湊)。
  3. 資源屬性一次定好。 service.name、deployment.environment、service.version 這三個沒定好,之後查詢會非常痛苦。本文在 Collector 用 resource processor 統一補上 deployment.environment=demo,實測在 debug 輸出與 Jaeger 都看得到——這招可以讓應用不必管環境標籤。

誰適合、誰不需要

適合:有 2 個以上服務會互相呼叫、正在被「不知道哪裡慢」困住、已經有 Prometheus 但指標看不出瓶頸、需要跨服務追一個請求的團隊。

還不需要:只有一支單體服務、有明確的 APM 需求且預算充足(商業 APM 的開箱體驗仍勝過自架)、或者連日誌都還沒結構化——先把日誌寫好,OTel 的效果會好很多。

最小起步建議:先只做 traces、只裝自動 instrumentation、後端用 Jaeger all-in-one,跑一天看看資料長什麼樣,再決定要不要接 metrics 與 log。一次上三種信號,通常會卡在設定而不是得到洞察。

站內延伸閱讀

原始來源

  • OpenTelemetry 官方文件:https://opentelemetry.io/docs/
  • Collector 設定參考:https://opentelemetry.io/docs/collector/configuration/
  • OpenTelemetry Collector releases(v0.165.0,2026-11-07):https://github.com/open-telemetry/opentelemetry-collector-releases/releases
  • Python 自動 instrumentation:https://opentelemetry.io/docs/languages/python/automatic/
  • Jaeger 官方文件:https://www.jaegertracing.io/docs/

📬 訂閱 most.tw 電子報

每週精選 AI 工具教學與技術乾貨,直接送到你的信箱。免費、隨時可退訂。

訂閱即表示同意收到 most.tw 電子報,隨時可一鍵退訂。

💬 有問題想討論?加 LINE 聯絡我

歡迎透過 LINE 官方帳號直接留言,我會盡快回覆你的問題。

加入 LINE 好友