一句話結論
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 等框架自動產生 span | 0.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放最後(把資料變大再送出去最省)。debugexporter 是最好用的除錯工具,它會把收到的每一個 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 /checkout | 3 個 | 約 116–118 ms |
GET /slow | 1 個 | 400.9 ms |
/checkout 那 3 個 span 是最值得理解的部分:
GET /checkout(server span,約 118 ms)——請求的根GET(client span,約 15 ms)——requests套件被自動攔截產生的對外呼叫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 ms | 5 s | 0.63 s、4.08 s | 約 2.4 s(依落在窗口哪個位置,變異很大) |
| 500 ms | 5 s | 2.15 s、4.42 s、4.51 s | 3.70 s |
| 500 ms | 1 s | 0.43 s、0.53 s、0.53 s | 0.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:python | Jaeger 的下拉選單多出一個詭異的名字,你的服務找不到 | 沒設 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-one | 14.63 MiB |
這是「什麼都沒在收」的基準值。真實成本主要取決於每秒 span 數 × 每 span 大小,以及後端保留策略。以一個日請求百萬級的服務來說,Jaeger all-in-one 用記憶體內儲存絕對不夠——它設計上是示範與短期查詢用的,正式環境要接 Elasticsearch/Cassandra,或改用 Tempo 這類以物件儲存為底的後端。
正式環境的三個決策
- Agent 還是 Gateway? 每台主機跑一個 Collector 當 agent(貼近應用、分擔流量),再集中到一個 gateway(統一補屬性、做尾端取樣)。規模小的時候一個 Collector 就夠,但不要讓應用直接打後端,否則未來換後端要改所有服務。
- 尾端取樣放哪裡? 想「錯誤全留、慢請求全留」就得在 Collector 做 tail sampling,這需要整條 trace 都經過同一個 Collector 實例(或做 load balancing 時用 trace ID 做一致性雜湊)。
- 資源屬性一次定好。
service.name、deployment.environment、service.version這三個沒定好,之後查詢會非常痛苦。本文在 Collector 用resourceprocessor 統一補上deployment.environment=demo,實測在debug輸出與 Jaeger 都看得到——這招可以讓應用不必管環境標籤。
誰適合、誰不需要
適合:有 2 個以上服務會互相呼叫、正在被「不知道哪裡慢」困住、已經有 Prometheus 但指標看不出瓶頸、需要跨服務追一個請求的團隊。
還不需要:只有一支單體服務、有明確的 APM 需求且預算充足(商業 APM 的開箱體驗仍勝過自架)、或者連日誌都還沒結構化——先把日誌寫好,OTel 的效果會好很多。
最小起步建議:先只做 traces、只裝自動 instrumentation、後端用 Jaeger all-in-one,跑一天看看資料長什麼樣,再決定要不要接 metrics 與 log。一次上三種信號,通常會卡在設定而不是得到洞察。
站內延伸閱讀
- Grafana + Prometheus + Loki 監控完整教學
- Docker Compose healthcheck 實戰:等到健康才啟動
- Nginx 反向代理完整教學 2026:proxy_pass、WebSocket 與 HTTPS
原始來源
- 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/
