OpenTelemetry Trace Pipeline¶
概念概覽
Trace Transport 常見斷點¶
核心知識¶
Trace Transport 常見斷點¶
# 錯誤：指向本地（dev 環境常見錯誤）
OTEL_EXPORTER_OTLP_ENDPOINT: "localhost:4318"
# 正確：指向叢集內 Tempo
OTEL_EXPORTER_OTLP_ENDPOINT: "tempo.monitoring:4318"
game-server、publisher、admin 三個服務各自需要確認 configmap 是否正確，不能只改其中一個。
Correlation Contract 標準欄位¶
以下欄位必須**同時**出現在 response headers、app logs、spans、audit logs：
request_id, trace_id, span_id,
user_id, account_id, session_id,
rpc/service, build_sha, config_version, env
任何一層缺少這些欄位，跨系統問題診斷時就必須靠肉眼拼湊。
多環境 Tracing 策略¶
- dev / staging / prod 共用同一個 Tempo cluster
- 每條 span 加
environmentlabel（dev/staging/prod） - Grafana 用 dashboard variable 過濾，避免混看
- 不需要部署三套 Tempo，節省維護成本
經驗教訓¶
-
Trace transport 是最大單點阻塞：endpoint 指向 localhost 讓整個 dev tracing 完全不可靠，但修復只是改一行 config
-
Admin tracing 不是純 Infra 問題：configmap 要改，server code 的 middleware chain 也必須補 tracing middleware
常見陷阱¶
-
只改了 configmap 但忘記 middleware chain 沒有掛 tracing middleware，trace 仍然不會產生
-
多環境共用 Tempo 但忘記在 query 加 environment filter，會看到混合資料
最佳實踐¶
-
所有服務的 OTEL endpoint 統一指向叢集內 tempo service，而非 localhost
-
Correlation ID 欄位要在 structured log schema 設計期就確定，後期補加會需要重構
相關概念¶
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-24 | 6295486a-8e60-49c7-a5da-f375c806641a | 定義 Go 遊戲後端完整的 Trace 傳輸鏈路修正方案，以及 Correlation Contract 的標準欄位清單 |