OpenTelemetry 可觀測性三種訊號（Traces、Metrics、Logs）與 Exporters

什麼是 OpenTelemetry

OpenTelemetry（OTel）是一套開源的可觀測性標準與 SDK，統一了蒐集 Traces、Metrics、Logs 的方式，讓應用程式可以不綁定特定後端（Jaeger、Zipkin、Datadog 等）地輸出遙測資料。

三種訊號（Signals）

1. Traces & Spans

Trace 代表一次完整的操作鏈（例如：處理一個使用者請求的全過程）。

Span 是 Trace 的最小單位，記錄一段工作的開始/結束時間與屬性：

1
2
3
4
5
Trace: 處理訂單請求
├── Span: route_request          (root span)
│   ├── Span: parse_order_message
│   ├── Span: call_llm           (LLM 推論)
│   └── Span: create_order       (DB 寫入)

每個 Span 帶有：

  • trace_id：所屬 Trace 的唯一 ID
  • span_id：自身的唯一 ID
  • parent_span_id：父 Span 的 ID
  • attributes：任意 key-value 屬性（如 gen_ai.agent.name）

2. Metrics

Metric 是數值型的聚合量測，適合監控系統健康狀態：

  • Counter：只增不減（如請求總數、錯誤數）
  • Gauge：可增可減的當前值（如記憶體用量）
  • Histogram：分佈統計（如請求延遲的百分位數）

3. Log Records

OTel Log 是結構化的事件記錄，與 Trace 可以關聯（同一個 trace_id/span_id），但也可獨立存在。

每筆 Log Record 帶有：

  • timestamp：事件發生時間
  • severity：嚴重等級（INFO、WARN、ERROR…）
  • body：事件內容
  • attributes：額外欄位（如 token 用量、model 名稱）
  • resource：產生此 log 的服務資訊（service.name、service.version）

OTel SDK Pipeline

三種訊號共用同一套 SDK 架構：

1
2
3
4
5
6
7
8
9
Instrumentation（程式碼產生遙測）
    ↓
Provider（TracerProvider / MeterProvider / LoggerProvider）
    ↓
Processor（BatchProcessor、SimpleProcessor、自訂...）
    ↓
Exporter（OTLP、Jaeger、Zipkin、自訂...）
    ↓
後端（Aspire Dashboard、Grafana、Datadog...）

Exporter 負責將蒐集到的訊號送到後端：

Exporter 協定 適合場景
otlptracehttp OTLP/HTTP 送 Traces 到任何 OTLP 相容後端
otlploghttp OTLP/HTTP 送 Logs 到任何 OTLP 相容後端
自訂 Exporter 任意 寫檔、送 DB、客製化格式

與 ADK 的關係

Google ADK（Agent Development Kit）內建 OTel 支援，會自動為每次 LLM 呼叫產生：

  • Span：記錄 invoke 的起訖時間、agent 名稱、session ID
  • Log Record：記錄 LLM 的 input prompt 和 output content、token 用量

開發者只需設定 Exporter 和後端，不需手動埋點：

1
2
3
4
5
6
// ADK 自動產生 OTel 資料，開發者只需設定 Exporter
err = telemetry.Setup(ctx,
    telemetry.WithResource(res),
    telemetry.WithLogRecordProcessors(myProcessor),
    telemetry.WithGenAICaptureMessageContent(true),  // 開啟 prompt/response 內容捕捉
)