本章目標

讀完本章後、你應該能：

1. 解釋 LLM tracing 跟 traditional logging 的差異。
2. 用 OpenTelemetry GenAI semantic conventions 設計 span 結構。
3. 用 trace 做 cost / latency 監控跟 failure debug。
4. 把 production trace 餵回 LLM-as-judge 做品質迴路。
5. 對自己應用判斷該用 self-host vs SaaS observability platform。

Traditional logging 為什麼不夠

LLM 應用的 debug 問題對傳統 logging 太抽象：

LLM tracing 用「結構化 span + parent-child 關係 + 標準化 attribute」直接編碼這些訊息。

OpenTelemetry GenAI semantic conventions

OTel GenAI semconv 是 2024-2025 標準化中的 trace schema。核心概念：

 1Trace（一次 user query 從進來到 response）
 2  ├── Span: gen_ai.agent.invocation（agent loop iteration 1）
 3  │     ├── Span: gen_ai.client.operation（LLM call 1）
 4  │     │     attrs: model, temperature, input_tokens, output_tokens, cache_read
 5  │     ├── Span: gen_ai.tool.execution（tool: read_file）
 6  │     │     attrs: tool_name, input, output, duration
 7  │     └── Span: gen_ai.memory.read（retrieval）
 8  │           attrs: query, top_k, similarity_scores
 9  ├── Span: gen_ai.agent.invocation（iteration 2）
10  │     └── ...
11  └── Span: gen_ai.agent.terminate
12        attrs: reason, total_tokens, total_cost

主要 attribute 分類：

實作概要（Python 例）：

 1from opentelemetry import trace
 2from openinference.semconv.trace import SpanAttributes
 3
 4tracer = trace.get_tracer(__name__)
 5
 6with tracer.start_as_current_span("gen_ai.client.operation") as span:
 7    span.set_attribute(SpanAttributes.LLM_MODEL_NAME, "claude-sonnet-4-6")
 8    span.set_attribute(SpanAttributes.LLM_TEMPERATURE, 0.7)
 9
10    response = llm_client.chat(messages=...)
11
12    span.set_attribute(SpanAttributes.LLM_TOKEN_COUNT_PROMPT, response.usage.input_tokens)
13    span.set_attribute(SpanAttributes.LLM_TOKEN_COUNT_COMPLETION, response.usage.output_tokens)
14    span.set_attribute("gen_ai.usage.cached_tokens", response.usage.cache_read_tokens or 0)

實務上多用 framework auto-instrumentation（LangChain / LlamaIndex / Anthropic SDK 都有 OTel integration）、不必手寫 span。

Use case 1：Cost monitoring

Trace 是 LLM 應用 cost 監控的核心 — token usage attribute 內建、不必另外算。

實作模式：

11. Trace 端記錄 input_tokens / output_tokens / cached_tokens
22. Observability 平台用「per-model pricing table」算出 USD
33. Aggregate by：
4   - User（哪個 user 燒最多）
5   - Endpoint（哪條 API path 最貴）
6   - Feature（哪個 feature 最費 token）
7   - Time（哪天 spike）

典型 dashboard 指標：

Use case 2：Latency / failure debug

Trace 自然編碼 latency tree、能定位「哪個 span 卡」：

1User query → response total: 5.2s
2├── Agent iteration 1: 4.8s
3│   ├── LLM call (claude): 4.2s     ← 主要時間在這
4│   │   - prefill: 3.8s             ← prefill 太久、看 prompt 是否需要 cache
5│   │   - generation: 0.4s
6│   ├── tool: read_file: 0.5s
7│   └── memory: retrieval: 0.1s
8└── Agent iteration 2: 0.4s

從這 trace 看出「90% 時間在 prefill、開 prompt cache 可以救」、不必猜。

Failure debug：

1User query → response: ERROR
2├── Agent iteration 1: success
3│   └── LLM call: tool_call(run_bash, cmd="rm -rf /")
4├── Agent iteration 2: failure
5│   └── tool: run_bash: REJECTED by permission system
6└── Agent fallback: error response
7
8從 trace 看：tool call 被 permission 擋下、不是 LLM 自己亂、而是 user query 觸發危險 tool call、permission 正確擋下。

對應 6.2 tool use 權限模型 跟 hands-on permission-boundary 的判讀。

Use case 3：Production trace → eval loop

Production trace 是 LLM-as-judge 的最佳資料來源：

 1Production users
 2   ↓ 產生 trace
 3Trace storage（LangSmith / Phoenix / Langfuse）
 4   ↓ filter（e.g. user thumbs-down 的 trace）
 5   ↓ sample N 個
 6LLM-as-judge eval
 7   ↓ rubric scoring
 8找出系統性問題（哪類 query 品質差）
 9   ↓
10改 system prompt / tool / agent loop
11   ↓
12A/B test on production traces

這是 4.14 benchmarking 提的「in-house benchmark」的具體 implementation — production trace 是最真實的 benchmark dataset。

主流平台選型

判讀：

1. 個人 / 小流量：SaaS 免費 tier（LangSmith / Langfuse / Phoenix）夠用
2. 隱私敏感（user data 不能離本機）：Self-host（Langfuse / Phoenix self-hosted、或 OTel + Jaeger）
3. 已有 observability stack：用 OTel + 現有 Datadog / Grafana、別再加一層
4. 重 eval：Braintrust / Langfuse 的 eval feature 強

跟 4.9 production resource 的關係

4.5 寫 production resource 的 6 個 dimension（concurrency / latency / cost / storage / observability / reliability）、其中 observability 是 4.5 點到、本章展開。讀者讀完 4.5 知道「需要 observability」、本章補「具體怎麼做」。

設計失敗模式

1. 過度 instrument：每個 internal function 都加 span、trace overhead 大、實際 production noise 多

緩解：聚焦 LLM-related 跟跨 service 邊界、internal logic 不必 trace

2. PII / sensitive data 寫進 span attribute：user prompt、API key、會被 SaaS 平台看到

緩解：Span attribute 過 PII filter、敏感資料 hash / masking、跟 6.4 跨雲端邊界 結合

3. 不 sample：production 100% trace、storage / cost 爆

緩解：Production sample rate < 10%、error / outlier 100% capture

4. 沒設 trace 保留期：trace 越累積越多、舊 trace 沒人看但仍付儲存

緩解：明確保留 policy（如 7-30 天 hot、之後 archive 或刪）

5. Trace 不跟 metric 串：trace 是 sample、metric 是 aggregate、debug 要兩個一起看

緩解：cost / latency 也輸出 metric（Prometheus 等）、trace 補 specific instance debug

何時不需要 tracing

1. 純 demo / 個人玩：log 字串夠用
2. 單一 LLM call、無 agent loop：簡單到 grep log 也能 debug
3. 隱私極敏感且不 self-host：trace 內容流向 SaaS 是邊界、評估 risk
4. 每 request 都 trace 的 overhead > 收益：超低 latency 場景看是否 worth it

何時過時 / 何時不過時

不會過時的部分：

• LLM tracing 跟 traditional logging 的根本差異
• 結構化 span + parent-child 關係的 framing
• Cost monitoring / latency debug / failure debug 三大 use case
• Trace → eval 的閉環概念
• 5 個設計失敗模式

會變的部分：

• OTel GenAI semconv 的具體 attribute 名稱（仍在 stabilizing）
• 主流 SaaS 平台（每年 1-2 個新進入者）
• Auto-instrumentation 的支援度（持續擴展）
• 跟具體 framework 的整合方式

下一章

下一章：4.21 LLM-as-judge 評估方法、把 production trace 變成系統性 eval 的閉環。

完整鏈路

以使用者在 web app 點擊「結帳」為例，一次操作產生的觀測鏈路：

 1Browser: user clicks "checkout"
 2  → RUM SDK 建立 client span（type: resource / xhr）
 3  → HTTP POST /api/checkout + W3C traceparent header
 4    → Server middleware 提取 trace context
 5    → Server 建立 child span（checkout-handler）
 6      → DB query span（order insert）
 7      → Cache span（inventory check）
 8      → Queue span（event publish）
 9    → Server 回 200 + response body
10  → Browser 收到 response → resource timing 結束
11  → RUM SDK 關閉 client span（記錄 duration + status）
12  → 統一 trace waterfall：client span 是 root、server spans 是 children

鏈路的每一段都需要 trace context 正確傳遞。任何一段斷掉，trace waterfall 就會出現孤立的 span — server 端看到的 trace 跟 client 端看到的 trace 是兩條不相關的紀錄。

Trace context propagation

W3C traceparent header

W3C Trace Context 是跨 vendor 的標準 propagation 格式。Header 長這樣：

1traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
2              │  │                                │                  │
3              │  trace-id (32 hex)                 parent-id (16 hex) flags
4              version

RUM SDK 在發起 XHR / fetch 時把 traceparent 注入 request header。Server 的 trace SDK 從 header 提取 trace-id 和 parent-id，建立 child span。

Client 端注入

各 RUM SDK 的注入方式：

三者的共同模式：只對設定的 domain 注入 trace header。不設定白名單時，header 不會被注入到第三方 API（避免 information leakage）。

Server 端提取

Server 端的 trace SDK（OTel auto-instrumentation 或 vendor agent）從 incoming request 的 header 提取 trace context：

 1# OTel Python 範例 — auto-instrumentation 自動處理
 2# 不需要手動提取，middleware 自動讀 traceparent header
 3# 建立的 span 會繼承 client 傳來的 trace-id 和 parent-id
 4
 5# 手動提取（不用 auto-instrumentation 時）
 6from opentelemetry.propagate import extract
 7ctx = extract(carrier=request.headers)
 8with tracer.start_as_current_span("checkout-handler", context=ctx):
 9    # server logic
10    pass

CORS 限制

跨域請求時，browser 的 CORS preflight 會阻止非標準 header。Server 需要明確允許 trace header：

1Access-Control-Allow-Headers: traceparent, tracestate, sentry-trace, baggage

CORS 是 client-server trace 串接最常見的斷裂原因。Server 沒有回 Access-Control-Allow-Headers: traceparent 時，browser 會 strip 掉 trace header，server 端收到的 request 沒有 trace context，建立的 span 成為新的 root — 跟 client span 斷裂。

跨層 correlation 設計

Trace ID 串接

統一 trace-id 是最基本的 correlation。同一個 trace-id 下的所有 span（client + server）可以在 trace backend 的 waterfall view 裡按時間排列，看到完整的 request 路徑。

Session 跟 transaction 的 mapping

RUM SDK 的 session（使用者的一次造訪）包含多個 user action，每個 action 可能觸發多個 HTTP request。Mapping 關係：

1RUM session
2  └── user action (click "checkout")
3        ├── HTTP request /api/checkout  →  server transaction (trace)
4        ├── HTTP request /api/inventory →  server transaction (trace)
5        └── client-side rendering time

Datadog RUM 和 Sentry 都支援從 session replay 點進去看對應的 server trace。這個 mapping 靠的是 RUM event 裡記錄的 trace-id，跟 server trace backend 裡的同一個 trace-id 做 join。

Breadcrumbs 跟 server log 的時間對齊

RUM SDK 收集的 breadcrumbs（使用者操作序列：page view → button click → form submit）跟 server-side log 的 timestamp 需要可比對。時間對齊的前提是 client 和 server 的 clock 差距在可接受範圍（通常 < 1s）。

NTP 同步的 server 端 clock 通常精準。Client 端（browser）依賴使用者裝置的系統時間，可能偏差數秒到數分鐘。RUM SDK 通常會記錄 relative timing（相對於 session 開始的 offset），而非絕對 timestamp，來降低 clock skew 的影響。

Error correlation

Client-side JS error 跟 server-side 5xx 可能是同一個問題的兩面。Correlation 方式：

• 同一 trace-id：client error 發生在某個 HTTP request 的 response 處理中，該 request 的 trace-id 跟 server-side 500 的 trace-id 相同 — 直接 correlation
• 時間窗 + endpoint：client error 沒有 trace-id（例如 CORS block 導致 request 沒發出），用時間窗 + endpoint 模式做 fuzzy correlation
• Server 無異常但 client 報錯：client-side rendering error（JSON parse failure、type error），server 端看不到 — 需要 RUM 獨立分析

Evidence package 整合

把 client-side 訊號納入 4.20 Observability Evidence Package 時，需要額外記錄：

Client perceived latency 跟 server-side latency 的差異本身就是一個觀測訊號。差異穩定在 50ms 是正常的 network overhead；差異突然從 50ms 跳到 500ms 代表網路或 CDN 出了問題 — 而這個問題 server-side dashboard 完全看不到。

失敗場景判讀

Vendor 整合模式

同 vendor 組合的串接最自然。跨 vendor 組合只要雙方都支援 W3C Trace Context，trace-level correlation 可以通；但 session-level 的功能（session replay → server trace）需要同 vendor 才有。

交接路由

• 4.10 Client-side / Synthetic / RUM：概念定位和 vendor 選型
• 4.3 Tracing Context：server-side trace context 設計
• 4.22 Checkout API Evidence Package：evidence 整合到 release gate
• 4.20 Observability Evidence Package：evidence 欄位標準
• Monitoring 03 SDK 設計：client-side SDK 埋點設計
• Monitoring 06 商業方案：Sentry / Datadog RUM 的 client-side 能力比較
• 監控資料的雙重用途：同一份 event data 如何同時服務行為分析與訊號治理