從任務設計、合成環境、Agent 架構、評分機制到報告輸出，逐一解析這個開放 benchmark 的每個組件——以及 Gemini 3 Flash Preview 的完整實測結果

先說清楚這在解決什麼問題

目前多數 LLM benchmark 測的是「知識」：模型知不知道 PromQL 的語法，知不知道什麼是 p99 latency。但 SRE 的工作從來不只是知識問題——真正的挑戰是：能不能在一個陌生的監控環境裡，自主操作工具，把分散在 metrics、logs、traces 三個訊號裡的線索拼起來，找到根因？

metrics 像體溫計（數字趨勢）、logs 像病歷（事件記錄）、traces 像 X ▎ 光（請求在系統內怎麼流動）。on-call 的難處是這三種資料分別存在三個系統裡，要自己拼起來。

Grafana Labs 的工程師 Yasir Ekinci 和 Jack Gordley 在 GrafanaCON 2026 發表 o11y-bench 時，特別強調了 observability 任務的本質差異：

"In observability, the dangerous mistakes are often the subtle ones."

一個查詢語法正確，但選了錯誤的 metric series；一個 dashboard 在 UI 上看起來正常，但 variable binding 沒有真正連上 panels——這類錯誤在一般的 benchmark 裡不會被抓到，但在真實 on-call 場景裡會導致錯誤判斷。這就是為什麼需要一個讓 agent 面對真實 stack、結果由程式直接驗證的 benchmark。

o11y-bench 嘗試回答這個問題。它是由 Grafana Labs 開發的開放 benchmark，基於 Harbor 框架運作，讓 LLM agent 在一個真實跑起來的 Grafana + Prometheus + Loki + Tempo stack 上解題，評分後對外公開 leaderboard。

• Harbor → benchmark 執行框架（負責起容器、跑 agent、收結果）

• Prometheus → 存 metrics、Loki → 存 logs、Tempo → 存 traces

整體架構鳥瞰

跑一次 benchmark 的流程大致如下：

tasks-spec/  →  (sync)  →  tasks/
                                ↓
                    Harbor 起一個 trial
                                ↓
              ┌─────────────────────────────┐
              │   docker/ sidecar 容器          │
              │   Prometheus + Loki + Tempo    │
              │   + Grafana + mcp-grafana      │
              └─────────────────────────────┘
                                ↓
              ┌─────────────────────────────┐
              │   agents/ agent 容器            │
              │   讀題目 → 呼叫 MCP 工具          │
              │   → 寫出 trajectory.json       │
              └─────────────────────────────┘
                                ↓
              ┌─────────────────────────────┐
              │   grading/ verifier            │
              │   deterministic checks         │
              │   + LLM rubric (Claude)        │
              └─────────────────────────────┘
                                ↓
              jobs/<job-name>/result.json
              jobs/<job-name>/run_report.html

以下逐一拆解每個組件。

組件一：tasks-spec/ — 題目的源頭

tasks-spec/
  prometheus_query/   (16 題)
  loki_query/         (10 題)
  tempo_query/        (13 題)
  grafana_api/        (6 題)
  dashboarding/       (7 題)
  investigation/      (11 題)

tasks-spec/ 是整個專案唯一需要手動維護的 task 資料，tasks/ 是從它生成的 output（不要直接編輯）。執行 mise run setup:sync 會把所有 YAML 轉換成 Harbor 能讀的任務格式。

YAML 格式設計

每個 task 的核心欄位：

id: promql-subquery-peak-error-rate
category: prometheus_query
statement: |
  六小時內，payment-service 的 error rate 峰值是多少？

checks:
  - name: Response cites a trace ID that appears in Tempo tool results
    weight: 70
    type: grounding
    params:
      mode: tool_trace_id

rubric:
  - criterion: The final response states the peak error rate accurately.
    weight: 65
    fact:
      kind: query
      backend: prometheus
      query: max_over_time(rate(http_requests_total{job="payment-service",status=~"5.."}[5m])[6h:1m])

有幾個刻意的設計決策值得注意：

• statement 用自然語言，不給語法提示：不寫「用 PromQL subquery」，只說「六小時內的峰值是多少」。這樣才是真正測 agent 能不能選對工具。

• 數字精確性用 fact：benchmark 自己跑那個 PromQL 拿到 ground truth，讓 judge 比對，而不是把答案寫死在 criterion 文字裡（否則改了資料就要改題目）。

• 具體實體用 grounding check：trace ID 不靠 LLM 判斷，程式直接比對。

grounding check：強制答案裡的具體值（trace ID、service 名）必須真的在工具回傳結果裡出現，防 LLM 編造

一道題包含三個東西：題目（statement）、程式驗的部分（checks）、LLM 評分的部分（rubric）。「rubric」是 LLM 評估常用語：一份評分準則清單。「LLM rubric」就是讓另一個 LLM（這裡是 Claude）當 judge，照清單逐條打勾 YES/NO。後面組件四會展開細節。

六個類別的能力層次

PromQL（16 題）—— 結構化查詢的精確度

最基礎的一層。題目用自然語言描述，不給語法提示，例如：

「找出六小時內 payment-service 的 error rate 峰值」

模型需要自己決定用 subquery、offset、topk 還是 rate，並且對計算出的數字做出正確解讀。

代表題目：

LogQL（10 題）—— 半結構化資料的處理能力

Loki 的 LogQL 比 PromQL 難在：必須先做 pipeline 解析（| json | __error__=""），才能對欄位做聚合。測試案例包括找最慢 endpoint（需要 unwrap duration_ms）、計算 p95 latency、區分 retry 造成的假 5xx 和真實錯誤。

代表題目：

TraceQL（13 題）—— 跨服務的因果推理

分散式追蹤是三個訊號裡最難操作的。測試重點：

• 能否準確引用真實的 trace ID（有 grounding check 防止幻覺）

• 能否沿著 call chain 追蹤 error 傳播路徑

• 能否用 TraceQL metrics 計算各 service 的 error rate

代表題目：

Grafana API（6 題）—— REST API 直接操作

不只是用 Grafana UI，而是要能直接操作 REST API 讀取 datasource 設定、搜尋 dashboard、檢查 panel 查詢內容。

Dashboarding（7 題）—— 能不能建出真實可用的東西

這類題目以 deterministic check 為主：agent 建完 dashboard 後，benchmark 直接打 Grafana API 驗證 panels 是否存在、datasource 是否正確、variable binding 是否真的生效。

dashboard-create-service-overview 是最複雜的 task，要求一次建立 5 種 panel type + 1 個 multi-value variable + 1 個 Loki annotation，並驗證 variable binding 在選不同 service 時真的生效。

Investigation（11 題）—— 跨訊號的根因分析

最困難的一層，也是最接近真實 on-call 工作的場景。沒有 deterministic check，全靠 LLM rubric。典型題目：

「api-gateway 出現 5xx，請判斷是自己的問題還是 downstream 傳上來的？」

評分標準包含：數字準確性（有 ground truth 對照）、推理是否基於工具結果而非憑空推測、結論是否區分主因和次要影響。

組件二：docker/ — 合成的 Observability 環境

docker/
  Dockerfile
  entrypoint.sh
  prometheus.yml  /  loki-config.yaml  /  tempo.yaml  /  datasources.yaml
  python/src/o11y_stack/
    generate_data.py           # 合成資料產生器
    provision_task_resources.py # task 專屬的 Grafana 資源

每次執行 benchmark trial，這個 sidecar 容器就從頭啟動，最終對外提供一個完整的 Grafana stack 加上 mcp-grafana（暴露 36 個 MCP 工具給 agent）。

啟動順序

容器啟動有嚴格的相依順序：

1. Loki + Tempo + Grafana 同時背景啟動
      ↓
2. 等 Loki、Tempo 的 /ready 端點回應
      ↓
3. generate_data.py — 產生 24 小時合成資料
   ├─ 寫 Prometheus TSDB block（用 promtool）
   ├─ 推 traces 到 Tempo（OTLP HTTP）
   └─ 推 logs 到 Loki（push API）
      ↓
4. 啟動 Prometheus（故意在這步才啟動）
      ↓   ← TSDB block 必須先存在才能被讀到
5. 等所有服務的 health endpoint
      ↓
6. provision_task_resources.py — 建立 task 需要的 dashboard
      ↓
7. 啟動 mcp-grafana（:8080）
      ↓
=== Environment Ready ===

Prometheus 故意在資料產生完才啟動，這是個有意思的工程細節：TSDB block 必須在 Prometheus 啟動前就存在才能被讀到，如果先啟動 Prometheus 再推資料，會有時序問題。

模擬的電商微服務系統

合成資料來自一個 5 個微服務的電商平台：

webapp → api-gateway → user-service
                     → order-service → user-service
                                     → payment-service
                     → payment-service

資料時間釘死在 scenario_time.txt，隨機種子 random.seed(42)，確保每次跑同一道題拿到完全相同的資料——這是跨模型、跨時間比較的基礎。

三段刻意設計的故障

資料裡藏了三段相互獨立的 incident，這是整個 benchmark 的核心：

Incident 1：Error Spike（資料結尾前 3 小時，持續 30 分鐘）

payment-service 大量出錯，cascading 傳遞：

故障前 2 分鐘：Loki 有 payment-service 和 order-service 的 deployment log，暗示是部署引發的。

Incident 2：Latency 劣化（資料結尾前 6 小時，持續 45 分鐘）

order-service 回應變 5 倍慢，upstream 連帶受影響。/api/orders 有 60% 機率被標成 slow request（duration_ms 500–3000ms）。

Incident 3：Cache Refresh Lag（資料結尾前 9 小時，持續 40 分鐘）

user-service auth cache 更新卡住。service_cache_refresh_lag_seconds metric 最高到 520 秒，Loki 有帶 lag_seconds 和 stale_keys 欄位的 warn log。

精心設計的陷阱：traces 裡的 error span status 只標在真正的根源 span。upstream 的 webapp 和 api-gateway 雖然回傳 HTTP 500，但 span status 是 OK。模型如果偷懶只看最外層，會找錯根因——必須真的沿著 call chain 往下追。

合成資料涵蓋 24 小時，「資料結尾」就是模擬的「現在時間」（即 scenario_time.txt 裡釘死的那個時刻）。上面三段 incident 的時間都是相對這個「現在」往回推。這樣設計是因為 agent 解題時是站在「資料結尾」這個固定時間點往回看。

Prometheus Metrics 清單

provision_task_resources.py

某些 task 需要環境裡預先存在某個 dashboard（例如「修復這個壞掉的 dashboard」），這個腳本在 Grafana ready 後讀取 /task/setup.json，把需要的 dashboard 建好並確認可讀後才結束。目前 9 個 task 有用到。

組件三：agents/ — 跑在容器裡的 Agent

agents/
  o11y_agent.py          # Harbor agent 入口（host 端）
  agent_runner.py        # 核心 loop（跑在 task 容器內）
  system_prompt.txt
  task_prompt.txt
  langchain_o11y_agent.py   # LangChain 版（示範用）
  gcx_opencode_agent.py     # 使用 gcx CLI 的替代版本

執行架構

Agent 分成兩層：

[Host]  O11yBenchAgent.run()         o11y_agent.py
          ├─ 上傳 agent_runner.py 進容器
          ├─ 轉傳 API keys 環境變數
          └─ 等容器結束，下載 trajectory.json
                   ↓
[容器]  agent_runner.py              (uv run 啟動)
          ├─ 連接 mcp-grafana（36 個工具）
          └─ while True loop

核心 Loop

while True:
    resp = await litellm.acompletion(messages, tools=mcp_tools)
    if no tool_calls:
        write trajectory, print "done", break
    for tc in tool_calls:
        out = await mcp_session.call_tool(tc.name, tc.args)
        messages.append(tool result)
    flush_trajectory()   # 每步都寫，partial work 不會丟失

設計上刻意簡單：純粹的 ReAct 循環，最多 50 步，透過 litellm 支援所有主流 provider。flush_trajectory() 每步都寫出，即使 trial 中途被取消也能保留部分紀錄。

Reasoning + Acting：模型輸出『下一步要做什麼』→ 執行工具 → 把結果丟回去 → 模型決定下一步，反覆到模型說『我答完了』。

Prompt 設計的關鍵細節

task_prompt.txt 有一個重要的時間控制：

<context>
Current time: {current_time}
</context>

{statement}

current_time 來自 O11Y_SCENARIO_TIME_ISO 環境變數（即 scenario_time.txt），強制 agent 把這個時間當作「現在」。如果 agent 用真實的 now() 查詢，拿到的資料範圍就會對不上合成資料，導致無法找到那三段 incident。

system_prompt.txt 裡有幾條關鍵指令：

• 必須基於工具回傳的資料做結論，不能靠記憶推測

• 建 Grafana dashboard 時一步給出完整 model

• Act autonomously. Do not ask the user for clarification.

Trajectory 格式（ATIF-v1.6）

每次 trial 結束產出 trajectory.json：

{
  "schema_version": "ATIF-v1.6",
  "agent": { "model_name": "gemini/gemini-3-flash-preview", ... },
  "steps": [
    { "step_id": 1, "source": "system", "message": "..." },
    { "step_id": 2, "source": "user",   "message": "題目內容" },
    { "step_id": 3, "source": "agent",  "tool_calls": [...] },
    { "step_id": 4, "source": "agent",  "message": "最終回答" }
  ],
  "final_metrics": {
    "total_cost_usd": 0.064,
    "total_tool_calls": 4,
    "elapsed_seconds": 23.3
  }
}

這個檔案是後續 regrade 和行為分析的基礎。評分系統只需要 trajectory.json，不需要重跑 agent。

trajectory（軌跡）就是 agent 整次解題的完整紀錄：每一步它說了什麼、呼叫了哪個 工具、拿到什麼回應，全部依時序存下來。後續評分只要讀這個檔，不需要再跑一次 agent。

替代 Agent

除了預設 agent，repo 還提供兩種替代實作：

組件四：grading/ — 雙層評分系統

grading/
  verifier.py           # 評分流程 main()
  checks.py             # deterministic check 執行
  facts.py              # ground truth 查詢與快取
  judge.py              # LLM judge（Claude）
  scoring.py            # 加權分數計算
  transcript_parser.py  # 解析 trajectory.json
  dashboard_state.py    # dashboard 狀態 check
  env_context.py        # 對 Grafana/Prometheus/Loki/Tempo 發請求

評分流程

trajectory.json  +  problem.yaml
         ↓
1. Deterministic checks
   grounding: 答案引用的 trace ID 是否來自工具結果？
   state:     Grafana 上 dashboard/datasource 是否符合規格？
         ↓
2. Resolve facts
   實際打 Prometheus/Loki/Tempo/Grafana API 拿 ground truth
         ↓
3. LLM rubric（Claude 當 judge）
   讀完整 transcript，逐條評 YES/NO
         ↓
4. 加權合算 → score (0.0–1.0)

官方部落格對評分設計的核心立場是：

"Our general grading philosophy is to always check against the ground truth of what the agent actually did, not just what it said."

對數字類的 criterion，benchmark 會拿相同的 PromQL 在相同資料上跑一遍；對 dashboard 類的操作，直接讀取已儲存的 panel JSON、驗證 variable binding、執行查詢並比對結果。Agent 的最終回答只是輔助，實際狀態才是評分依據。

第一層：Deterministic Checks

程式直接驗，快、精確，不需要 LLM。共有五種模式：

tool_trace_id 防的是一個常見的 LLM 行為：模型「知道」系統用了 Tempo，所以直接捏造一個看起來合理的 trace ID 格式。Grounding check 強制要求 trace ID 必須出現在這次 trial 的工具回傳結果裡。

第二層：LLM Rubric

用另一個 Claude 當 judge。Judge 的 prompt 結構：

<transcript>
  [System]: ...
  [User]: 題目
  [Assistant Tool Call]: query_prometheus(...)
  [Tool Result]: {"data": [...]}
  [Assistant]: 最終回答：payment-service error rate 峰值為 3.4%
</transcript>

Based on the transcript above, evaluate each criterion:

<criteria>
  <criterion id="0">The final response states the peak error rate accurately.
  Source of truth: The canonical query returned 0.034.</criterion>
</criteria>

Source of truth 是 facts.py 實際打 Prometheus API 拿到的數字，讓 judge 有明確的對照基準。Judge 回傳：

<evaluation id="0">
<answer>YES</answer>
<explanation>Response states 3.4% which matches the canonical value 0.034.</explanation>
</evaluation>

Context budget 設計：Judge prompt 有三段長度嘗試（180K / 120K / 80K chars），遇到「prompt is too long」錯誤時自動縮短重試，縮短策略是先壓 thinking 和 tool result，最後才截頭截尾。

分數計算

scoring.py 非常單純：

def calculate_score(subscores, weights) -> float:
    normalized = normalize_weights(weights)
    return sum(s * w for s, w in zip(subscores, normalized))

checks 和 rubric 的 weight 一起正規化，所以兩層的相對比重由各自的 weight 值決定，不是固定的 50/50。

重新評分（Regrade）

如果修改了 rubric 或評分邏輯，可以只重跑評分部分，不需要重跑 agent：

uv run python -m o11y_bench regrade --job-dir jobs/<job-name>

verifier 會讀取已存在的 trajectory.json，重跑 checks 和 LLM judge，覆寫 grading_details.json 和 reward.txt。需要真實 Grafana stack 的 check（如 dashboard_state）會自動起臨時的 sidecar stack。

組件五：o11y_bench/ — 排程與執行協調

這層是 Harbor 框架的使用者：負責把 tasks、agents、environments 組合起來，按照 job config 排程執行，處理 retry 邏輯，以及在執行完成後觸發 reporting。

關鍵行為：

Resume 機制：bench:job 會按 job directory 名稱 resume。如果 job 已存在且 config 相容，直接跑剩下的 trial，不重跑已完成的。這讓中途中斷的 job 可以繼續接著跑。

Retry 設定（來自昨天的 config）：

"retry": {
  "max_retries": 1,
  "exclude_exceptions": [
    "AgentTimeoutError", "RewardFileNotFoundError",
    "VerifierOutputParseError", "RewardFileEmptyError"
  ]
}

RewardFileNotFoundError 被排除在 retry 之外——這代表這類錯誤不會自動重試，需要人工介入調查。

簡單說：前四個組件是「零件」，這一層是把零件組裝起來、按順序執行、處理失敗的「 指揮中心」。當你執行 mise run bench:job 時，呼叫的就是這層。

組件六：reporting/ — 結果視覺化

reporting/
  run_report.py       # 單一 job 的 HTML 報告
  report.py           # 跨模型 suite leaderboard
  compare_report.py   # 兩個 job 並排比較
  report_data.py      # 核心資料載入與分類
  summary.py          # TrialRow / TaskSummary 聚合計算

三個關鍵指標

一題跑 3 次，pass@3 = 3 次裡至少 1 次過；pass^3 = 3 次都要過。on-call 想要的是後者——你不會希望「值班 3 次裡有 1 次能找到 bug」。

為什麼 leaderboard 以 pass^k 排序

官方的設計決策是：leaderboard 以 pass^k（一致性）為主要排名指標，而不是 pass@k（最好情況）。原因在於 observability 的使用情境——on-call 的時候，你需要的是「每次都對」，而不是「運氣好的時候對」。pass@k 和 pass^k 之間的差距本身就是一個重要訊號：差距大代表模型有能力但不穩定，不適合生產環境；差距小代表行為可預測。

幾種典型的解讀模式：

• pass@3 高、pass^3 低：有能力但不穩定，需要多試幾次

• pass@3 ≈ pass^3：穩定，行為可預測（不論對錯）

• mean_score 高但 pass_rate 低：很多題都拿到部分分，但沒有一題完全答對

輸出 Artifacts

jobs/<job-name>/
  run_report.html                   # 單一模型報告（自動生成）
  result.json                       # 所有 trial 分數摘要
  <task-name>__<trial-id>/
    agent/trajectory.json           # 完整對話 + 所有 tool calls
    agent/command-0/stdout.txt      # 每步工具呼叫摘要
    verifier/reward.txt             # 分數（0.0–1.0）
    verifier/grading_details.json   # 各 criterion 分數 + judge 解釋

grading_details.json 裡的 explanation: 欄位是診斷模型行為最直接的入口：

{
  "score": 0.45,
  "The final response identifies the root cause service.": 0.0,
  "explanation:The final response identifies...": "Agent said order-service but canonical query shows payment-service as the root cause"
}

實測結果：Gemini 3 Flash Preview（2026-05-02）

測試配置

錯誤分布

按類別分析

PromQL — 接近完美

幾乎全部滿分。唯一例外 promql-cache-refresh-lag-peak（0.55）。PromQL 語意嚴格、訓練資料充足，是目前模型最熟悉的能力域。

TraceQL — 整體良好

多數滿分，traceql-metrics-error-rate-by-service 其中一次 0.92（幾乎完美）。traceql-checkout-p99-by-service 得 0.0 是因為 NonZeroAgentExitCodeError（agent 崩潰），不是理解問題。

LogQL — 中等，變異最大

logql-multi-stage-pipeline 兩次都是 0.625 是個強訊號——說明模型對這個題型有固定的理解偏差，而不是偶發失誤。這個題目需要先 JSON 解析再用 unwrap 做 metric 計算，任何一步跑偏後續就全錯。

Dashboarding — 加法容易、改法困難

• add-cache-lag-panels、add-deployment-annotation：兩次都是 1.0

• create-cache-incident-review：0.90

• add-retry-backlog-panels：0.773

• update-add-service-variable：0.455（兩次一致）

dashboard-update-add-service-variable 固定 0.455 最值得關注——這道題要在所有現有 panels 加上 service variable binding，讓選不同服務時 panels 跟隨過濾。分數暗示模型能新增 variable，但無法把 variable 正確插入每個 panel 的查詢 template 裡。

Investigation — 清楚的能力分界線

結果分成明顯兩群：

拿到滿分的（1.0）：incident-triage、service-degradation-rca、cache-incident-blast-radius、retry-backlog-incident

固定卡在 0.45（兩次一致）：

• payments-path-root-cause

• slow-path-hotspot-correlation

• deployment-blast-radius-check

0.45 不是完全失敗——模型能識別部分症狀，但無法完成完整的因果推理鏈。這三道題的共同點：需要把 metrics 數字 + logs 時間序列 + traces span 結構對應到同一個根因，並給出有量化依據的結論。滿分的那些題目只需要跨 2 個訊號，這 3 道需要 3 個訊號全部對準。

四個核心觀察

1. PromQL > TraceQL > LogQL 的能力梯度

符合直覺：PromQL 語法嚴格語意清楚；TraceQL 以結構化查詢為主；LogQL 需要理解 pipeline 概念且輸出是文字，容錯空間最小。

2. 新增比修改容易

在 Dashboarding 類別，新增 panels 幾乎全滿分，但修改 variable binding 固定失敗。這反映對 Grafana dashboard JSON schema 的理解深度不同：建新 panel 只需知道基本結構，修改 variable binding 需要理解整個 dashboard 的資料流。

3. 一致的低分比偶發的低分更有診斷價值

payments-path-root-cause 兩次 0.45、dashboard-update-add-service-variable 兩次 0.455、logql-multi-stage-pipeline 兩次 0.625——這些固定分數說明的是系統性理解缺口，是模型真正的能力邊界，而不是運氣問題。

4. 11 個 RewardFileNotFoundError 值得追查

依照 retry 設定，這類錯誤不會自動重試，需要逐一查看各 trial 的 verifier/grading_details.json，釐清是 agent 輸出格式問題還是 verifier 環境問題。

官方 Leaderboard 全局觀（GrafanaCON 2026）

以上是 Gemini 3 Flash Preview 單一模型的分析。官方在 GrafanaCON 2026 公布了更完整的跨模型比較，以下是重點摘要。

整體排名趨勢

leaderboard 以 pass^k（一致性）排序，而不是 pass@k（最好情況）。整體趨勢：

• Anthropic Claude Opus 4.7（reasoning off） 拿到最高 pass^k，一致性最佳

• Claude Opus 4.7（reasoning on） pass@k 更高但 pass^k 略低——開啟 reasoning 讓模型偶爾能解更難的題，但也增加了不穩定性

• 開源模型：Qwen 3.6 Plus 超越了部分較小的 Sonnet 和 GPT 變體，顯示開源模型在 observability 任務上已具競爭力

各類別的飽和程度

Dashboard 任務之所以最難，是因為它同時考驗四件事：state 正確、query 語法正確、variable wiring 正確、saved behavior 符合預期——任何一層出錯都會被 deterministic check 抓到。

一個值得注意的任務設計細節

官方提到 promql-retry-backlog-triage 這個任務揭示了一個有趣的 tradeoff：高 reasoning 或高 token 消耗的 agent，反而容易在這道題上過度蒐集資訊、繞遠路。這暗示 observability 任務的評分不只是「對不對」，也是「有沒有效率地對」——而 benchmark 的 cost 和 tool call 數量指標正好捕捉這個面向。

如何自己跑

環境需求

# 安裝工具鏈
git clone <repo>
cd o11y-bench
mise install
uv sync

# 設定 API keys
export ANTHROPIC_API_KEY=...   # grading 用（必要）
export GOOGLE_API_KEY=...      # 如果要跑 Gemini
export OPENAI_API_KEY=...      # 如果要跑 GPT

快速驗證（單一題目）

mise run bench:job -- --model google/gemini-3-flash-preview \
  --task-name query-cpu-metrics --n-concurrent 1

跑完整 63 題

mise run bench:job -- --model google/gemini-3-flash-preview

跑所有模型全部題目（完整 suite）

mise run bench:suite

沒有 Anthropic API key 也能跑

export SKIP_LLM_GRADING=1
export ANTHROPIC_API_KEY=dummy   # Harbor 前置檢查需要這個變數存在，填假的即可
mise run bench:job -- --model google/gemini-3-flash-preview --task-name query-cpu-metrics

注意：investigation 類的 task 全靠 LLM rubric，這種模式下分數會是 0，但 agent 行為本身還是會跑完。

重新評分（不重跑 agent）

uv run python -m o11y_bench regrade --job-dir jobs/<job-name>

其他常用指令

mise run test             # 跑 pytest 測試套件（驗 benchmark 邏輯，不需要 Docker）
mise run lint             # Ruff lint
mise run typecheck        # mypy
mise run setup:sync       # 從 tasks-spec/ 重新生成 tasks/
mise run setup:preflight  # 預先 build Docker image、清理舊容器

# 重建單一 job report
uv run python -m reporting.run_report --job-dir jobs/<job-name>

# 兩個 job 並排比較
uv run python -m reporting.compare_report \
  --job-dir jobs/<suite-id>/<job-a> \
  --job-dir jobs/<suite-id>/<job-b>

解讀結果

每個 trial 目錄下有三個關鍵檔案：

jobs/<job-name>/<task-name>__<trial-id>/
  agent/trajectory.json          # 完整對話 + 所有 tool calls
  verifier/grading_details.json  # 各 criterion 分數 + judge 解釋
  verifier/reward.txt            # 最終分數（0.0–1.0）

grading_details.json 裡的 explanation: 欄位直接說明 judge 為什麼扣分，是診斷模型行為最有效的入口。

拿來測試你們自己的 Agent

o11y-bench 不只是用來跑公開 leaderboard 的工具，更實際的用途是讓你在開發 agent 的過程中，對著真實的 Grafana stack 持續驗證能力。接入的方式取決於你的 agent 形態，有三條路。

路線一：只換 model，架構不動

最快的起點——你的 agent 本質上是「LLM + tool use loop」，只是想換成自己的模型或推論服務：

# 換成自己的模型
mise run bench:job -- --model your-provider/your-model

# 接 OpenAI-compatible 自架服務
export OPENAI_API_BASE=https://your-inference-server
mise run bench:job -- --model openai/your-model-name

這條路適合：評估特定 model 在 observability 任務上的能力、比較不同 reasoning effort 設定的效益。

路線二：接入自己的 Agent Framework

如果你的 agent 用了自己的 framework（LangChain、自製 loop、LlamaIndex 等），需要實作一個薄薄的 Harbor agent class。Repo 裡的 agents/langchain_o11y_agent.py 就是範本，照著結構改：

# agents/my_team_agent.py
from harbor.agents.base import BaseAgent

class MyTeamAgent(BaseAgent):
    async def setup(self):
        pass  # 環境準備，可留空

    async def run(self, task):
        statement = task.statement   # 題目文字
        current_time = ...           # 從環境變數 O11Y_SCENARIO_TIME_ISO 讀

        # 用你的 framework 跑 agent loop
        # MCP server 在 http://localhost:8080/sse（mcp-grafana）
        result = await your_framework.run(statement, mcp_url="http://localhost:8080/sse")

        # 把結果寫到 /logs/agent/trajectory.json
        self.write_trajectory(result)

執行：

mise run bench:job -- --model your/model \
  --agent-import-path agents.my_team_agent:MyTeamAgent

Trajectory 格式要求：grading 系統只需要能讀到 steps 和最終的 assistant message，最簡化的結構：

{
  "schema_version": "ATIF-v1.6",
  "steps": [
    { "step_id": 1, "source": "user",  "message": "題目內容" },
    { "step_id": 2, "source": "agent", "tool_calls": [
        { "id": "tc1", "name": "query_prometheus", "arguments": {...} }
    ]},
    { "step_id": 3, "source": "tool",  "tool_call_id": "tc1", "content": "..." },
    { "step_id": 4, "source": "agent", "message": "最終回答" }
  ],
  "final_metrics": { "total_cost_usd": 0.0, "total_tool_calls": 3 }
}

grading 的 LLM rubric 讀的是最後一個 source: "agent" 且有 message 的 step；deterministic check 讀的是所有 source: "tool" 的 content。只要這兩段正確，分數就能算出來。

路線三：Agent 不用 MCP，有自己的 Grafana 操作方式

如果你的 agent 已經有自己一套跟 Grafana 互動的方法（REST API wrapper、自製 SDK、CLI tool），可以參考 agents/gcx_opencode_agent.py——它把 MCP tools 全部移除，改讓 agent 透過 gcx CLI 操作 Grafana。

你的 agent class 在 run() 裡可以完全自主決定怎麼操作 Grafana，只要最終產出格式正確的 trajectory.json 就行。sidecar 容器裡的 Grafana 端口是固定的（:3000），Prometheus 在 :9090，Loki 在 :3100，Tempo 在 :3200。

建議的起步順序

無論哪條路，建議這樣進入：

1. 先跑預設 agent 確認環境正常

mise run bench:job -- --model your/model --task-name query-cpu-metrics --n-concurrent 1

這一步驗證 Docker 環境、API key、model provider 都通了。

2. 挑 2–3 道你最在意的 task 重點觀察

不需要跑全部 63 題。根據你的 agent 設計，挑最相關的類別：

• 如果你的 agent 主打查詢能力：promql-error-rate、logql-multi-stage-pipeline

• 如果你的 agent 主打根因分析：incident-triage、payments-path-root-cause

• 如果你的 agent 主打 Grafana 操作：dashboard-create-service-overview、dashboard-update-add-service-variable

3. 讀 grading_details.json，理解評分標準

cat jobs/<job-name>/<task-name>__<trial-id>/verifier/grading_details.json

explanation: 欄位會直接告訴你 judge 為什麼扣分。在開始改 agent 之前，先確認評分標準符合你的預期——如果有 criterion 的定義不合理，直接去 tasks-spec/ 修改 rubric，跑 regrade 就能看到新分數，不需要重跑 agent。

4. 接入自己的 agent，跑完整 63 題

確認了環境和評分標準之後，再把自己的 agent 接進來跑完整 benchmark。這時候的分數才有意義——你能知道自己的 agent 在哪個類別有系統性的弱點，以及跟公開 leaderboard 上的其他模型相比在什麼位置。

小結

o11y-bench 的設計哲學是不測試模型「知道」什麼，而是測試模型「能做到」什麼：

• tasks-spec/ 用自然語言出題，不洩露語法提示

• docker/ 跑起真實 stack，資料釘死確保可重現

• agents/ 用輕量 ReAct loop，讓工具能力差異直接顯現

• grading/ 用 deterministic check 防幻覺，用 LLM rubric 處理語意判斷

從 Gemini 3 Flash Preview 的結果來看，0.710 的平均分顯示結構化查詢已相當成熟，但跨訊號根因分析和精確修改複雜資源結構這兩個能力邊界仍然清晰。整體 leaderboard 的趨勢也印證了這點：PromQL 和 Grafana API 類別接近飽和，Dashboard 和 Investigation 仍是區分模型能力的主戰場。

o11y-bench 刻意設計成 可檢驗（inspectable）、可重現（reproducible）、開放挑戰（open to challenge）。資料、題目、評分邏輯全部開源，任何人都可以在本地重現結果、加入新的 agent harness、或對評分標準提出質疑。這和那種「只公布分數、不公布方法」的封閉 benchmark 不同——結果的意義來自於它背後的流程是透明的。

leaderboard 持續更新在 o11ybench.ai，提交新結果見 Hugging Face 投稿 repo，官方介紹文見 Grafana Blog。

接續上篇【OTel 陣法監控篇】，此卷深入解析奇術（Skills）機制——臥龍神算如何知曉有哪些兵器可用、糧草如何節省、奇術如何設計才不浪費、以及如何驗證奇術行為如你所謀。

稟告主公：為何需要奇術（Skills）？

主公可曾遇過此種困境：每次要臥龍神算（Claude Code）助你辦一件事，都得貼上一大段說明？

「請用我軍的插旗格式，格式如下：feat(scope): 描述，且...（以下三百字軍令）」

每次開新一場戰役便要重複貼上一遍。更慘的是，若你有三十份這樣的「工作說明書」，全部塞進軍令總諭，不但糧草爆炸，臥龍神算的注意力也會被稀釋——什麼都想做，反而什麼都做不精。

奇術就是解決此問題的機制。

其核心思想甚為簡單：按需調兵，用多少拿多少。

第一計：奇術如何運作？三層漸進揭露之術

此乃全篇兵書最重要之處。理解了此機制，後面所有的設計決策都會豁然開朗。

此節由諸葛亮主講。孔明搖動羽扇，微笑道：

孔明言： 主公請聽臣細細道來。

第一層：目錄情報（Metadata）

神算啟動時 → 只載入每個奇術的名稱與描述 → 佔用極少糧草

臥龍神算啟動時，只把所有奇術的名稱和描述載入軍令總諭。此乃圖書館的目錄卡，告訴神算「你的兵器庫裡有什麼」，但不把每本兵書的內容都塞進去。

技術細節：描述總共的糧草預算 = 戰場視野的 2%，最多 16,000 字元。若奇術太多超過預算，執行 /context 可以看到警告。

第二層：奇術兵書（Instructions）

將領說「幫我審查這份奏摺」
  → 神算發現這符合 "review-pr" 這個奇術
  → 透過後台指令讀取 SKILL.md 兵書
  → 詳細的部署步驟才進入神算的兵略

奇術被觸發時，神算才去讀 SKILL.md 兵書。在此之前，SKILL.md 的內容完全不佔用戰場視野。

第三層：運行時資源（Runtime Resources）

執行具體步驟時
  → 兵書輔冊（reference/*.md）：需要時才讀
  → 奇兵腳本（scripts/*.py）：直接執行，不讀進戰場視野

此處有個關鍵之點：奇兵腳本只有輸出結果會耗用糧草，腳本本身的程式碼不會。五百行的 Python 腳本，被執行後回傳一行結果，那也只花那一行結果的糧草。

┌────────────────────────────────────────────────────┐
│  奇術：漸進揭露三層陣法                              │
│                                                     │
│  第一層：目錄情報（神算啟動）                        │
│  ├── name: "review-pr"                              │
│  └── description: "..."    ← 只有這些進戰場視野      │
│                                                     │
│  第二層：奇術兵書（奇術被觸發）                      │
│  └── SKILL.md 全文         ← 此時才載入              │
│                                                     │
│  第三層：運行時資源（執行步驟中）                    │
│  ├── references/checklist.md ← 需要時才讀            │
│  └── scripts/validate.py    ← 只有輸出進戰場視野     │
└────────────────────────────────────────────────────┘

第二計：糧草如何節省？奇術與軍需官之本質差異

理解了三層陣法，我們來看奇術（Skills）和軍需官（MCP）的根本差異。

司馬懿接回主講：

仲達撫著長袖，冷靜分析道：

軍需官（MCP）的弊端

軍需官要讓神算知道「有哪些兵器可用」，必須在對陣開始時把所有兵器的完整規格一次性注入：名稱、詳細描述、參數規格、使用範例。

以 GitHub 軍需官為例，它有三十餘件兵器。假設每件兵器規格消耗五百糧草：

30 件兵器 × 500 糧草 = 15,000 糧草（光是「告知神算有哪些兵器」就花掉了）

若你連接四十個軍需官、三百件兵器，啟動成本可以高達數萬糧草。你還沒說任何事，神算就已經燒掉大量糧草了。

更麻煩的是，兵器太多會讓神算的注意力下降。根據 MCP Atlas 基準測試，即使最強的 Claude Opus 4.6 兵種，在四十個軍需官、三百件兵器的環境下，兵器調用準確率也只有 62%。

奇術的解法

💡 孔明言：兩者不互相取代，而是互補。軍需官專注「連接各方諸侯」，奇術專注「封裝行軍流程」。未來架構會是：

AI 謀士神算
  ├── 內建兵器（bash, read, write, edit）← 核心能力
  ├── 奇術層 ← 封裝 80% 的行軍流程
  └── 軍需官層 ← 少數場景需要遠端連線

第三計：你的第一個奇術——臨陣速建之法

此節由諸葛亮主講。孔明搖動羽扇，微笑道：

奇術駐紮何處？

注意：舊的 .claude/commands/ 目錄依然有效，只是奇術目錄多了資料夾、輔助兵書等功能。

建立第一個奇術

mkdir -p ~/.claude/skills/commit-helper

建立 ~/.claude/skills/commit-helper/SKILL.md 兵書：

---
name: commit-helper
description: 根據 git diff 生成符合 Conventional Commits 規範的插旗訊息。當將領要插旗、寫插旗記錄、或詢問暫存變更時使用。
disable-model-invocation: true
---

根據 `git diff --staged` 的輸出，生成一條符合軍令規範格式的插旗訊息：

## 格式規則
- `feat(scope): 描述` — 新功能
- `fix(scope): 描述` — 修復亂象
- `docs(scope): 描述` — 兵書變更
- `refactor(scope): 描述` — 重整部署

## 行軍步驟
1. 執行 `git diff --staged` 查看變更
2. 分析變更類型和影響範圍
3. 生成一條簡潔的主訊息（50 字元以內）
4. 若有多項變更，加上條列說明

## 注意
- 不要自動執行 `git commit`，只輸出建議的訊息
- scope 用小寫，和陣地模組名稱一致

兩種召喚方式

方式一：直接呼叫

/commit-helper

方式二：自然語言觸發（描述符合時自動載入）

幫我整理一下這次的插旗訊息

第四計：兵書題記完整欄位解析

此為 SKILL.md 兵書開頭 --- 之間可以設定的所有欄位：

---
name: my-skill              # 奇術識別名稱（小寫英數和連字號，最多 64 字）
description: "..."          # 告訴神算何時使用（最多 1024 字，用第三人稱寫）
argument-hint: <奏摺號碼>   # 在 / 選單中顯示的參數提示
disable-model-invocation: true  # true = 只有將領能手動觸發，神算不會自動呼叫
user-invocable: false       # false = 從 / 選單隱藏，但神算可自動觸發
allowed-tools: Read, Grep   # 執行此奇術時不需逐一確認的兵器清單（虎符授權）
model: claude-opus-4-6      # 指定執行這個奇術使用的兵種
context: fork               # fork = 在隔離的偏師中執行
agent: Explore              # 指定偏師類型（搭配 context: fork 使用）
hooks:                      # 奇術生命週期 Hooks
  - event: skill-start
    command: echo "奇術啟動"
---

何時用 disable-model-invocation: true？

此欄位防止神算自動觸發奇術，適合有副作用的操作：

# 出兵、傳送軍報、資料庫遷移 — 你想控制時機的操作
---
name: deploy-production
description: 出兵至正式戰場
disable-model-invocation: true  # 絕對不讓神算自己決定要出兵
---

何時用 user-invocable: false？

把奇術設為背景知識，讓神算在相關情境自動參考，但不出現在 / 選單：

---
name: legacy-system-context
description: 包含舊陣地的架構說明和注意事項。處理和舊陣地相關的程式碼時參考。
user-invocable: false  # 將領不需要直接呼叫，神算遇到相關情境會自動載入
---

三種組合的行為對照

奇兵一策：拆分部署之法——引用輔助兵書

此為節省糧草最重要的實作技巧。若你寫過軟體，你會發現奇術的設計原則和模組化程式設計幾乎一模一樣——只是操作對象從「程式碼」換成了「給神算的指令」。

此節由諸葛亮主講。孔明搖動羽扇，微笑道：

以軍事部署思維理解奇術結構

奇術目錄 ≈ 一個軍團（Module）

行軍打仗，我們不會把所有兵力塞進主帥一人；設計奇術也一樣，不要把所有知識塞進一個 SKILL.md 兵書。

# 你熟悉的軍團結構：
src/bigquery/
├── index.ts          # 正面旗幟（只暴露必要介面）
├── finance.ts        # 財務謀略（內部實作）
├── sales.ts          # 銷售謀略（內部實作）
└── utils/
    └── validate.ts   # 輔助工具（不直接對外）

# 奇術的對應結構：
.claude/skills/bigquery-analysis/
├── SKILL.md          # 正面旗幟（神算的進入點）
├── reference/
│   ├── finance.md    # 財務謀略（需要時才載入）
│   └── sales.md      # 銷售謀略（需要時才載入）
└── scripts/
    └── validate.py   # 奇兵腳本（直接執行，不讀入戰場視野）

SKILL.md ≈ 正面旗幟（Facade 佯攻之術）

SKILL.md 只宣告「這個奇術能做什麼、入口在哪」，把實作細節隱藏在兵書輔冊和奇兵腳本背後。此與佯攻之術完全相同：對外提供簡單的正面，背後可以有複雜的子陣。

# 程式碼的 Facade：
class DataService {
  getReport(domain: string) { /* 隱藏內部複雜性 */ }
}

# 奇術的 Facade（SKILL.md 兵書）：
## 可用資料集
- 財務：[reference/finance.md](reference/finance.md)
- 銷售：[reference/sales.md](reference/sales.md)

漸進揭露 ≈ 按需調兵（Lazy Loading）

前線將領對按需調兵一定不陌生：不要在大戰前把所有兵力一次調到前線，用到哪個方向才調哪路兵馬。奇術的三層陣法做的是同一件事：

# 按需調兵（前端）：
import('./finance')  // 只有進入 /finance 頁面才召來這路兵馬

# 漸進揭露（奇術）：
[reference/finance.md]  // 只有談到財務問題才讀這份兵書

兵書輔冊（reference/ 資料夾） ≈ 職責分守原則（ISP）

職責分守原則說：不要強迫將士依賴他們用不到的命令。同理，不要強迫神算在每次戰役都載入所有知識——把不同領域的知識拆分到各自的文件，神算只拿它需要的部分。

# 職責分守違反（單一大陣）：
interface BigQueryService {
  financeQuery();   // 每次都要帶著這個
  salesQuery();     // 和這個
  productQuery();   // 和這個
}

# 職責分守遵守（分開的小陣）：
interface FinanceService { financeQuery(); }
interface SalesService { salesQuery(); }
# ↑ 對應到：把知識拆進 finance.md / sales.md

奇兵腳本（scripts/ 資料夾） ≈ 封裝內功（Encapsulation）

腳本的程式碼邏輯對神算是不透明的——它只知道「執行這個腳本，取得結果」，不需要理解腳本內部怎麼運作。此與封裝兵器內部機密、只暴露使用方法的概念完全一致。

# validate_query.py 的 500 行實作細節，神算完全不知道
# 神算只知道：
# - 輸入：SQL 查詢字串
# - 輸出：OK 或錯誤訊息
# 此乃封裝內功

實作：SKILL.md 作為正面旗幟

---
name: bigquery-analysis
description: 分析 BigQuery 資料，生成業務報告。處理財務、銷售、產品相關數據查詢時使用。
allowed-tools: Bash(bq *)
---

# BigQuery 分析謀士

## 可用資料集（依需求載入對應兵書）

| 領域     | 說明              | 兵書位址                                          |
|--------|-----------------|------------------------------------------------|
| **財務** | 營收、ARR、帳單  | [reference/finance.md](reference/finance.md)   |
| **銷售** | Pipeline、機會   | [reference/sales.md](reference/sales.md)       |
| **產品** | API 使用量、功能採用 | [reference/product.md](reference/product.md) |

## 行軍部署，分三步走：

1. 確認將領要查詢哪個領域 → 讀取**對應的**兵書輔冊（不要全部讀）
2. 撰寫查詢 → 執行驗證腳本 → 執行查詢
3. 格式化結果

## 注意事項
- 所有查詢必須排除測試帳號（`WHERE account_type != 'test'`）
- 日期一律使用 UTC

效果： 將領問「銷售 Pipeline 本週的數字」時：

1. 神算讀 SKILL.md 兵書（約 100 行）

2. 正面旗幟引導它判斷：這是銷售問題 → 讀 reference/sales.md

3. finance.md 和 product.md 完全不進戰場視野

三份兵書輔冊若各 200 行，此次戰役省了 400 行糧草。

單一職責原則（SRP）：一個奇術辦一件事

SRP 說：一個軍團應該只有一個改變的理由。奇術設計也一樣——不要建一個「萬能奇術」。

❌ 違反 SRP：
.claude/skills/everything/
├── SKILL.md  # 裡面同時處理：奏摺審查、兵書生成、出兵、資料分析...

✅ 遵守 SRP：
.claude/skills/review-pr/     # 只做奏摺審查
.claude/skills/gen-docs/      # 只做兵書生成
.claude/skills/deploy/        # 只做出兵
.claude/skills/data-analysis/ # 只做資料分析

細粒度的奇術可以被**組合（Compose）**使用——神算在一次戰役中可以依序觸發多個奇術，此和兵法組合的概念一樣。

黃金法則：旗幟最好只有一層深度

此對應兵法中的「避免過深的糧道依賴鏈」。若 A 依賴 B，B 又依賴 C，任何一層出問題都會導致整條糧道斷裂。

❌ 過深的糧道依賴鏈：
SKILL.md → advanced.md → details.md → 真正的情報
# 神算讀到 advanced.md 發現還要再讀 details.md
# 可能只預覽就決定跳過，導致情報不完整

✅ 扁平的依賴（最多一層）：
SKILL.md → finance.md  （直接是完整情報）
SKILL.md → sales.md
SKILL.md → product.md

超過 100 行的兵書輔冊要加目錄（相當於 JSDoc / 兵器型別定義）

# 財務資料 Schema 兵書

## 目錄
- [revenue_monthly 陣型](#revenue-monthly)
- [billing_events 陣型](#billing-events)
- [arr_snapshots 陣型](#arr-snapshots)

## revenue_monthly
...

即使神算只讀到前幾行，它也能從目錄知道整份兵書的全貌，就像 TypeScript 的 .d.ts 型別定義——不需要看實作就能知道有什麼可以用。

奇兵二策：動態注陣與分兵遣將

動態上下文注入（! 語法）

在奇術被觸發時，可以預先執行 Shell 指令，把輸出注入到提示詞中：

---
name: pr-review
description: 對奏摺進行完整的程式碼審查
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## 奏摺情報（系統自動抓取）

- 奏摺差異：!`gh pr diff`
- 奏摺描述：!`gh pr view --json title,body`
- 變更檔案：!`gh pr diff --name-only`
- CI 戰況：!`gh pr checks`

## 審查任務

請針對以上奏摺進行完整審查，重點關注：
1. 邏輯正確性
2. 是否有遺漏的邊界情況
3. 演武場覆蓋是否足夠
4. 是否符合陣地程式碼規範

重要：command 是在奇術載入時就執行，神算只看到執行結果，不是神算在「做」這個動作。

「奇術之妙，在於因地制宜。以 ! 之法，可臨陣攝取八方情報——如 CPU 之氣、記憶體之靈 ，將動態之氣注入軍令，使神算所得情報皆為即時戰況，此乃『借力使力』之最輕量陣法 。」

在偏師中執行（context: fork）

加上 context: fork 讓奇術在獨立沙箱執行，不共享當前戰役歷史：

---
name: deep-research
description: 對程式碼庫進行深入研究分析
context: fork
agent: Explore          # 使用探查偏師（唯讀兵器集，防止意外修改）
---

深入研究 $ARGUMENTS 的實作細節：

1. 用搜索斥候找到所有相關檔案
2. 閱讀核心實作
3. 整理依賴關係
4. 回報：主要邏輯、潛在亂象、建議改進方向

可選的偏師類型：

「深入險境，不宜動搖大軍。以 fork 之法遣一偏師，在隔離之沙場進行深入探究（Deep Research） 。其探查結果回報即可，偏師即使在險境中有所變動，亦不傷及中軍大帳之戰役歷史 。」

第五計：選兵指揮之術——讓不同奇術用不同兵種

---
name: quick-lint
description: 快速 Lint 程式碼，找常見亂象
model: claude-haiku-4-5-20251001   # 輕量任務用 Haiku 兵種，速度快糧草少
---

快速掃描 $ARGUMENTS 檔案，找出：
- 明顯的語法錯誤
- 未使用的 import
- 明顯的命名問題

---
name: architecture-review
description: 對陣地架構做深度評估
model: claude-opus-4-6             # 需要深度謀略的任務用 Opus 兵種
context: fork
---

對以下架構設計進行深度評估：$ARGUMENTS

評估維度：可擴展性、安全性、維護成本、效能瓶頸

兵種 ID 速查：

「夫兵者，各有其材。Haiku 如輕騎，迅捷而省糧，利在快攻 ；Sonnet 如中軍步兵，穩健多能，為陣中砥柱 ；Opus 則如大將軍，深謀遠慮，專應架構之變 。主公應視戰情緩急，調遣合適兵種，方為度支之道。」

第六計：臥龍神算內建哪些兵器？它如何知曉武器存在？

兵器發現機制

神算知道有哪些兵器，來源有三：

1. 臥龍神算內建兵器：隨系統自動注入，永遠可用

2. 奇術宣告的虎符授權（allowed-tools）：奇術被觸發時，這些兵器可不經確認直接使用

3. 軍需官（MCP Server）兵器：連接的軍需官在啟動時注入完整定義

臥龍神算內建兵器完整清單

核心操作兵器：
├── Bash          衝鋒奇兵（執行 Shell 指令）
├── Read          探查細作（讀取檔案）
├── Write         修築工事之兵（建立/覆寫檔案）
├── Edit          精密工事之兵（精確替換檔案內容）
├── Glob          搜索斥候（用 Pattern 搜尋檔案）
└── Grep          情報細作（在檔案內容中搜尋）

遠探工具：
├── WebFetch      信使斥候（抓取網頁內容）
└── WebSearch     天下情報（網路搜尋）

開發工具：
├── Task          調兵遣將（委派任務給偏師）
├── LSP           兵器語言服務（GoToDefinition、FindReferences 等）
└── NotebookEdit  策劃冊編修（編輯 Jupyter Notebook）

任務管理：
├── TodoWrite     軍令清單建立
└── TodoRead      軍令清單查看

互動工具：
└── AskUserQuestion   向將領提問，等待回覆後再繼續

AskUserQuestion 特別說明

此兵器值得單獨拿出來講，因為在奇術設計裡特別常見卻容易被忽略。

其作用：讓神算暫停執行，彈出一個選項面板或輸入框向將領確認，再繼續。

典型使用場景：

---
name: sanguo-rewrite
description: 以三國軍師風格改寫技術文章
allowed-tools: Read, Write, AskUserQuestion   # ← 注意這裡的虎符授權
argument-hint: <文件路徑>
---

1. 讀取 $ARGUMENTS 指定的文件
2. 若 $ARGUMENTS 為空，使用 AskUserQuestion 詢問文件路徑
3. 改寫並輸出

當將領直接打 /sanguo-rewrite（沒帶路徑），奇術會透過 AskUserQuestion 彈出詢問，而不是憑空猜或直接報錯。

為何要在 allowed-tools 裡宣告它？

預設情況下，神算使用兵器需要逐一確認。把 AskUserQuestion 加入虎符授權，代表奇術執行期間可以不經額外確認就向你提問——讓互動流程更順暢。

在奇術裡的實用寫法：

## 出征前確認

若以下任一條件不明確，使用 AskUserQuestion 詢問後再繼續：
- 目標文件路徑未指定
- 輸出格式有多個選項（Markdown / HTML / 純文字）
- 操作會覆寫現有兵書

此讓奇術具備「智慧詢問」的能力：需要確認的才問，不需要的直接執行。

虎符授權（allowed-tools）語法細節

---
allowed-tools: Read, Grep, Glob          # 允許特定兵器
---

---
allowed-tools: Bash(git *)               # 允許衝鋒奇兵，但只能執行 git 開頭的指令
---

---
allowed-tools: Bash(npm run *), Read, Write   # 組合：允許 npm 指令 + 讀寫
---

此機制讓你可以在奇術裡開放特定兵器的自動執行權限，減少操作過程中的確認彈窗，同時又不會全面放開兵器庫。

「軍令有疑，必先諮詢主公。奇術運作時，若遇關隘不明，軍師將手持『智慧詢問』之兵，退回中軍請示 。若主公預賜『虎符授權』（Allowed Tools），則部分兵器可先斬後奏，不驚擾主公，使行軍流程如水流般順暢 。」

第七計：自鑄兵器之法——自行開發工具給神算使用

方式一：軍需官（MCP Server）——最完整的自訂兵器

透過 MCP 協議開發自定義兵器，神算可以調用你的 API、資料庫、內部服務：

# 一個簡單的軍需官範例（Python）
from anthropic import MCP

@MCP.tool("get_deploy_status")
def get_deploy_status(env: str) -> dict:
    """查詢出兵狀態"""
    # 呼叫你的內部 API
    return your_internal_api.get_status(env)

在 ~/.claude/settings.json 主帥令冊中設定：

{
  "mcpServers": {
    "company-tools": {
      "command": "python",
      "args": ["/path/to/your/mcp_server.py"]
    }
  }
}

方式二：奇術內建腳本（輕量版，不需要軍需官框架）

把腳本打包進奇術目錄，透過衝鋒奇兵執行：

.claude/skills/deploy-checker/
├── SKILL.md
└── scripts/
    └── check_deploy.sh   # 你的自訂兵器邏輯

---
name: deploy-checker
description: 檢查所有陣地的出兵狀態
allowed-tools: Bash(bash ~/.claude/skills/deploy-checker/scripts/*)
---

執行出兵狀態檢查：

```bash
bash ~/.claude/skills/deploy-checker/scripts/check_deploy.sh $ARGUMENTS

解讀輸出並提供建議。

此法門檻極低：任何 Shell/Python/Node.js 腳本都可以變成神算的「兵器」。

方式三：! 動態注陣（最輕量）

若兵器只是抓資料，用動態注陣就夠了：

---
name: check-metrics
description: 查看軍情數報
allowed-tools: Bash(curl *)
---

## 當前戰況
- CPU 使用率：!"curl -s http://localhost:9090/api/v1/query?query=node_cpu_usage"
- 記憶體：!"curl -s http://localhost:9090/api/v1/query?query=node_memory_usage"

根據以上軍情分析戰況，若有亂象提供建議。

陣前排難：驗證你的奇術

司馬懿接回主講：

仲達補充： 孔明設計奇術，仲達負責驗證——此乃軍中分工之道。

先釐清：「評估兵書」是規格書，不是可執行的演武框架

官方文件提到的評估 JSON 結構長這樣：

{
  "skills": ["commit-helper"],
  "query": "幫我整理這次的插旗訊息",
  "expected_behavior": [
    "執行 git diff --staged 取得變更內容",
    "判斷變更類型（feat/fix/docs/refactor）",
    "生成符合軍令規範格式的訊息",
    "不自動執行 git commit"
  ]
}

但官方同時說：「目前沒有內建的執行方式，請自行建立評估系統。」

此 JSON 的用途是寫清楚你對奇術的期望，讓你在手動或程式化演武時有明確的對照基準。它不是一個 npm test 那樣可以直接跑的東西。

實際上有三個層次的演武方式，從輕到重：

亂象一：手動演武（最快驗證）

最直接的方式：開臥龍神算，真的跑奇術，然後逐條對照 expected_behavior 清單。

行軍步驟：

# 1. 確認奇術已放在正確位置
ls ~/.claude/skills/commit-helper/

# 2. 打開臥龍神算
claude

# 3. 先確認奇術被認得
What skills are available?

# 4. 觸發奇術，觀察行為
/commit-helper
# 或自然語言：
# 幫我整理這次的插旗訊息

觀察清單（對照你寫的 expected_behavior）：

□ 神算有沒有執行 git diff --staged？
□ 有沒有正確判斷 feat / fix / docs？
□ 格式有沒有符合軍令規範格式？
□ 有沒有自己去執行 git commit（這個不應該發生）？
□ 有沒有讀了不應該讀的兵書輔冊？
□ 有沒有問不必要的問題？

此方式的限制是「你自己跑一次」，容易遺漏邊界情況。建議為同一個奇術準備 三個以上不同的詢問（正常情況、邊界情況、模糊情況）。

亂象二：claude -p 程式化演武（半自動）

臥龍神算支援 -p 旗號（print mode）非互動式執行，可以寫成腳本批次演武：

# 基本用法：把詢問傳進去，直接輸出結果
claude -p "幫我整理這次的插旗訊息"

# 搭配 --output-format json 可以拿到結構化結果
claude -p "幫我整理這次的插旗訊息" --output-format json

把這個包進 Shell 腳本，就能批次跑多個演武情境：

#!/bin/bash
# test_commit_skill.sh

PASS=0
FAIL=0

run_test() {
  local description="$1"
  local query="$2"
  local should_contain="$3"
  local should_not_contain="$4"

  echo "🧪 演武：$description"
  result=\((claude -p "\)query" 2>&1)

  if echo "\(result" | grep -q "\)should_contain"; then
    if [ -n "\(should_not_contain" ] && echo "\)result" | grep -q "$should_not_contain"; then
      echo "  ❌ 失敗：結果含有不應出現的「$should_not_contain」"
      ((FAIL++))
    else
      echo "  ✅ 通過"
      ((PASS++))
    fi
  else
    echo "  ❌ 失敗：結果未包含「$should_contain」"
    echo "  輸出預覽：\((echo "\)result" | head -3)"
    ((FAIL++))
  fi
}

# 演武案例
run_test \
  "新功能的插旗" \
  "剛加了一個登入功能，幫我整理插旗訊息" \
  "feat" \
  "git commit"   # 不應該自動執行插旗

run_test \
  "亂象修復的插旗" \
  "修了一個日期顯示錯誤的亂象，幫我整理插旗訊息" \
  "fix" \
  "git commit"

run_test \
  "兵書變更的插旗" \
  "更新了 README 兵書，幫我整理插旗訊息" \
  "docs" \
  ""

echo ""
echo "結果：\(PASS 通過 / \)FAIL 失敗"

chmod +x test_commit_skill.sh
./test_commit_skill.sh

限制：grep 只能做字串比對，無法判斷「格式正不正確」這類語意問題。對於需要語意判斷的期望行為，還是得靠人眼或下面的方法三。

亂象三：雙謀士演武法（最接近真實情境）

讓另一個神算實例扮演「測試謀士」：

謀士甲（你的開發對話）              謀士乙（新戰役，乾淨環境）
    │                                        │
    │── 幫我設計這個奇術 ──>               │
    │<── 生成 SKILL.md ──                   │
    │                                        │
    │         放好 SKILL.md，給實際任務 ──> │
    │                          <── 觀察行為 │
    │                                        │
    │── 它在 X 地方卡住了，沒有讀 finance.md │
    │<── 建議：把 finance.md 的連結移到更前面│
    │                                        │
    │         更新 SKILL.md，再演武一次 ──> │
    │                          <── 通過了 ──│

謀士乙要觀察的具體行為：

💡 仲達觀察：你在謀士甲裡對奇術設計太熟悉，容易用「已知答案」去補充奇術沒說清楚的部分。謀士乙是第一次看到這個奇術，它的行為才是真實將領的縮影。

亂象四：不同兵種演武

# Haiku 兵種需要更明確的指引
model: claude-haiku-4-5-20251001
---
# 若奇術對 Opus 有效，但對 Haiku 失效，
# 代表你的奇術依賴兵種自身的推理能力，需要補充更多明確指示

常見亂象排除

亂象一：奇術不自動觸發？

# 在臥龍神算中詢問：
What skills are available?

# 確認 description 包含將領自然會說的關鍵字
# 描述過於通用 = 不容易被匹配

亂象二：奇術觸發太頻繁？

# 加上更精確的觸發條件，或改為手動觸發
disable-model-invocation: true

亂象三：奇術太多，有些沒載入？

# 設定軍令旗號放寬糧草預算
export SLASH_COMMAND_TOOL_CHAR_BUDGET=32000

第八計：用 OTel 陣法親眼驗證三層機制（接續烽火台篇）

司馬懿接回主講：

若你已按上一篇架好 OTel 陣法 + 大帳（Grafana），可以直接用斥候情報觀察三層漸進揭露的每一步行為。

步驟一：建立一個有完整三層的演武奇術

mkdir -p ~/.claude/skills/layer-test/reference
mkdir -p ~/.claude/skills/layer-test/scripts

~/.claude/skills/layer-test/SKILL.md 兵書：

---
name: layer-test
description: 演武用：顯示三國戰役列表。當將領詢問三國戰役、赤壁之戰、官渡之戰時使用。
allowed-tools: Read, Bash
---

# 三國戰役資料庫

## 可用資料

- 主要戰役列表：[reference/battles.md](reference/battles.md)

## 執行步驟

1. 先讀取 reference/battles.md
2. 執行 scripts/format.sh 格式化輸出
3. 回答將領問題

~/.claude/skills/layer-test/reference/battles.md 兵書輔冊：

# 主要戰役
- 赤壁之戰（208年）
- 官渡之戰（200年）
- 夷陵之戰（221年）

~/.claude/skills/layer-test/scripts/format.sh 奇兵腳本：

#!/bin/bash
echo "=== 戰役查詢結果 ==="
date
echo "查詢完成"

然後開臥龍神算，說：「赤壁之戰是哪一年？」

步驟二：在大帳 Explore 分層觀察

第一層（目錄情報）— 看輸入糧草基準值

目錄情報不會產生獨立 event，但所有奇術的描述都注入在軍令總諭裡，所以每次傳令兵出使的輸入糧草都包含它的重量。對比有奇術和沒有奇術的第一筆傳令，差異就是目錄情報佔用的量。

{service_name="claude-code"}
  | event_name = "api_request"
  | line_format "input={{.input_tokens}} cache_read={{.cache_read_tokens}} model={{.model}}"

第二層（SKILL.md 兵書被讀取）— 看探查細作的路徑

{service_name="claude-code"}
  | event_name = "tool_result"
  | tool_name = "Read"
  | line_format "path={{.tool_parameters}} duration={{.duration_ms}}ms"

你會在 tool_parameters 看到 SKILL.md 兵書的完整路徑出現，這就是第二層觸發的證據。

第三層（兵書輔冊被讀、奇兵腳本被執行）— 分開看

# 兵書輔冊被讀取
{service_name="claude-code"}
  | event_name = "tool_result"
  | tool_name = "Read"
  | line_format "{{.tool_parameters}}"
  |= "reference"

# 奇兵腳本被執行（只有輸出進戰場視野，腳本本身不進）
{service_name="claude-code"}
  | event_name = "tool_result"
  | tool_name = "Bash"
  | line_format "cmd={{.tool_parameters}} output_size={{.tool_result_size_bytes}}bytes"

步驟三：切換 Table 模式看完整時序

在大帳 Explore 把顯示模式從 Logs 改成 Table，然後跑這條軍令：

{service_name="claude-code"}
  | json
  | session_id=`你的-session-id`
  | event_name =~ "tool_result|api_request|user_prompt"
  | line_format "{{.event_sequence}} | {{.event_name}} | {{.tool_name}} | {{.duration_ms}}ms | size={{.tool_result_size_bytes}}B"

💡 仲達觀察：關於 | json：臥龍神算的戰報 body 不是 JSON（只是 claude_code.event_name 字串），所以 | json 會在每筆戰報加一個 __error__="JSONParserErr" 欄位，但不影響查詢結果。大帳的 query builder 常會自動幫你加，直接用完全沒問題；若想消除 __error__ 欄位，把 | json 移除即可。

按時間排序，你會看到三層的完整執行鏈（以下為實際 OTel 陣法數據）：

序號  時刻      事件             兵器   耗時      大小    說明
──────────────────────────────────────────────────────────────────
  0  13:28:03  user_prompt      —      —         —       你說「赤壁之戰是哪年？」（9字）

  1  13:28:08  tool_decision    奇術   —         —       ┐ 第二層：
  2  13:28:08  tool_result      奇術   9ms       74B     ┘ SKILL.md 兵書指令進戰場視野

  3  13:28:08  api_request      —      4637ms    —       神算讀完指令後謀略

  4  13:28:10  tool_decision    Read   —         —       ┐ 第三層：
  6  13:28:10  tool_result      Read   34ms      347B    ┘ battles.md 進戰場視野

  7  13:28:12  api_request      —      2009ms    —       謀略要執行腳本

  9  13:28:13  tool_decision    Bash   —         —       ┐ 第三層：
 10  13:28:14  tool_result      Bash   691ms     226B    ┘ format.sh 輸出進戰場視野
                                                         （腳本本身沒進戰場視野）

 11  13:28:17  api_request      —      2810ms    —       組合最終答案

三層陣法的每一步都清楚可見。

若不是呼叫奇術的戰役，會沒有兵器階段的 span，這是因為神算知道此問題跟任何兵器都沒關係：

從糧草補給效率看按需調兵的實際成本

每次傳令兵出使的 cache_creation_tokens（當輪新增進糧倉的量）會隨著戰場視野逐步累積而遞減：

從糧倉直取從 22,591 增長到 27,620，新增成本（新增糧倉）卻從 4,056 降到 77。此乃漸進揭露之術的實際成本曲線——兵書輔冊和奇兵腳本只在需要時才付新增糧草成本，一旦進入糧倉，後續輪次幾乎免費。

怎麼識別「同一輪戰役」的戰報？

OTel 陣法資料有兩個層級的識別碼：

同一句話的完整鏈路：

你說「赤壁之戰是哪一年？」→ prompt_id: "6b003bf2-..."
  tool_result   奇術        74B  /  9ms  ← 第二層：SKILL.md 兵書指令
  api_request               4637ms       ← 神算謀略
  tool_result   Read        347B / 34ms  ← 第三層：battles.md
  api_request               2009ms       ← 決定執行腳本
  tool_result   Bash        226B / 691ms ← 第三層：format.sh 輸出
  api_request               2810ms       ← 最終回答

你說「官渡之戰呢？」→ prompt_id: "def-456-..."
  ...（新的一輪，全新的 prompt_id，同一個 session_id）

同一個大本營 terminal session 跑完整段對話：全部共用同一個 session_id。

在大帳建戰役下拉選單

此讓你可以在戰情圖上點選要看哪個戰役，不用每次手動貼識別碼。

步驟一：大帳 → Settings → Variables → New variable

Name:        session_id
Type:        Query
Data source: 戰報文書庫（你的 Loki 資料源名稱）
Query:       label_values({service_name="claude-code"}, session_id)
Sort:        Alphabetical desc（最新的排前面）

步驟二：所有 panel 的軍令查詢加上變數 filter：

{service_name="claude-code"}
  | session_id = "$session_id"
  | event_name =~ "tool_result|api_request"

步驟三（選用）：再加一個 prompt_id 變數，縮小到單一對話輪次：

Name:        prompt_id
Type:        Query
Query:       label_values({service_name="claude-code"}, prompt_id)

然後在 panel query 補上：

{service_name="claude-code"}
  | session_id = "$session_id"
  | prompt_id = "$prompt_id"
  | line_format "{{.event_name}} | {{.tool_name}} | {{.duration_ms}}ms"

此乃從大帳精確到「這一句話說出去之後，神算到底動了哪些兵器、照什麼順序、花了多少時間」——三層陣法的行為一覽無遺，也可以直接驗證奇術是否照你設計的路徑在跑。

幾個實用的奇術監控軍令查詢

# 哪些奇術被調用過，各幾次
{service_name="claude-code"}
  | event_name = "tool_result"
  | tool_name = "Skill"
  | line_format "{{.tool_parameters}}"

# 奇術調用失利（有哪個奇術出錯）
{service_name="claude-code"}
  | event_name = "tool_result"
  | tool_name = "Skill"
  | success = "false"

# 某個奇術執行期間讀了哪些兵書輔冊
{service_name="claude-code"}
  | session_id = "$session_id"
  | prompt_id = "$prompt_id"
  | event_name = "tool_result"
  | tool_name = "Read"
  | line_format "{{.tool_parameters}}"

最後一條特別有用：若你在演武「BigQuery 奇術只應該讀 sales.md，不應該讀 finance.md」，此條查詢可以直接告訴你神算在這一輪戰役裡讀了哪些兵書。

兵法總綱：設計原則總整理

此節由諸葛亮主講。孔明搖動羽扇，微笑道：

好的奇術寫法 vs 壞的寫法

❌ 壞：過度解釋（神算已經知道這些）
> PDF（Portable Document Format）是一種廣泛使用的文件格式。
> 要從 PDF 提取文字，你需要一個程式庫...（以下三百字）

✅ 好：直接給核心情報
> 使用 pdfplumber 提取文字：
> ```python
> import pdfplumber
> with pdfplumber.open("file.pdf") as pdf:
>     text = pdf.pages[0].extract_text()
> ```

自由度設定原則

操作越危險、越不可逆 → 給越少自由度（明確軍令）
操作越靈活、越有彈性 → 給越多自由度（方向性指引）

類比：把神算想成在懸崖邊走鋼索的先鋒兵：

• 若兩側都是懸崖 → 給精確的護衛（如：資料庫遷移必須照順序）

• 若是開闊草地 → 只給大方向即可（如：奏摺審查）

奇術品質自我檢查清單

基本品質

• [ ] description 用第三人稱，包含觸發關鍵字

• [ ] SKILL.md 兵書在 500 行以內

• [ ] 兵書輔冊在獨立檔案中，且只有一層深

• [ ] 超過 100 行的兵書輔冊有目錄

糧草效率

• [ ] 沒有過度解釋神算已知的常識

• [ ] 奇兵腳本用執行方式（不是讀進戰場視野）

• [ ] 按領域拆分，避免載入無關內容

密情守則

• [ ] 有副作用的操作有 disable-model-invocation: true

• [ ] 虎符授權只開放必要兵器

• [ ] 危險操作有驗證步驟

可演武性

• [ ] 有至少三個評估案例

• [ ] 用不同兵種演武過

• [ ] 在 OTel 陣法監控中可以追蹤執行路徑

臨陣速查：實戰場景

場景一：封裝奏摺審查流程

---
name: review-pr
description: 對奏摺做完整的程式碼審查，包含安全性、效能、可讀性分析
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## 奏摺情報
- Diff：!`gh pr diff`
- 描述：!`gh pr view --json title,body,labels`
- CI 戰況：!`gh pr checks --json name,status,conclusion`

## 審查重點（依序）
1. 邏輯正確性與邊界條件
2. 安全漏洞（SQL Injection、XSS、硬編碼密鑰）
3. 效能影響（N+1 查詢、不必要的計算）
4. 可讀性與命名

## 輸出格式
用 GitHub comment 格式輸出，直接可貼上。

場景二：特定領域知識庫（RAG 的奇術版本）

不用建向量資料庫，直接把兵書放進奇術的 references 資料夾：

.claude/skills/product-knowledge/
├── SKILL.md
└── references/
    ├── pricing.md      # 產品定價規則
    ├── faq.md          # 常見問題
    └── api-limits.md   # API 限制說明

---
name: product-knowledge
description: 回答關於產品定價、API 限制、功能說明的問題。將領詢問產品細節、定價、功能比較時使用。
user-invocable: false   # 背景知識，不需要手動呼叫
---

## 產品知識庫

- 定價規則：[references/pricing.md](references/pricing.md)
- 常見問題：[references/faq.md](references/faq.md)
- API 限制：[references/api-limits.md](references/api-limits.md)

回答問題時，引用來源兵書，保持準確性。

場景三：多兵種協作奇術

---
name: smart-refactor
description: 對程式碼進行智能重整
context: fork
model: claude-opus-4-6   # 重整分析需要 Opus 兵種
---

分析 $ARGUMENTS 的程式碼，提供重整建議：
1. 識別不良陣型（Code Smell）
2. 建議重整策略
3. 提供重整後的範例程式碼

只提供建議，不直接修改兵書。

總結

司馬懿終末叮嚀：

主公，奇術乃「內功」，監控乃「外照」。

• 奇術設計：務必遵守「一個奇術辦一件事」的 SRP 原則，切莫自鑄萬能兵器，反受其累。

• 演武驗證：建議主公在設計後，先以「雙謀士演武法」進行測試，確保奇術在陌生環境下依然如您所謀。

正如主公所言： 內功不濟，則外強中乾；外照不明，則盲人瞎馬。

若只顧監控而無精良奇術，不過是眼睜睜看著糧草虛擲；若空有奇術卻無監控，則如暗夜行軍，不知險阻。二者相輔相成，方能決勝千里。

那「萬能兵器」看似美好，實則如軍中過重的輜重，平時看似什麼都有，真到臨陣時卻樣樣不精，反倒拖累了大軍行進。專才專用，職責單一，才是用兵之上策。

延伸兵書

• Claude Skills 官方文件

• Agent Skills 開放標準

• Agent Skills 最佳實踐（官方）

• 奇術開放市場 - skillsmp.com

• 上一篇：用 OTel 陣法監控臥龍神算行為

兵書版本：2026-02-20 ｜ 主述：諸葛亮（字孔明）與司馬懿（字仲達）聯合演繹 ｜ 由 /sanguo-rewrite 奇術生成

稟告主公：此乃司馬懿進呈之兵書，詳解如何以 OpenTelemetry 陣法，令臥龍神算之一舉一動盡在掌握，知糧草消耗、察兵器效能、辨戰報異常，使主公運籌帷幄於大帳之中。

為何需要斥候情報？

司馬懿稟告主公：

臥龍神算（Claude Code）乃當世利器，然若無斥候回報，主公便如蒙眼行軍——兵器耗損幾何、糧草消費幾許、哪路斥候出了差錯，一概不知。臣以為，此乃兵家大忌。

無情報之弊，有四：

• 軍費不明：不知每日每週糧草消耗幾何，哪場戰役尤為耗費

• 用兵不察：哪件兵器最常被調遣？哪件兵器行動最遲緩？

• 功績難量：無法向諸將或主公展示神算工具帶來的實際戰果

• 敗仗難溯：兵器偶有失靈卻不知是哪件、發生在何種陣仗之中

透過 OpenTelemetry 陣法整合，主公可得以下情報：

✅ 即時掌握等效軍費消耗（精確到每支兵馬、每五分鐘的耗糧節奏）

✅ 分析糧草使用效率（糧倉補給命中率、輸入糧草 vs 產出糧草之比）

✅ 掌握兵器出征行為（哪件兵器最常出動、哪件行進最遲）

✅ 追查折戟與傳令失利（逐筆查閱失靈兵器、驛站告急、虎符拒發記錄）

✅ 多路諸侯比較（按使用者、團隊、部門分層分析兵力消耗）

連環陣法總覽

司馬懿展開沙盤，向諸將說明：

┌─────────────────────────────────────────────────────────────────┐
│  主公之大本營（開發機器）                                           │
│                                                                   │
│  臥龍神算 CLI                                                      │
│  ├── CLAUDE_CODE_ENABLE_TELEMETRY=1  ← 命令斥候出發的虎符          │
│  ├── OTEL_METRICS_EXPORTER=otlp     → 軍情數報                    │
│  └── OTEL_LOGS_EXPORTER=otlp        → 戰報文書                    │
│           │                                                       │
│           │ OTLP gRPC :4317 / HTTP :4318（驛道）                   │
│           ▼                                                       │
│  ┌────────────────────────────────┐                              │
│  │  情報中樞（OTel Collector）      │  ← 傳令中軍，統一收發          │
│  │  (otel/opentelemetry-          │                              │
│  │   collector-contrib:0.145.0)   │                              │
│  │                                │                              │
│  │  接收：OTLP（gRPC/HTTP 兩路）   │                              │
│  │  處理：限制糧草、批次傳遞        │                              │
│  │  分發：                        │                              │
│  │    ├── 糧草台帳 (:8889)         │                              │
│  │    └── 戰報文書庫 (:3100/otlp)  │                              │
│  └────────────────────────────────┘                              │
│           │                    │                                  │
│           ▼                    ▼                                  │
│  ┌──────────────┐    ┌──────────────┐                           │
│  │  糧草台帳     │    │  戰報文書庫   │  ← 情報儲存               │
│  │ (Prometheus) │    │  (Loki 3.6)  │                           │
│  │  v2.55.1     │    │  (戰況存錄)   │                           │
│  │  (:9090)     │    │  (:3100)     │                           │
│  └──────────────┘    └──────────────┘                           │
│           │                    │                                  │
│           └─────────┬──────────┘                                │
│                     ▼                                             │
│              ┌────────────┐                                      │
│              │  大帳沙盤   │  ← 統帥覽圖之所（Grafana）             │
│              │  12.3.3    │                                      │
│              │  (:3000)   │                                      │
│              └────────────┘                                      │
└─────────────────────────────────────────────────────────────────┘

情報傳遞路徑

軍情二分：數報與戰報

司馬懿言： 情報有二類，各有其用，主公需知其別。

軍情數報（Metrics）

• 性質：累積計數器，記錄糧草消耗總量

• 特性：適合趨勢分析、消耗速率計算

• 存於：糧草台帳（Prometheus）

• 回報頻率：每 60 秒一次（可用 OTEL_METRIC_EXPORT_INTERVAL 加快）

戰報文書（Events/Logs）

• 性質：結構化戰況記錄，含豐富上下文

• 特性：包含具體兵器名稱、出征時長、折戟原因

• 存於：戰報文書庫（Loki）

• 回報頻率：每 5 秒一次（可用 OTEL_LOGS_EXPORT_INTERVAL 調整）

烽火台速建之法

此節由諸葛亮主講。孔明搖動羽扇，微笑道：

孔明言： 仲達所言陣法雖精妙，然主公若欲速見成效，可按亮之三法，依序而行。

第一法：臨陣點火（單次試用）

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=claude-code

claude

第二法：軍令刻入兵書（永久設定，亮力薦此法）

編輯 ~/.claude/settings.json（主公的兵書）：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_SERVICE_NAME": "claude-code",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp"
  }
}

第三法：加快斥候回報（偵錯模式）

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_LOGS_EXPORTER=console,otlp
export OTEL_METRIC_EXPORT_INTERVAL=5000   # 5秒（預設60秒）
export OTEL_LOGS_EXPORT_INTERVAL=1000     # 1秒（預設5秒）

連環陣法開陣

cd monitoring
docker compose up -d

# 確認五軍就位
docker compose ps

# 探查各軍健康
curl http://localhost:13133          # 情報中樞
curl http://localhost:3100/ready     # 戰報文書庫
curl -s http://localhost:3000/api/health | jq .  # 大帳沙盤

司馬懿補充： 主公需防一事——連環陣法啟動後，約需等候 60 秒方能在大帳見到第一批軍情數報。此乃正常等候，非陣法有誤。

兵書詳解：settings.json 深度解析

司馬懿接回主講：

本軍兵書解讀

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",     // 神算一次最多輸出之文字量
    "MAX_THINKING_TOKENS": "8000",                 // 神算思謀之最大用度
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",   // 啟用多路子軍同時出征
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",           // 啟用斥候情報（最關鍵之令）
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",  // 情報中樞位址
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",         // 驛道傳令協議
    "OTEL_SERVICE_NAME": "claude-code",            // 本軍番號（戰報文書庫之識別標籤）
    "OTEL_METRICS_EXPORTER": "otlp",               // 軍情數報之傳送器
    "OTEL_LOGS_EXPORTER": "otlp"                   // 戰報文書之傳送器
  }
}

所有軍令旗號完整參考

核心旗號

行軍調速旗號

輜重管制旗號（高基數問題）

⚠️ 仲達提醒：每場戰役（session）均有獨一番號，若台帳時序過多，可令 OTEL_METRICS_INCLUDE_SESSION_ID=false，以減輕糧草台帳之負擔。

密情管制旗號

五軍聯動：監控堆疊元件解析

司馬懿正色道：

臣為主公佈下五軍聯動之陣，缺一不可，各司其職。

第一軍：情報中樞（OTel Collector）

兵書位址：monitoring/otelcol/config.yaml

情報中樞乃整座連環陣法之樞紐，職責三分：

1. 接收斥候回報：同時接收 gRPC（:4317）與 HTTP（:4318）兩路情報

2. 整理情報：

   • memory_limiter：防止情報堆積壓垮中樞（限制 512MiB）

   • batch：批次整理，每 5 秒 / 1024 筆集中傳送

3. 分發情報：

   • 軍情數報 → 糧草台帳（:8889 供台帳定期抄錄）

   • 戰報文書 → 戰報文書庫（HTTP OTLP）

情報中樞亦自我回報健康狀況（:8888），可透過糧草台帳直接查詢（http://localhost:9090）確認收發量。

第二軍：糧草台帳（Prometheus）

兵書位址：monitoring/prometheus/prometheus.yml

scrape_configs:
  - job_name: "claude-code"
    scrape_interval: 15s
    static_configs:
      - targets: ["otelcol:8889"]

糧草台帳每 15 秒從情報中樞抄錄一次軍情數報，存入時序冊（TSDB）。

存糧期限：預設 15 天。如需延長，於 docker-compose.yml 加入：

command:
  - "--storage.tsdb.retention.time=90d"

第三軍：戰報文書庫（Loki）

兵書位址：monitoring/loki/loki-config.yaml

戰報文書庫採用 TSDB schema v13（最新一代歸檔法），並開啟結構化密令支援（allow_structured_metadata: true），此乃接收 OTLP 戰報之必要設定。

存檔期限：30 天（retention_period: 720h）

第四軍：大帳沙盤（Grafana）

版本：12.3.3 大帳位址：http://localhost:3000（通關密語：admin / admin）

戰情圖透過自動佈陣（provisioning）載入，並設為大帳首頁：

GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH=/var/lib/grafana/dashboards/claude-code.json

大帳沙盤導覽

司馬懿引諸將至大帳，指點沙盤：

一覽台：戰役總覽（Session Overview）

糧草軍費圖（Cost & Token Usage）

• 各路兵馬軍費速率（Cost Rate by Model）：各兵種軍費消耗速率，識別哪路兵馬最貴

• 糧草類型速率（Token Rate by Type）：輸入/輸出/糧倉取糧/糧倉存糧之速率趨勢

• 每五刻軍費（Cost per 5 Minutes）：每五分鐘之軍費消耗（條形圖，按兵種分色）— 清楚顯示何時有密集出征，軍令為 sum by (model)(increase(claude_code_cost_usage_USD_total[5m]))

• 糧草類型分佈（Token Distribution，圓餅圖）：時間範圍內各類型糧草占比

• 各路兵馬軍費占比（Cost by Model，圓餅圖）：各兵種累積軍費占比

• 糧倉補給效率（Cache Hit Rate）：取糧 / 總糧草 × 100%，越高表示糧倉調撥越順暢

💡 仲達觀察：糧倉補給效率乃衡量出征前軍令旗號是否穩定之要指。若主公每番出征皆沿用相同旗號，糧倉直接調撥，無需重新清點，軍費節省可觀。

⚠️ 仲達提醒：此軍費數字為「等效 API 費用」而非主公每月繳納之固定月費。Pro / Max 方案按月收費，此數字僅供消耗趨勢參考，無法對應 Settings 中之配額使用百分比。

兵器排行榜（Top 10 Tools）

使用戰報文書庫 LogQL 軍令查詢（tool_result 戰報），資料來自結構化密令，直接 unwrap 取值。

折戟詳情請見下方「戰報文書 → 兵器折戟記錄」，提供比排行榜更完整之逐筆戰況。

戰報文書閱覽（Logs & Events）

觀圖識機：看到什麼、代表什麼、能做什麼

司馬懿向諸將道： 觀圖非為賞玩，乃為臨陣決策。每處旗標背後，皆有可採取之行動。

一覽台 — 一眼掌握戰役總況

糧草軍費圖 — 費用節奏與效率

兵器排行榜 — 兵器使用行為

戰報文書 — 折戟追查第一入口

軍情數報完整冊（所有 Metrics）

司馬懿取出台帳典籍，逐一說明：

指標命名轉換規則

糧草台帳（Prometheus）中，指標名稱由 . 轉換為 _：

各指標可用維度（Labels）

claude_code_cost_usage_USD_total
  └── 維度：model（兵種）、session_id（戰役番號）、user_account_uuid（將領號）...

claude_code_token_usage_tokens_total
  └── 維度：type (input|output|cacheRead|cacheCreation)、model、session_id...

claude_code_lines_of_code_count_total
  └── 維度：type (added|removed)、session_id...

claude_code_code_edit_tool_decision_total
  └── 維度：tool_name (Edit|Write|NotebookEdit)、decision (accept|reject)、
              source (config|hook|user_permanent|user_temporary|user_abort|user_reject)、
              language (TypeScript|Python|...|unknown)

claude_code_active_time_seconds_total
  └── 維度：type (user|cli)、session_id...

常用台帳查詢範例

# 今日軍費消耗
sum(increase(claude_code_cost_usage_USD_total[24h]))

# 按兵種分組的軍費速率
sum by (model)(rate(claude_code_cost_usage_USD_total[$__rate_interval]))

# 糧倉補給效率（節省軍費的關鍵指標）
100 * sum(increase(claude_code_token_usage_tokens_total{type="cacheRead"}[24h]))
    / sum(increase(claude_code_token_usage_tokens_total[24h]))

# 工事淨新增行數
sum(increase(claude_code_lines_of_code_count_total{type="added"}[24h]))
- sum(increase(claude_code_lines_of_code_count_total{type="removed"}[24h]))

# TypeScript 工事的修築核准率
sum(rate(claude_code_code_edit_tool_decision_total{language="TypeScript",decision="accept"}[$__rate_interval]))
/ sum(rate(claude_code_code_edit_tool_decision_total{language="TypeScript"}[$__rate_interval]))

# 每場戰役的平均軍費
sum(increase(claude_code_cost_usage_USD_total[$__range]))
/ count(count by (session_id)(claude_code_active_time_seconds_total))

戰報文書總錄（所有 Events）

軍令追蹤：prompt.id 關聯之法

司馬懿道： 每次主公下令，神算可能出動多路人馬。透過 prompt.id 可追蹤一道軍令觸發的完整行軍鏈路：

主公軍令 (prompt.id: "abc-123")
  └── 傳令出使 (prompt.id: "abc-123")
  └── 傳令出使 (prompt.id: "abc-123")  ← 同一道令可能多次傳令
  └── 衝鋒奇兵出征 (prompt.id: "abc-123")
  └── 探查細作出征 (prompt.id: "abc-123")
  └── 修築工事出征 (prompt.id: "abc-123")
  └── 虎符決策 (prompt.id: "abc-123")

查詢特定軍令之完整行軍記錄：

{service_name="claude-code"} | json | prompt_id = "你的-prompt-id"

各類戰報詳細欄位

user_prompt（主公軍令）

{
  "event.name": "user_prompt",
  "event.timestamp": "2025-01-15T10:30:00Z",
  "event.sequence": 1,
  "prompt_length": 256,
  "prompt": "<僅在 OTEL_LOG_USER_PROMPTS=1 時才錄入原話>"
}

api_request（傳令出使）

{
  "event.name": "api_request",
  "model": "claude-sonnet-4-6",
  "cost_usd": 0.00145,
  "duration_ms": 3200,
  "input_tokens": 12500,
  "output_tokens": 850,
  "cache_read_tokens": 11000,
  "cache_creation_tokens": 1500,
  "speed": "normal"
}

tool_result（兵器出征結果）

{
  "event.name": "tool_result",
  "tool_name": "Bash",
  "success": "true",
  "duration_ms": 450,
  "tool_result_size_bytes": 2048,
  "decision_type": "accept",
  "decision_source": "config",
  "tool_parameters": "{\"bash_command\":\"npm test\",\"timeout\":120000}"
}

tool_decision（虎符授決）

{
  "event.name": "tool_decision",
  "tool_name": "Edit",
  "decision": "accept",
  "source": "user_permanent"
}

api_error（傳令失利）

{
  "event.name": "api_error",
  "model": "claude-sonnet-4-6",
  "error": "Rate limit exceeded",
  "status_code": "429",
  "duration_ms": 500,
  "attempt": 2,
  "speed": "normal"
}

奇兵五策：進階應用場景

司馬懿獻上五策奇謀：

第一策：識別最拖沓之兵器

# 找出平均出征時長最久的兵器
topk(10,
  sum by (tool_name)(
    sum_over_time(
      {service_name="claude-code"} | event_name=`tool_result` | json
      | unwrap duration_ms | __error__="" [24h]
    )
  ) /
  sum by (tool_name)(
    count_over_time(
      {service_name="claude-code"} | event_name=`tool_result` [24h]
    )
  )
)

第二策：察看衝鋒奇兵之動向

# 查看所有衝鋒指令（需 tool_parameters 中有 bash_command）
{service_name="claude-code"}
  | event_name=`tool_result`
  | tool_name=`Bash`
  | json
  | line_format "{{.tool_parameters}}"

第三策：衡量出征效率（每時辰產出）

# 每時辰新修工事行數
sum(rate(claude_code_lines_of_code_count_total{type="added"}[1h])) * 3600

# 每時辰插旗（commit）次數
sum(rate(claude_code_commit_count_total[1h])) * 3600

第四策：異常軍費告警（大帳預警）

在大帳沙盤中設定告警旗號：

# 當一個時辰軍費超過五金時觸發警報
sum(increase(claude_code_cost_usage_USD_total[1h])) > 5

第五策：兵種選用最佳化

# 各兵種「每單位糧草之軍費」效率比較
sum by (model)(rate(claude_code_cost_usage_USD_total[$__rate_interval]))
/
sum by (model)(rate(claude_code_token_usage_tokens_total[$__rate_interval]))

度支算糧：ROI 衡量與成本分析

司馬懿掐指算道：

戰力量化之道

糧草管控四訣

1. 每日告警：設定大帳預警，當單日軍費超出預算即鳴金示警

2. 兵種選用：Opus 4.6 費用約為 Sonnet 4.6 之十五倍，確認是否調用了正確兵種

3. 糧倉優化：軍令旗號越穩定，糧倉補給效率越高，可節省九成糧倉部分之費用

4. 戰役時長：久戰不收兵，context 越積越大，軍費越高；適時鳴金收兵重整，可節省消耗

月度軍費戰報（PromQL）

# 本月總軍費
sum(increase(claude_code_cost_usage_USD_total[30d]))

# 本月 vs 上月軍費環比
sum(increase(claude_code_cost_usage_USD_total[30d]))
/ sum(increase(claude_code_cost_usage_USD_total[30d] offset 30d))

諸侯聯盟：多人團隊監控

司馬懿謀劃多路諸侯協同之策：

以旗號區別各路人馬

# 於各將領的兵書中設定所屬陣營
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

按將領分組之軍費查詢

# 各將領之軍費分佈
sum by (user_account_uuid)(increase(claude_code_cost_usage_USD_total[7d]))

# 各將領糧草消耗排行（前十名）
topk(10,
  sum by (user_account_uuid)(
    increase(claude_code_token_usage_tokens_total[7d])
  )
)

主帥統一部署：管理員集中設定

於 /etc/claude/settings.json（主帥令冊）中統一部署：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

📝 主帥令冊之優先度高於各將領自設兵書，無法被覆蓋。

陣前排難：常見問題排除

司馬懿終末叮嚀：

主公，圖表雖美，然「觀圖」之後的「決策」才是勝負關鍵。臣已將這些陣法圖示融入秘錄之中，建議主公下一步可執行以下軍令：

司馬懿沉聲道： 主公需防以下陣前之亂，臣逐一列出破解之法。

亂象一：大帳沙盤無任何軍情數報

診斷步驟：

# 1. 確認情報中樞正在接收斥候回報
docker compose logs otelcol --tail=50

# 2. 確認糧草台帳之抄錄目標狀態
curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, health: .health}'

# 3. 直接查閱情報中樞匯出之數報
curl -s http://localhost:8889/metrics | grep claude_code | head -20

# 4. 確認虎符旗號已升起
claude --version  # 並在啟動前 echo $CLAUDE_CODE_ENABLE_TELEMETRY

常見原因：

• CLAUDE_CODE_ENABLE_TELEMETRY 旗號未升或不在正確的營帳（shell）中

• 情報中樞驛道（4317）未開放

• 糧草台帳尚未完成首次抄錄（等候 >30 秒）

亂象二：戰報文書庫無任何戰報

# 1. 確認戰報文書庫已就緒
curl http://localhost:3100/ready

# 2. 查詢庫中是否有任何存檔
curl -G -s "http://localhost:3100/loki/api/v1/query" \
  --data-urlencode 'query={service_name="claude-code"}' \
  --data-urlencode 'limit=5' | jq .

# 3. 若無存檔，確認情報中樞之戰報管道
docker compose logs otelcol | grep -i "loki\|log"

戰報分類過濾問題：

若 event_name 存於戰報正文而非標籤，需改用：

# 原本（不可用）
{service_name="claude-code"} | event_name=`tool_result`

# 改為 JSON 解讀
{service_name="claude-code"} | json | event_name = "tool_result"

密情守則：安全性與隱私考量

司馬懿正色叮囑： 情報雖重要，洩密亦是大患，主公需知以下密情守則。

預設隱私防護

臥龍神算之遙測，預設已做以下防護：

潛在密情外洩之處

tool_result 戰報之 tool_parameters 欄位含衝鋒指令，可能含有：

• 密語（若直接寫在指令中）

• 金鑰令牌

• 典籍路徑（可能洩露大本營之目錄結構）

建議：在情報中樞中加入 attributes 處理器遮蔽敏感欄位：

processors:
  attributes:
    actions:
      - key: tool_parameters
        action: delete  # 或使用 update + 遮罩

本地陣法 vs 遠端傳送

本連環陣法完全在大本營運行，無任何情報傳送至外部勢力。

若要傳送至雲端（如 Grafana Cloud、Datadog 等外藩），請確認：

1. 驛道加密（TLS/HTTPS）

2. 認證虎符（OTEL_EXPORTER_OTLP_HEADERS 設定 Bearer token）

3. 情報存留政策符合軍規

延伸兵書

• Claude Code 監控文書

• Anthropic ROI 量化

• OpenTelemetry 規格

• Prometheus PromQL 查詢教典

• Loki LogQL 查詢文法

• Grafana Dashboard 程式碼

兵書版本：2026-02-19 ｜ 主述：司馬懿（仲達）、諸葛亮（孔明）｜ 由 /sanguo-rewrite 奇術生成

本文整合 Anthropic 官方 Best Practices 與社群實戰 Tips，帶你由淺入深掌握 Claude Code。

什麼是 Claude Code？為什麼值得學？

如果你還在用「複製程式碼貼到 ChatGPT，再複製答案貼回去」的工作流程，Claude Code 會讓你大開眼界。

Claude Code 是 Anthropic 推出的命令列工具，它直接活在你的 terminal 裡，能夠讀懂你的整個 codebase、寫入檔案、執行指令、操作 git，甚至幫你開 PR。它不只是個「提示框」，而是一個能主動採取行動的 AI 代理（agentic coding assistant）。

用一句話形容：你告訴它要做什麼，它去搞定。

很多從 Cursor、GitHub Copilot 轉過來的工程師都說，用過 Claude Code 之後回不去了。原因不是它比較聰明，而是它的工作方式根本不同——它在你的環境裡工作，而不是你把東西帶去它的環境。

第一步：安裝與基本啟動

安裝 Claude Code 只需要一行：

curl -fsSL https://claude.ai/install.sh | bash

安裝後，進入你的專案目錄，直接輸入 claude 就能啟動。

四種啟動模式

建議新手先從 claude 開始，熟悉基本操作後，-c 和 -r 會成為你每天的好朋友。

Headless Mode（claude -p）

claude -p 是 Claude Code 從「個人工具」升級到「團隊基礎設施」的關鍵能力：

• 非互動式，執行完就結束，不進入對話模式
• 適合用在 CI/CD、git hooks、自動化腳本
• 可搭配 --output-format stream-json 輸出結構化 JSON，方便下游程式處理
• 可搭配 --allowedTools 限制可用工具範圍

# 最簡單的用法
claude -p "review 這個 PR 的安全性問題"

# pipe 資料進去
cat error.log | claude -p "分析這些錯誤，找出最常見的根因"

# 輸出 JSON 給下游處理
claude -p "列出所有 deprecated 的 API 呼叫" --output-format stream-json | your_script.py

# 限制工具範圍（更安全）
claude -p "把 foo.py 從 React 改成 Vue" --allowedTools Edit "Bash(git commit:*)"

第二步：學會在對話中操作

進入 Claude Code 後，它看起來像個聊天介面，但有一些特殊符號和快捷鍵讓你的效率倍增。

三個超有用的符號

@ 指定檔案：輸入 @ 後會顯示檔案列表，支援模糊搜尋，讓你精確告訴 Claude 要操作哪個檔案，不用擔心它讀錯地方。

! 直接執行 shell 指令：有時你只是想快速執行一個指令，不需要 AI 處理，直接用 ! 前綴就能執行 shell 命令。例如 !git status 或 !ls -la。

# 加入記憶：當你輸入 # 開頭的訊息，系統會詢問你要存入哪個 CLAUDE.md，讓 Claude 長期記住這段背景知識。例如「# 我們的 API 版本是 v2，請不要使用 v1 的 endpoint」，之後的每次對話它都會記得。

不可不知的快捷鍵

• ESC — 中斷當前任務。Claude 正在瘋狂編輯檔案但方向不對？按 ESC 立刻停下，不會破壞 session，可以重新下指令
• ESC ESC（按兩次） — 顯示過去發送的訊息列表，讓你選擇一個重新發送，類似「開分支」的概念，從不同的起點探索
• Shift+TAB — 切換工作模式

三種工作模式

使用 Shift+TAB 可以在三種模式間切換：

自動接受模式（auto-accept edits）：Claude 提議的修改自動核准，適合信任度高、不想每次都確認的場景。速度最快。

規劃模式（plan mode）：Claude 只做分析和規劃，不會實際動檔案。在開始寫程式之前，先用這個模式讓它產出設計方案給你審核，是架構討論的好幫手。

危險模式（--dangerously-skip-permissions）：跳過所有權限確認，讓 Claude 全速工作。官方文件特別強調這個模式要在有限制的 Docker container 裡使用，不建議在本機直接用。

第三步：設定你的專案大腦 — CLAUDE.md

CLAUDE.md 是整個 Claude Code 生態系中最重要的概念。這個檔案是 Claude 每次啟動對話時必讀的說明書，放對內容，效果立竿見影。

第一次使用時，執行 /init 指令，Claude 會自動分析你的 codebase 結構並產生一份基礎的 CLAUDE.md，再手動精修即可。

放什麼在 CLAUDE.md？

• 常用的 bash 指令（npm run build、npm run test 等）
• 核心檔案與工具函式的位置說明
• 程式碼風格規範（例如：使用 ES modules 而非 CommonJS）
• 測試方式與規則
• Git 工作流程規範（例如：branch 命名方式、merge vs. rebase）
• 開發環境特殊設定
• 任何你希望 Claude 永遠記住的事項

# 常用指令
- npm run build: 建置專案
- npm run test: 執行測試
- npm run typecheck: 型別檢查

# 程式碼風格
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 盡量用解構語法引入 (import { foo } from 'bar')
- 所有 API 呼叫都走 /src/api/ 資料夾的封裝

# 工作流程
- 每次改完記得跑 typecheck
- 測試優先，盡量跑單一測試而非全套
- branch 命名格式：feature/xxx 或 fix/xxx

CLAUDE.md 的四個層級

根據官方文件，CLAUDE.md 其實有四個層級，由高到低依序套用：

CLAUDE.local.md 會自動加入 .gitignore，適合放沙箱 URL、個人測試資料等不應上傳的設定。

@import 語法

CLAUDE.md 支援用 @ 語法引入其他檔案，最多支援 5 層巢狀：

# 引入其他說明文件
請參考 @README 了解專案概覽，@package.json 查看可用指令。

# Git 工作流程
@docs/git-instructions.md

# 個人偏好（引入自 home 目錄，不會進 git）
@~/.claude/my-project-instructions.md

這讓 CLAUDE.md 保持簡潔，把細節拆到獨立文件裡分開維護。

Monorepo 建議結構

CLAUDE.md 支援多層級繼承，Claude 會自動把沿途讀到的所有 CLAUDE.md 合併進 context，這對 monorepo 非常適合：

root/
├── CLAUDE.md                ← 全專案共用：monorepo 工具（nx/turborepo）、CI 指令、跨 package 規範
│                               可用 @import 引入各 package 文件
├── docs/
│   └── git-instructions.md  ← 被 @import 引用的獨立說明
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md        ← 前端專用：React 規範、CSS-in-JS、UI 元件慣例
│   ├── backend/
│   │   └── CLAUDE.md        ← 後端專用：API 設計規範、DB migration 指令
│   └── shared/
│       └── CLAUDE.md        ← shared lib 專用：型別規範、不能有 side effect 等限制
└── CLAUDE.local.md          ← 個人設定，自動加入 .gitignore

分層邏輯：

• 根目錄 放「任何 package 都適用」的內容，例如 pnpm install、branch 命名規則、PR 流程
• 各 package 只放「這個 package 才有意義」的差異化內容

當你在 packages/frontend/ 啟動 claude，它會同時讀到根目錄與 packages/frontend/ 的 CLAUDE.md，不需要在每個 package 重複寫共用規範。

小技巧：根目錄的 CLAUDE.md 加一行職責邊界說明，例如「packages/shared 只能被其他 package 引用，不能引用 frontend 或 backend 的程式碼」，跨 package 重構時 Claude 就不會犯錯。

其他管理記憶的方式

• # 快速新增：輸入 # 內容，系統會詢問要存入哪個 CLAUDE.md
• /memory 指令：在對話中執行，會用系統編輯器開啟記憶檔案，適合一次做大量整理

第四步：上下文管理 — 最關鍵的資源

很多人用 Claude Code 用著用著開始感覺它「變笨了」，原因幾乎都是一樣的：context window 滿了。

Claude 的整個對話歷史、讀過的每個檔案、執行過的每個指令輸出，全都塞在 context window 裡。一個複雜的除錯過程，可能幾萬個 token 就燒掉了。當 context 快滿，Claude 開始「遺忘」早期的指令，犯更多錯誤。

兩個關鍵指令

/clear：清除所有當前對話的 context，重新開始。開始一個全新任務之前，養成習慣打 /clear，讓它帶著清爽的頭腦工作。

/compact：壓縮 context，可以附上提示說明要保留哪些重點。注意，壓縮後有可能遺失部分細節、導致後續表現變差，更建議的做法是直接開新的 session。

官方建議：在長對話工作後、切換到新任務前，定期使用 /clear。有些工程師甚至把「每次開始新任務就 /clear」當成強制習慣。

第五步：善用 Think 模式深度推理

Claude Code 支援幾個特殊關鍵字，讓它進入不同深度的思考模式：

使用方式很直覺，直接在 prompt 裡說「請 think hard，設計這個資料庫 schema」或「ultrathink，分析這個 bug 的根本原因」即可。

重要提醒：更深的思考消耗更多 token，建議根據問題複雜度選擇。簡單任務用 think 就夠，複雜架構設計或難以追蹤的 bug 才用 ultrathink。

中文指令「想一想」、「深度思考」也可以被識別，但優先用英文以確保穩定性。

第六步：掌握高效工作流

有了基礎工具知識後，來看幾個 Anthropic 官方推薦的實戰工作流。

工作流一：探索 → 規劃 → 實作 → Commit

這是最通用的工作流，適合大多數功能開發場景：

1. 探索：告訴 Claude 讀相關的檔案、圖表或 URL，但明確說「還不要寫程式」。這個階段讓它建立完整的 context。
2. 規劃：請 Claude 制定實作計畫（可以用 think hard 讓它想得更仔細）。計畫確認後，請它寫成 Markdown 文件或 GitHub issue 存檔。
3. 實作：拿著確認好的計畫，請它動手寫程式。
4. Commit：請 Claude 寫 commit message 並 commit，需要的話也可以請它開 PR。

前兩步是關鍵。很多工程師跳過規劃直接叫它寫，結果方向跑偏，浪費更多時間。

工作流二：TDD 測試驅動開發

這是 Anthropic 內部最愛的工作流，AI 時代的 TDD 威力加倍：

1. 請 Claude 根據預期的輸入輸出寫測試，明確說要做 TDD，不要先做 mock 實作
2. 請它跑測試，確認測試確實失敗
3. 對測試滿意後，請它 commit 測試
4. 請 Claude 寫讓測試通過的實作，不允許修改測試，讓它自己跑測試、修改、再跑，直到全部通過
5. 確認後 commit 實作

提供清晰的「完成標準」是讓 Claude 表現最好的方式，而測試就是最好的完成標準。

工作流三：截圖視覺迭代（UI 開發最愛）

1. 給 Claude 一個設計稿圖片（拖放或貼上截圖）
2. 請它實作 UI
3. 透過 Puppeteer MCP 讓它截圖比對
4. 請它根據差異迭代修正
5. 滿意後 commit

Claude 在有視覺目標時表現特別好。第一版可能不完美，但給它 2-3 輪迭代後通常相當接近設計稿。

第七步：進階技巧 — 讓 Claude 更強大

擴充工具能力：MCP

MCP（Model Context Protocol）是讓 Claude Code 連接外部服務的標準協議。常用的有：

• Puppeteer：讓 Claude 能操控瀏覽器、截圖
• GitHub MCP：更深度整合 GitHub 操作
• 資料庫 MCP：直接查詢你的資料庫

在專案目錄加入 .mcp.json 設定檔，整個團隊都能共用這些工具。

自訂 Slash 指令

把重複的工作流程做成 slash 指令，存在 .claude/commands/ 資料夾裡。例如建立 fix-github-issue.md：

請分析並修復 GitHub issue：$ARGUMENTS

步驟：
1. 用 gh issue view 取得 issue 詳細內容
2. 理解問題描述
3. 搜尋 codebase 找出相關檔案
4. 實作必要的修改
5. 撰寫並執行測試驗證修復
6. 確認通過 lint 和 type check
7. 建立描述性的 commit message
8. Push 並開 PR

之後只要輸入 /project:fix-github-issue 1234 就能一鍵處理 issue #1234。個人常用指令則存到 ~/.claude/commands/ 讓所有專案都能用。

允許清單（Permissions）

用 /permissions 指令把常用操作加入允許清單，例如 Edit（允許編輯檔案）和 Bash(git commit:*)（允許 git commit），不用每次都確認，工作流程更流暢。

第八步：多 Claude 並行 — 終極生產力

當你熟悉了單 Claude 工作流後，可以嘗試更強大的多 Agent 模式。

雙 Claude 互審

用第一個 Claude 寫程式，另開一個 terminal 或用 /clear 重置，讓第二個 Claude 審查程式碼。不同的 context 往往能發現不同的問題，效果類似真實的 code review。

Git Worktrees 平行作業

這是 Anthropic 工程師內部的常用技巧：用 git worktree add 建立多個獨立的工作目錄，每個目錄開一個 Claude，同時處理不同任務：

git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

cd ../project-feature-a && claude  # Claude A 做 feature A
cd ../project-feature-b && claude  # Claude B 做 feature B

# 完成後清理
git worktree remove ../project-feature-a
git worktree remove ../project-feature-b

兩個任務互不干擾，你只需要輪流去確認進度和核准操作。

給新手的建議清單

操作習慣

• 每次開始新任務前先 /clear，保持 context 乾淨
• 養成用 ESC 中斷而非 Ctrl+C（後者會直接退出整個程式）
• 用 @ 精確指定檔案，不要讓它猜
• 重要決策和設定用 # 記錄到 CLAUDE.md，或用 /memory 做整理

下指令的原則

• 具體比模糊好。「幫我加測試」遠不如「為 foo.py 新增一個測試 case，覆蓋使用者未登入的邊界情況，不要用 mock」
• 先規劃再實作，省下來的時間遠比多打一次指令值得
• 根據問題複雜度選擇 think 層級，不要每次都 ultrathink

品質把關

• Claude 寫的程式你負責 review，最終責任在你
• 有測試和 CI 的環境下信任它更多，沒有就要多留意
• 對話越長越要注意 context 品質，適時 /clear 比用 /compact 更可靠

結語

Claude Code 的學習曲線不在於功能複雜，而在於思維方式的轉換：從「AI 幫我補全程式碼」轉向「AI 是我的協作工程師，我負責方向，它負責執行」。

一開始可能會覺得要打很多字、要設定很多東西。但一旦你的 CLAUDE.md 建立起來，slash 指令設定好，權限調整完，你會發現整個開發體驗有質的飛躍。

從今天開始，打開 terminal，進入你的專案，輸入 claude，然後問它：「你對這個 codebase 有什麼問題嗎？」——你們的旅程就此開始。

參考資料：Anthropic 官方 Claude Code Best Practices、Anthropic 官方 Memory 文件、Cash Wu 的 Claude Code Tips

摘要:

• 高吞吐量 (TPS)： 系統需要支援每秒 1,000,000 次交易 (1,000,000 TPS)。

• 為了達到這個目標，後端估算可能需要約 2,000 個資料庫節點來處理每秒 1 百萬次轉帳（因為每次轉帳涉及兩條指令，相當於 2 百萬次操作）。

• 可靠性： 系統的可靠性必須至少達到 99.99%。

• 事務與一致性： 必須支援交易 (transactions)，以確保資料的正確性。

• 可重現性 (Reproducibility)： 系統需要具備從頭開始重放資料來重建歷史餘額的能力

Step 1 粗略估算

1. 估算的前提與假設

• 背景： 討論 TPS 時，通常假設系統將使用事務型資料庫 (transactional database)。

• 性能基準： 來源指出，現今運行在典型資料中心節點上的關係型資料庫，大約可以支援每秒幾千次事務。

• 單節點假設： 為了進行估算，假設一個資料庫節點可以支援 1,000 TPS（每秒 1,000 次事務）。

• 目標負載： 系統必須支援 1,000,000 TPS（每秒 1 百萬次交易）。

2. 初始計算與修正

這個估算過程的關鍵點在於，交易數（轉帳次數）並不等同於實際的資料庫操作數。

1. 初始（不準確的）計算： 如果系統需要 1,000,000 TPS，而每個資料庫節點能處理 1,000 TPS，那麼初始估算需要 1,000 個資料庫節點（1,000,000 / 1,000 = 1,000）。

2. 關鍵修正（實際操作數）： 這個計算被認為是稍微不準確的。這是因為每個轉帳指令 (transfer command) 需要兩個操作：

◦ 從一個帳戶扣除資金 (deducting money)。

◦ 向另一個帳戶存入資金 (depositing money)。

3. 最終所需的節點數量： 為了支援每秒 1 百萬次的轉帳，系統實際上需要處理高達 2 百萬次 TPS（2,000,000 TPS，即 2 百萬次操作）。 因此，根據每個節點 1,000 TPS 的假設，系統需要 2,000 個節點（2,000,000 / 1,000 = 2,000 節點）來支援此負載。

3. 對設計的影響

這個粗略估算直接影響了設計目標，因為所需節點的總數與單節點可處理的事務次數成反比：

• 設計目標： 降低所需的總節點數量是設計目標之一，這意味著必須增加單一節點可以處理的事務數量 (per-node TPS)。單節點的 TPS 越高，所需的硬體成本就越低。

來源提供了 TPS 與所需節點數量的映射表（Table 12.1），進一步說明了這種關係：

總結來說，粗略估算確定了數位錢包系統為了處理 1 百萬次轉帳的負載，需要數千個資料庫節點，這為後續討論分區 (sharding)、分佈式事務 (distributed transactions) 以及如何提高單節點效率奠定了基礎。

Step 2 - Propose High-level Design and Get Buy-in

1. API 設計 (API Design)

在深入討論架構之前，首先要確立外部客戶端將如何與系統互動。

• API 協定： 採用 RESTful API 協定。

• 唯一支援的 API： 在本次面試中，只需支援一個 API，即跨錢包餘額轉帳操作。

• API 規範：

◦ 方法/路徑： POST /v1/wallet/balance_transfer。

◦ 功能： 執行從一個錢包向另一個錢包轉帳。

• 請求參數 (Request parameters)： 請求需要包含以下欄位：

◦ from_account：借記帳戶（扣款帳戶）。

◦ to_account：貸記帳戶（收款帳戶）。

◦ amount：金額（資料類型為字串 string）。

◦ currency：貨幣類型（使用 ISO 4217 標準）。

◦ transaction_id：用於去重複 (deduplication) 的 UUID。

•Response Body:

◦ status

◦ transaction_id

2. 三種高階設計方案的討論 (Three High-level Designs)

此階段的重點是逐步提出並完善三個高階設計方案，以解決系統對一致性和可重現性的嚴格要求。

• 2.1. 方案一：簡單的記憶體內解決方案 (Simple In-memory solution)

這是第一個被提出的高階方案，主要利用記憶體內分區儲存（例如 Redis 叢集）來維護帳戶餘額。

• 架構： 錢包服務 (Wallet Service) 是無狀態的，它根據分片資訊（可能由 ZooKeeper 管理）向分佈在多個 Redis 節點上的帳戶發出更新指令。

以下是面試官與面構、高效能優勢，以及最關鍵的缺陷——缺乏事務原子性 (Atomicity) 進行了交流。

1. 面試者對方案的描述（架構概述）

面試者首先說明了該方案的結構和工作原理：

• 資料儲存與分散： 帳戶餘額分佈在多個 Redis 節點上。

• 分片資訊： ZooKeeper 被用於維護分片（sharding）資訊。

• 服務層： 無狀態的錢包服務 (stateless Wallet Service) 利用分片資訊來定位客戶端所在的 Redis 節點。

• 操作： 錢包服務隨後相應地更新帳戶餘額。

2. 面試官的評論與關鍵挑戰（指出缺陷）

面試官肯定了此設計在工作方面是可行的，但立刻指出了它最大的問題——無法滿足系統對「正確性」的嚴格要求：

• 承認可行性： 面試官指出：「這個設計是可行的 (The design works)」。

• 否決原因： 面試官接著說：「但它不符合我們對正確性的要求 (but it does not meet our correctness requirement)」。

• 問題暴露： 面試官解釋了轉帳操作如何違反原子性：

◦ 錢包服務需要為每次轉帳更新兩個 Redis 節點。

◦ 無法保證這兩次更新都能成功。

◦ 失敗情境： 如果錢包服務節點在第一次更新完成之後、但在第二次更新完成之前崩潰，就會導致轉帳不完整 (an incomplete transfer)。

結論要求： 面試官強調，這兩次更新需要作為單一的原子事務 (single atomic transaction) 進行。

• 結論： 儘管它能滿足高吞吐量的需求（1,000,000 TPS），但無法保證原子性。由於一次轉帳涉及兩次獨立的更新，如果錢包服務在兩次更新之間崩潰，會導致轉帳不完整。因此，此方案因缺乏事務保證而被排除。

• 2.2. 方案二：基於資料庫的分佈式事務解決方案 (Database-based distributed transaction solution)

為了提供事務保證，設計從記憶體儲存轉向使用事務型關聯式資料庫。由於帳戶仍然需要分區，因此需要實施分佈式事務。

來源討論了兩種分佈式事務的實施方式：

• 兩階段提交 (2PC)： 這是一種低階解決方案，依賴資料庫本身來確保原子性。然而，2PC 的主要問題是可能導致鎖被長時間佔用，並且協調者 (Coordinator) 可能成為單點故障 (single point of failure)。

• 嘗試-確認/取消 (TC/C)： 這是一種高階解決方案，在業務邏輯層處理事務，因此它與底層資料庫無關。TC/C 分為兩個階段：第一階段是 Try（保留資源），第二階段是 Confirm（確認）或 Cancel（取消，即「undo」操作）。

• Try (嘗試階段)： 進行業務檢查，並預留必要的業務資源。例如圖中的帳戶 A 先扣除 $1，確保這筆錢被鎖定，但還沒真正交給帳戶 C。

• Confirm (確認階段)： 當所有參與者的 Try 都成功後，執行真正的業務操作。此階段不進行業務檢查，只使用 Try 階段預留的資源。

• Cancel (取消階段)： 如果有任何參與者的 Try 失敗，則執行回滾，釋放 Try 階段預留的資源（即「undo」操作）。

第一階段：Try Phase (Figure 12.7)

這是所有流程的起點。

1. Coordinator (Wallet Service) 發起請求。

2. Database A (扣款方)： 執行 UPDATE 將餘額減 1。這就是「預留資源」，錢已經從 A 的可用餘額中消失了。

3. Database C (收款方)： 此時執行 NOP (No Operation)，意即在 Try 階段不做任何實質改動，僅確認服務可用。

第二階段：Confirm Phase (Figure 12.8)

當 Try 階段全部成功（Done）時進入此流程。

1. Database A： 既然 Try 已經扣過錢了，Confirm 階段只需確認（NOP），不需要再動 A。

2. Database C： 執行 UPDATE 將餘額加 1。這完成了最終的轉帳動作。

3. 結果： A 減 1，C 加 1，事務成功完成。

第二階段：Cancel Phase (Figure 12.9)

如果在 Try 階段發生錯誤（例如圖中的 X Failed），則進入取消流程。

1. Database A： 因為 Try 階段已經扣了 $1，現在必須「補償」回來。執行 UPDATE balance = balance + 1，將 A 的錢加回去。

2. Database C： 維持 NOP，因為 Try 階段本來就沒動到 C。

3. 結果： A 的餘額恢復原狀，系統回到初始狀態，保證了一致性。

階段狀態表（Phase Status Table）

1. 階段狀態表的用途與必要性

在分佈式事務的設計中，例如 TC/C，協調者（在本案例中是錢包服務或 TCC/Saga 協調者）負責協調多個資料庫節點的更新。

• 解決的問題： 來源提到，如果錢包服務在 TC/C 處理的中途重新啟動，它可能會遺失所有先前的操作歷史記錄，並且不知道如何恢復事務。

• 解決方案： 解決方案很簡單，就是將 TC/C 執行的進度 (progress) 儲存到事務型資料庫中的階段狀態表內。

• 功能： 階段狀態表用於儲存分佈式事務的狀態，從而允許系統在協調者崩潰或重新啟動後，知道如何恢復，確保事務的持久性和一致性。

2. 階段狀態表的內容

階段狀態表儲存了確保分佈式事務能夠恢復和追蹤所需的重要資訊，包括：

1. 分佈式事務的 ID 與內容 (ID and content)。

2. Try 階段的狀態 (The status of the Try phase)：記錄了給定資料庫的狀態（例如，狀態是否已發送、已接收、或已回應）。

3. 第二階段的名稱 (The name of the Second phase)：根據 Try 階段的結果，可以計算出第二階段是 **Confirm（確認）**或 Cancel（取消）。

4. 第二階段的狀態 (The status of the second phase)。

5. 亂序執行狀態 (An out-of-order execution status)：用於處理亂序執行的狀況。

• TC/C 發生 Out-of-order Execution

TC/C 模式處理因網路延遲導致「亂序執行（Out-of-order Execution）」的機制如下：

1. 問題場景定義

在分散式系統中，網路延遲可能導致指令到達順序與發送順序不一致。最典型的亂序場景是 Cancel 命令比 Try 命令先到達。

• 發生原因： 協調者（Coordinator）發送 Try 後，因為網路擁塞導致超時（Timeout）。協調者隨即判定失敗並發送 Cancel 進行補償。結果 Cancel 請求比遲到的 Try 請求更早到達參與者節點。

• 風險： 如果不處理，節點收到 Cancel 時發現沒有 Try 記錄可能什麼都不做。接著 Try 到達並成功預留資源。但因為協調者已經發過 Cancel 並認為事務已結束，這筆被 Try 預留的資源將永遠不會被 Confirm 或釋放（資源洩漏）。

2. 解決方案：階段狀態表與亂序旗標

為了處理解決這個問題，系統必須利用 階段狀態表 (Phase Status Table) 配合特定的邏輯檢查：

步驟一：允許「空回滾」並記錄標記

當節點收到 Cancel 指令時，如果發現沒有對應的 Try 記錄，它不能視為錯誤或忽略。

• 邏輯： 節點必須允許在未收到 Try 的情況下執行 Cancel。

• 記錄： 節點必須在 階段狀態表 中插入一條記錄，並設置一個 「亂序旗標 (out-of-order flag)」。這個旗標表示：「我已經收到過 Cancel 了，雖然我還沒看過 Try」。

步驟二：Try 階段的預先檢查

當延遲的 Try 指令最終到達節點時，系統必須執行以下檢查：

• 檢查： Try 操作在執行任何資源預留之前，必須先查詢階段狀態表，檢查是否已存在該事務 ID 的 亂序旗標。

• 結果： 如果發現該旗標存在（表示 Cancel 已經先執行了），Try 操作必須返回失敗 (return a failure)。

透過在 階段狀態表 中儲存 亂序執行狀態 (out-of-order execution status)，系統確保了即使 Cancel 先於 Try 執行，遲到的 Try 也不會錯誤地鎖定資源，從而保證了分散式事務在網路不穩定環境下的正確性。這也是為什麼來源強調階段狀態表是 TC/C 中處理協調者崩潰恢復與亂序執行的關鍵組件。

3. 階段狀態表的位置

階段狀態表通常儲存在包含資金被扣除的錢包帳戶（借記帳戶）的資料庫中。

在最終的高階設計中，階段狀態表與 TCC/Saga 協調者協同工作。當使用者發送轉帳命令時：

• TCC/Saga 協調者會在階段狀態表中建立一條記錄，以追蹤該事務的狀態。

• 當分區 1（帳戶 A 所在的資料庫）成功執行扣款操作後，Saga 協調者會在階段狀態表中記錄該操作成功。這確保了在執行下一步（向帳戶 C 存入資金）之前，系統狀態是可追溯和可恢復的。

總體來說，階段狀態表是將應用層實現的分佈式事務（如 TC/C 和 Saga）的狀態持久化的機制，從而將無狀態的服務轉變為具備故障恢復能力的系統。

不平衡狀態 (Unbalanced state)

「不平衡狀態 (Unbalanced state)」是在分佈式事務解決方案，特別是應用層事務模型，如嘗試-確認/取消 (TC/C) 或 Saga，執行過程中出現的一種暫時性資料不一致狀態。

這張圖片詳細解釋了在分散式事務（特別是 TCC 或 Saga 模式）中，系統處於中間過程時所產生的**「不平衡狀態 (Unbalanced state)」**。

簡單來說，它描述了「錢已經扣了，但還沒入帳」的那段暫時性消失的狀態。

圖表流程拆解

追蹤了帳戶 A 加帳戶 C 的總金額 ($A+C$) 變化：

1. 初始狀態 (Before TCC start)

• 狀態： 帳戶 A 有 $1，帳戶 C 有 $0。

• 總和： $A+C = \$1$。此時系統是平衡的。

2. 第一階段結束後 (After first phase: Try)

• 動作： Coordinator 執行了 Try: A-$1。資料庫 A 的餘額被更新為 $0。

• 狀態： 帳戶 A 變成了 $0，而帳戶 C 依然是 $0。

• 總和： $A+C = \$0$。

• 現象 (Money loss)： 從系統宏觀角度看，這 $1 暫時「失蹤」了。這就是圖中所標註的 「不平衡狀態 (Unbalanced state)」。這是一種暫時性的資料不一致。

3. 第二階段結束後 (After second phase: Confirm)

• 動作： Coordinator 執行了 Confirm: C+$1。資料庫 C 的餘額被更新為 $1。

• 狀態： 帳戶 A 為 $0，帳戶 C 為 $1。

• 總和： $A+C = \$1$。

• 現象 (Money recovery)： 隨著第二階段完成，失蹤的 $1 被找回來了，系統重新回到平衡狀態。

以下是針對不平衡狀態的詳細說明：

1. 不平衡狀態的定義與發生時機

不平衡狀態發生在分佈式轉帳操作的第一階段結束時。

• 機制： 假設有一個從帳戶 A 轉帳 1給帳戶C的操作。在∗∗TC/C的Try階段(第一階段)∗∗結束時，∗∗1 已成功從帳戶 A 扣除**，但帳戶 C 仍然保持不變（尚未收到 $1）。

• 結果： 在這個中間點，帳戶 A 和帳戶 C 的餘額總和將會是 $0（假設交易開始時總和為 $1），這小於 TC/C 開始時的總和。

2. 會計原則的違反

這種暫時的狀態被稱為「不平衡」，因為它違反了一項基本的會計原則：在一次交易之後，資金的總和應該保持不變。

• 在 Try 階段完成後，資金似乎「丟失」了 $1 (Money loss: $1)，這就是不平衡狀態的體現。資金必須等到第二階段（Confirm 確認）完成後才會恢復平衡 (Money recovery: $1)。

3. TC/C 導致狀態可見性

不平衡狀態是應用層級分佈式事務（如 TC/C 和 Saga）的特性，因為這些高階解決方案是透過協調數個獨立的本地事務 (several independent local transactions) 來運作的。

• 應用程式可見： 因為 TC/C 是在應用程式層實施的，應用程式本身能夠看到這些本地事務之間產生的中間結果（即不平衡狀態）。

• 與 2PC 的區別： 相比之下，資料庫事務或兩階段提交 (2PC) 版本的集中式分佈式事務，通常會由資料庫維護這種高層次事務的抽象，因此這些不平衡狀態對於應用程式來說是不可見的。

4. 解決與處理

儘管存在不平衡狀態，事務保證仍然由 TC/C 維持。這意味著系統最終會通過執行第二階段（確認或取消）來達成最終的一致性。

• 由於高階分佈式事務會導致這種差異可見，如果底層的系統（如資料庫）沒有預先修復這些差異，那麼應用程式層必須自行處理這些不一致性 (handle them ourselves)。例如，TC/C 模式必須透過 Confirm 階段完成轉入，或者透過 Cancel 階段執行補償操作（undo）來回滾先前的操作，從而最終消除不平衡狀態。

此階段還討論了 Saga 工作流程，這是另一種應用層的分佈式事務模式。TC/C 和 Saga 都可以用來實施分佈式事務，但 TC/C 允許並行執行，而 Saga（除非使用協調模式）通常需要線性順序執行。

[Saga Pattern](https://ithelp.ithome.com.tw/articles/10236124)

[Saga, Choreography vs Orchestration](https://ithelp.ithome.com.tw/articles/10236411)

[YouTUbe Digital Wallet System Design | Distributed transactions | SAGA pattern](https://www.youtube.com/watch?v=8ByEyCd-MEM)

Saga v.s. TC/C

Saga 模式與 TC/C (Try-Confirm/Cancel) 在性能上最顯著的差異在於**「並行執行能力 (Parallel Execution)導致的延遲 (Latency)不同，以及適用交易長度**的區別。

以下是差異分析：

1. 並行執行與延遲 (Parallelism & Latency)

這是兩者在架構設計上最直接的性能差異：

• TC/C (低延遲，支援並行)：

  • 機制： TC/C 允許協調者在第一階段 (Try 階段) 同時向所有參與服務發送請求（例如同時預留資源 A 和資源 B）。

  • 性能影響： 由於操作是並行執行的，總耗時取決於最慢的那個服務，而非所有服務耗時的總和。因此，TC/C 非常適合對延遲敏感 (Latency-sensitive) 的系統,,。

• Saga (較高延遲，線性執行)：

  • 機制： 在典型的編排模式中，Saga 通常被設計為線性執行 (Linear execution)，即操作按順序一個接一個執行（例如先扣款，成功後再觸發存款）。

  • 性能影響： 總耗時是鏈條上所有服務耗時的總和。如果業務流程包含多個步驟，Saga 的整體響應時間會比 TC/C 長,。

2. 資源鎖定與交易長度 (Resource Locking & Transaction Duration)

兩者對資源的佔用方式不同，這決定了它們分別適用於「短交易」還是「長交易」：

• TC/C (適用於短交易)：

  • 資源預留 (Quasi-Isolation)： TC/C 在 Try 階段會「凍結」或「預留」資源（例如將資金移入 trading_balance 欄位）。雖然這不是資料庫層級的死鎖，但在 Confirm/Cancel 完成前，這部分資源是無法被其他事務使用的,。

  • 性能限制： 由於應用程式崩潰可能導致預留狀態遺失，且長時間預留會影響業務並發度，TC/C 被設計用來處理短時間且要求高一致性的交易,。

• Saga (適用於長交易 - Long Lived Transactions)：

  • 無鎖/立即提交 (Lock-free)： Saga 的每個本地事務執行完後會立即提交 (Commit) 到資料庫，不進行資源預留。這意味著資源鎖定時間極短,。

  • 性能優勢： 由於不長時間佔用資源，Saga 非常適合處理跨越數分鐘甚至數天的長事務 (LLTs)，在這種場景下它能維持高吞吐量，不會像 2PC 或 TC/C 那樣因為長時間佔用資源而導致性能瓶頸,,。

3. 補償成本 (Compensation Cost)

• TC/C (輕量回滾)： TC/C 的 Cancel 操作通常只是釋放 Try階段預留的資源（例如解凍資金），邏輯相對簡單且副作用較小,。

• Saga (昂貴補償)： 由於 Saga 的本地事務已提交，若後續步驟失敗，必須執行補償事務 (Compensating Transaction) 來「修正」數據（例如退款）。這通常涉及新的業務邏輯寫入（如新增一條負向流水的紀錄），在性能開銷和開發複雜度上可能較高,。

總結比較表

結論： 如果您的系統追求極致的低延遲且能接受較高的開發成本（需實作 Try/Confirm/Cancel 三個接口），TC/C 是性能較佳的選擇；如果您處理的是長流程且希望避免資源鎖定，Saga 則能提供更好的系統吞吐量。

面試官: 分散式事務解決方案雖然有效，但在某些情況下可能表現不佳。例如，用戶可能在應用層輸入了錯誤的操作，在這種情況下，我們指定的金額可能是錯誤的。我們需要一種方法來追蹤問題的根因，並審計（Audit）所有帳戶操作。我們該如何做到這一點？

• 2.3. 方案三：具備可重現性的事件溯源解決方案 (Event sourcing solution with reproducibility)

此方案是為了滿足面試官提出的對審計和追蹤問題根本原因的更高要求。

1. 為什麼選擇事件溯源？ (Background)

在面試場景中，面試官提出了一個關鍵挑戰：外部審計員可能會問：「我們如何知道任何給定時間點的帳戶餘額？」或「我們如何證明程式碼更改後的系統邏輯仍然正確？」。

傳統資料庫只儲存當前的狀態 (Current State)（例如：餘額 $10），一旦更新就覆蓋了舊值，丟失了變更的歷史軌跡。事件溯源正是為了回答這些問題而引入的設計哲學。

• 核心理念： 事件溯源 (Event Sourcing) 哲學將所有狀態變化儲存為不可變的事件清單，而不是只儲存最終的餘額狀態。

• 可重現性： 事件清單是不可變的，狀態機 (State machine) 的行為是確定性的，因此系統可以透過重放 (replaying) 事件來重建歷史狀態。這是事件溯源相對於其他架構的最大優勢。

• 狀態機： 狀態機在事件溯源中扮演核心角色，負責驗證命令 (Validate commands) 和應用事件 (Apply event) 來更新狀態。

2. 四個核心概念 (Definitions)

事件溯源的四個重要術語,：

1. 命令 (Command)：

   • 這是來自外部世界的意圖 (Intended action)。例如：「從 A 轉 $1 給 C」。

   • 命令不是事實，它可能會失敗（例如餘額不足）。命令必須按順序放入 FIFO 佇列中。

2. 事件 (Event)：

   • 這是已經發生並經過驗證的事實 (Validated fact)。例如：「從 A 轉了 $1 給 C (Transferred $1 from A to C)」。

   • 不可變性： 事件一旦生成，就永遠不能被改變。

   • 區別： 一個命令可能產生零個或多個事件。事件代表過去式。

3. 狀態 (State)：

   • 這是在應用事件後變更的內容。在錢包系統中，狀態就是客戶的帳戶餘額 (Map<User, Balance>)。

4. 狀態機 (State Machine)：

   • 這是驅動事件溯源過程的引擎。它有兩個主要功能：

     1. 驗證命令並生成事件 (Validate commands and generate events)。

     2. 應用事件以更新狀態 (Apply event to update state)。

   • 關鍵特性 - 確定性 (Deterministic)： 狀態機的行為必須是嚴格確定性的。它不能包含任何隨機性（如隨機數、依賴系統時間或外部 I/O）。這保證了只要輸入相同的事件序列，無論何時重播，輸出的狀態永遠一致。

3. 運作流程 (Dynamic View)

狀態機處理請求的流程如下,：

1. 讀取命令： 從命令佇列（如 Kafka）讀取轉帳請求。

2. 讀取狀態： 從資料庫讀取當前的餘額。

3. 驗證邏輯： 檢查餘額是否足夠。

4. 生成事件： 如果驗證通過，生成事件（如 MoneyDeducted）。

5. 應用事件： 更新資料庫中的餘額。

• 系統分為三個層次：Command（指令）、Event（事件） 與 State（狀態）。

• 指令經過驗證（Validate）後轉化為事件，事件被應用（Apply）後改變狀態。

• 錢包服務範例 (Wallet Service Example)：

• 

• Command 是來自外部世界（客戶端）的請求。它不是事實，因為它可能會失敗（例如餘額不足或驗證失敗）。Command 會被放入一個 FIFO 隊列中等待處理。

  • •         {
                "name": "TransferRequest",
                "payload": {
                  "transaction_id": "81589980-2664-11ec-9621-0242ac130002", // 用於去重 (Deduplication)
                  "from_account": "A",      // 扣款帳戶
                  "to_account": "C",        // 收款帳戶
                  "amount": "1.00",         // 金額 (字串類型以避免精度丟失)
                  "currency": "USD"         // 貨幣類型
                },
                "timestamp": "2023-10-27T10:00:00Z"
              }
      

      ```

• Event 是經過狀態機驗證後產生的結果。它代表已經發生且不可變 (Immutable) 的歷史事實。

  •     事件 1：扣款事件 (針對帳戶 A)
        {
          "name": "MoneyDeducted",    // 過去式，表示已發生
          "payload": {
            "account_id": "A",        // 影響的帳戶
            "amount": "1.00",         // 變動金額
            "transaction_id": "81589980-2664-11ec-9621-0242ac130002", // 關聯的交易 ID
            "new_balance": "9.00"     // (可選) 有些設計會包含結果餘額，或由重播計算
          },
          "sequence_id": 101,         // 用於確保順序
          "timestamp": "2023-10-27T10:00:01Z"
        }
        事件 2：入帳事件 (針對帳戶 C)
        {
          "name": "MoneyCredited",    // 過去式
          "payload": {
            "account_id": "C",
            "amount": "1.00",
            "transaction_id": "81589980-2664-11ec-9621-0242ac130002"
          },
          "sequence_id": 102,
          "timestamp": "2023-10-27T10:00:01Z"
        }
    

• • 在錢包服務中，「指令」就是轉帳請求。

    * 這些指令會進入一個 FIFO Queue。實務上常用的選擇是 Kafka。

    * 當狀態儲存在關聯式資料庫時，狀態機按以下 5 個步驟執行：

    1. Read commands： 從指令隊列（Command Queue）讀取指令。

    2. Read balance： 從資料庫讀取目前的餘額狀態。

    3. Validate： 驗證指令（例如餘額是否充足）。若有效，為涉及的帳戶生成事件。

    * 範例： 指令是「A 轉 $1 元給 C」，會生成兩個事件：「A: $-$1」與「C: $+$1」。

    4. Read next event： 讀取生成的事件。

    5. Apply event： 通過更新資料庫中的餘額來應用事件。

4. 核心優勢：可重現性 (Reproducibility)

這是事件溯源相對於其他架構的最大優勢。由於事件列表是不可變的，且狀態機是確定性的，系統可以透過從頭重播 (Replay) 所有事件來隨時重建歷史上的任何狀態。這完美解決了對帳與審計的需求，也能用來驗證修復 Bug 後的邏輯是否正確,。

審計問題的解答 (Final Section)

事件溯源能回答以下三個關鍵問題：

1. 我們能否知道任何特定時間點的帳戶餘額？

   • 回答： 可以，透過從起點重放事件，直到你想知道的那個時間點為止。

2. 我們如何知道歷史與目前的餘額是正確的？

   • 回答： 透過事件列表重新計算來驗證。

3. 如何證明代碼更動後系統邏輯依然正確？

   • 回答： 可以針對同一組事件運行不同版本的代碼，驗證其產出的結果是否一致（即 Regression Testing）。

結論： 由於具備強大的審計能力，事件溯源通常被視為錢包服務（Wallet Service）的標準解決方案。

5. CQRS 架構 (Command-Query Responsibility Segregation)

[CQRS亂談](https://ithelp.ithome.com.tw/articles/10237458)

由於事件溯源主要處理寫入，且只是一堆事件日誌，客戶端很難直接查詢「我現在有多少錢」。因此系統採用了 CQRS,：

• 寫入路徑 (Write Path)： 由上述狀態機負責，處理命令並生成/儲存事件。

• 讀取路徑 (Read Path)： 由 唯讀狀態機 (Read-only state machines) 負責。它們訂閱事件流，並計算出狀態，儲存到專門用於查詢的資料庫或視圖 (View) 中。客戶端查詢時是訪問這個讀取層。

• 特性： 讀取層可能有輕微的延遲（最終一致性），但在金融系統中，這通常是可接受的，且能提供完整的審計軌跡。

6. 深入設計：高效能與可靠性優化 (Deep Dive)

為了達到 100 萬 TPS 的目標，簡單的 Kafka + 資料庫方案是不夠的。所以能考慮進行深度的技術優化：

A. 檔案基於的命令與事件儲存 (File-based Storage)

• 問題： 透過網絡訪問遠端儲存（如 Kafka 或傳統 DB）太慢。

• 優化： 將命令和事件直接保存在本地磁碟 (Local Disk) 的追加日誌檔 (Append-only file) 中。

• 技術： 利用 mmap (Memory Mapped File) 技術。這將磁碟文件映射到記憶體數組中，將寫入操作轉換為記憶體操作，並由作業系統負責刷入磁碟。這將隨機 I/O 轉換為極快的循序 I/O (Sequential I/O)。

B. 狀態儲存 (Local State)

• 使用嵌入式的高效能資料庫，如 RocksDB 或 SQLite，直接在本地儲存狀態（餘額），避免遠端資料庫調用的開銷。RocksDB 使用 LSM-tree 結構，非常適合高寫入場景。

C. 快照 (Snapshot)

• 為了避免每次重啟都要從「創世區塊」重播數百萬個事件，系統會定期將當前的狀態存成快照。

• 恢復時，只需讀取最近的快照，然後重播該快照之後的事件即可。

D. 可靠性：Raft 共識演算法 (Consensus)

[etcd Raft淺談(上) 名詞簡介](https://ithelp.ithome.com.tw/articles/10239673)

• 風險： 使用本地磁碟儲存雖然快，但如果該節點掛了，資料就丟了（單點故障）。

• 解決方案： 引入 Raft 共識演算法。

• 運作： 系統將節點組成一個 Raft 群組（1 個 Leader，多個 Follower）。

  • Leader 接收命令並轉換為事件。

  • Raft 負責將事件列表 (Event List) 複製到其他 Follower 節點。

  • 只要大多數節點存活，資料就不會丟失。

  • 這確保了在本地高效能儲存的基礎上，同時擁有分散式系統的高可用性與資料一致性。

為什麼「事件 (Event)」是可靠性的核心？

為什麼我們備份「事件」而不是「指令」或「狀態」。

• 指令 (Command) 不具備決定性： 指令在轉化為事件的過程中，可能包含隨機數或外部 I/O。如果只記錄指令，重新執行時結果可能不同。

• 事件 (Event) 是既定事實： 事件代表已經發生的歷史紀錄（如：帳戶餘額變動），它是不可變 (Immutable) 的。

• 結論： 只要確保「事件列表」具備高可靠性，我們隨時都能透過重放 (Replay) 事件來還原系統狀態。

利用 Raft 演算法達成共識

為了避免單點故障，需要將事件列表同步到多個節點。

• 多數決原則 (Majority)： 只要集群中超過半數的節點正常運作（例如 5 台中有 3 台活著），系統就能持續運作。

• 角色分工：

  • Leader (領導者)： 負責接收外部指令、轉換成事件，並同步給其他節點。

  • Follower (跟隨者)： 接收來自 Leader 的事件並存檔。

  • Candidate (候選人)： 競選 Leader 時的過渡狀態。

解決效能瓶頸：分片與即時性

單一 Raft 組無法支撐百萬級 TPS，因此需要擴展架構。

• 資料分片 (Sharding)：根據 Key 的雜湊值將資料切分到不同的 Raft 組（Partition）。(Multi Raft Group)

• 從「拉」到「推」：為了避免客戶端因輪詢 (Polling) 產生的延遲，引入 反向代理 (Reverse Proxy)。當狀態機完成更新時，主動將結果推送給反向代理，給予用戶即時的回饋感。

跨區交易：Saga 分散式事務

當一筆交易（如轉帳）跨越兩個分片時，需要 Saga 協調器 (Coordinator) 來確保一致性。

轉帳成功流程 (Happy Path)：

1. 發起請求：用戶 A 要求轉帳 $1 給用戶 C。

2. 狀態追蹤：協調器在狀態表中建立記錄。

3. 分片 1 執行 (扣款)：協調器發送指令給 Partition 1。Leader 將其轉為事件、同步 Raft，並執行扣款。成功後透過讀取路徑回傳狀態給協調器。

4. 分片 2 執行 (存款)：協調器確認扣款成功後，發送指令給 Partition 2 執行存款。同樣完成 Raft 同步後回傳成功訊息。

5. 結束交易：協調器更新狀態表，完成整個分散式事務。

架構總結表

在分散式架構中，當多個請求同時想對同一個帳戶（用戶 A）進行操作時，系統設計主要透過 「排序」 與 「驗證」 兩個核心機制來確保資料正確性。

1. Raft Leader 的序列化 (Serialization)

在 Partition 1 的 Raft 組中，只有一個 Leader 負責接收所有指令。

• 指令排隊：不論有多少個 Saga 協調器同時發送「扣款用戶 A」的指令，Partition 1 的 Leader 都會將這些指令放入一個指令列表 (Command List) 中。

• 單一順序：Leader 會按照接收順序，一個接一個地處理這些指令。這意味著在技術層面上，對同一個用戶的操作已經在進入系統的第一關被「排好隊」了。

2. 狀態驗證與事件轉換 (Validation)

當 Leader 處理到某個扣款指令時，它會執行以下動作：

• 即時驗證：Leader 會根據目前的狀態機（State Machine）檢查用戶 A 的餘額是否足夠。

• 轉換為事件：如果餘額足夠且指令合法，Leader 才會將其轉換為「事件（Event）」並寫入 Log。

• 失敗處理：如果前一筆轉帳已經扣光了錢，第二筆指令在「驗證」階段就會被 Leader 拒絕，不會產生事件，也不會進行後續的 Raft 同步。

3. 分散式事務的狀態鎖定 (Isolation)

在 Saga 模型中，為了防止「超支」或「髒讀」，通常有兩種常見的設計模式：

當用戶 A 同時有兩筆轉帳請求時：

1. 第一筆請求到達 Leader，Leader 檢查餘額夠，轉換成「扣款事件」，同步給 Follower 並完成扣款。

2. 第二筆請求在 Leader 的隊列中等待，輪到它時，Leader 發現餘額已經被第一筆扣掉了。

3. 結果：Leader 直接回傳錯誤給 Saga 協調器，該筆交易失敗，不會影響系統一致性。

如果第一筆交易在 Partition 1 扣款成功，但最後在 Partition 2 失敗時，系統是如何幫用戶 A「把錢還回來」的（補償機制）?

簡單來說：既然錢已經扣了，我們就再發一個「存回去」的動作來抵銷。

總結

該章節描述的 Event Sourcing 方案，是從一個簡單的概念演進為一個工業級的高頻交易引擎：

1. 利用 事件不可變性 解決審計問題。

2. 利用 CQRS 解決查詢問題。

3. 利用 mmap/RocksDB (本地循序 I/O) 解決吞吐量問題 (1M TPS)。

4. 利用 Raft 解決本地儲存的可靠性問題。

一、 動機與痛點：為什麼你需要介入 AI 的生命週期？

在預設狀態下，Claude Code 雖然強大，但它是「被動」且「無狀態」的，這導致了開發者常遇到以下痛點：

1. 記憶重置 (Session Amnesia)：

   • 痛點：每次重啟終端機，AI 就像失憶一樣。

   • 解法：你需要一個機制，在 SessionStart 時自動把「上一集的劇情（Session Log）」灌輸給它。

2. 程式碼品質不一 (Inconsistent Quality)：

   • 痛點：AI 寫出的 Go 程式碼可能忘了 gofmt，或者留下了 fmt.Println 除錯訊息。

   • 解法：你需要一個「糾察隊」，在 PostToolUse（工具用完後）自動執行格式化與檢查。

3. 危險操作 (Safety Risks)：

   • 痛點：AI 有時會過度自信，想直接 git push 到主分支。

   • 解法：你需要在 PreToolUse（工具執行前）設下攔截點，強制顯示警告。

4. 上下文丟失 (Context Drift)：

   • 痛點：對話太長時，重要資訊被壓縮丟棄。

   • 解法：利用 PreCompact 在壓縮發生前，將關鍵狀態寫入硬碟。

二、 核心機制：生命週期圖解 (The Lifecycle)

要掌握 Hooks，必須理解這張生命週期圖。這不僅是流程，更是我們可以「插入程式碼」的機會點：

我們可以將其劃分為三個戰略區域：

1. 啟動與結束區 (Session Management)

• SessionStart：這是「載入記憶」的時刻。你的腳本 session-start.js 在這裡執行，負責掃描 .claude/sessions/ 下的 .tmp 檔案，告訴 AI 上次工作到哪裡。

• SessionEnd：這是「存檔」的時刻。session-end.js 會將當前的狀態快照保存下來，供下次使用。

2. 代理循環區 (The Agentic Loop) - 自動化的核心

這是圖中橙色虛線框起來的部分，也是 AI 實際工作的地方。

• PreToolUse (攔截層)：在 AI 真正執行 Bash 或 Edit 之前。這是防止錯誤的最佳時機（例如阻擋 git push）。

• PostToolUse (修正層)：在 AI 修改完檔案後。你的腳本可以在這裡自動執行 gofmt，或是檢查有沒有遺留的 fmt.Print。

3. 維護區 (Maintenance)

• PreCompact：當 Token 即將爆滿時，系統會觸發壓縮。利用 pre-compact.js 記錄這一事件，防止重要資訊在壓縮中「無聲消失」。

三、 配置結構與語法

Hooks 配置在 .claude/settings.local.json 中：

{
  "hooks": {
    "HookEvent": [
      {
        "matcher": "條件表達式",
        "hooks": [
          {
            "type": "command",
            "command": "要執行的指令"
          }
        ]
      }
    ]
  }
}

Matcher 語法

• "*" - 匹配所有情況

• tool == "Bash" - 匹配特定工具

• tool == "Edit" && tool_input.file_path matches "\\.go$" - 組合條件

• !(tool_input.file_path matches "README\\.md") - 排除條件

四、 實戰配置解析：你的腳本做了什麼？

結合 Go 專案範例，這套配置實現了以下具體功能：

1. 智慧型記憶掛載 (SessionStart)

你的配置不再只是依賴單一的 CLAUDE.md，而是引入了時間序列的 Session Log。

• 行為：腳本會檢查 go.mod 確認這是 Go 專案，並自動尋找最近修改過的 sessions/*.tmp 檔案。

• 優勢：AI 一啟動就知道專案類型（Go Module）以及上次具體的工作內容，實現「無縫熱啟動」。

配置範例：

{
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node /path/to/project/.claude/scripts/hooks/session-start.js"
        }
      ]
    }
  ]
}

session-start.js：

#!/usr/bin/env node
const path = require('path');
const fs = require('fs');

function main() {
  const sessionsDir = path.join(process.env.HOME, '.claude', 'sessions');

  // 檢查是否有最近的 session 記錄
  if (fs.existsSync(sessionsDir)) {
    const files = fs.readdirSync(sessionsDir)
      .filter(f => f.endsWith('.tmp'))
      .sort().reverse();

    if (files.length > 0) {
      console.error(`[SessionStart] Found ${files.length} recent session(s)`);
      console.error(`[SessionStart] Latest: ${files[0]}`);
    }
  }

  // Go 專案檢測
  if (fs.existsSync('go.mod')) {
    const content = fs.readFileSync('go.mod', 'utf8');
    const match = content.match(/^module\s+(.+)$/m);
    if (match) {
      console.error(`[SessionStart] Go project: ${match[1]}`);
    }
  }

  process.exit(0);
}

main();

2. 強制性程式碼規範 (PostToolUse)

這是這套配置最精彩的部分—— 自動修正 (Auto-Correction)。

• 行為：當監測到 Edit 工具修改了 .go 檔案後，Hooks 會自動觸發：

    gofmt -w "file_path"
  

  同時，若發現檔案內含有 fmt.Print，會透過 console.error 警告開發者。

• 優勢：即使 AI 生成的程式碼格式混亂，寫入硬碟的那一刻也會被強制修正為標準格式。這大幅減少了 code review 的負擔。

配置範例：

{
  "PostToolUse": [
    {
      "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.go$\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"const{execSync}=require('child_process');const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path;if(p&&fs.existsSync(p)){try{execSync('gofmt -w \\\"'+p+'\\\"',{stdio:['pipe','pipe','pipe']})}catch(e){console.error('[Hook] gofmt failed: '+e.message)}}console.log(d)})\""
        }
      ]
    },
    {
      "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.go$\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path;if(p&&fs.existsSync(p)){const c=fs.readFileSync(p,'utf8');if(/fmt\\\\.Print(ln|f)?\\\\(/.test(c)){console.error('[Hook] WARNING: fmt.Print found in '+p);console.error('[Hook] Consider using proper logging instead')}}console.log(d)})\""
        }
      ]
    },
    {
      "matcher": "tool == \"Bash\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const cmd=i.tool_input?.command||'';if(/gh pr create/.test(cmd)){const out=i.tool_output?.output||'';const m=out.match(/https:\\\\/\\\\/github.com\\\\/[^/]+\\\\/[^/]+\\\\/pull\\\\/\\\\d+/);if(m){console.error('[Hook] PR created: '+m[0])}}console.log(d)})\""
        }
      ]
    }
  ]
}

3. 危險操作防護網 (PreToolUse)

• 行為：當 AI 試圖執行 git push 時，Hooks 會攔截並輸出：

  [Hook] Review changes before push... Consider: git diff HEAD~1

• 優勢：增加了一道「冷靜期」，防止 AI 在未經人工確認的情況下將錯誤程式碼推送到遠端倉庫。

配置範例：

{
  "PreToolUse": [
    {
      "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"console.error('[Hook] Review changes before push...');console.error('[Hook] Consider: git diff HEAD~1, git log --oneline -5')\""
        }
      ]
    },
    {
      "matcher": "tool == \"Write\" && tool_input.file_path matches \"\\\\.(md|txt)$\" && !(tool_input.file_path matches \"README\\\\.md|CLAUDE\\\\.md\")",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"console.error('[Hook] WARNING: Creating documentation file');console.error('[Hook] Consider using CONTEXT.md for session notes')\""
        }
      ]
    }
  ]
}

4. 提交前最後檢查 (Stop)

配置範例：

{
  "Stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"const{execSync}=require('child_process');const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{execSync('git rev-parse --git-dir',{stdio:'pipe'})}catch{console.log(d);process.exit(0)}try{const files=execSync('git diff --name-only HEAD',{encoding:'utf8',stdio:['pipe','pipe','pipe']}).split('\\\\n').filter(f=>/\\\\.go$/.test(f)&&fs.existsSync(f));let hasDebug=false;for(const f of files){const content=fs.readFileSync(f,'utf8');if(/fmt\\\\.Print(ln|f)?\\\\(/.test(content)){console.error('[Hook] WARNING: fmt.Print found in '+f);hasDebug=true}}if(hasDebug)console.error('[Hook] Remove debug prints before committing')}catch(e){}console.log(d)})\""
        }
      ]
    }
  ]
}

5. Session 結束存檔 (SessionEnd)

配置範例：

{
  "SessionEnd": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node /path/to/project/.claude/scripts/hooks/session-end.js"
        }
      ]
    }
  ]
}

session-end.js：

#!/usr/bin/env node
const path = require('path');
const fs = require('fs');

function main() {
  const sessionsDir = path.join(process.env.HOME, '.claude', 'sessions');
  const today = new Date().toISOString().split('T')[0];
  const sessionFile = path.join(sessionsDir, `${today}-session.tmp`);

  if (!fs.existsSync(sessionsDir)) {
    fs.mkdirSync(sessionsDir, { recursive: true });
  }

  const time = new Date().toTimeString().slice(0, 5);

  if (fs.existsSync(sessionFile)) {
    let content = fs.readFileSync(sessionFile, 'utf8');
    content = content.replace(/\*\*Last Updated:\*\*.*/, `**Last Updated:** ${time}`);
    fs.writeFileSync(sessionFile, content);
    console.error(`[SessionEnd] Updated session: ${today}-session.tmp`);
  } else {
    const template = `# Session: ${today}
**Started:** ${time}
**Last Updated:** ${time}

## Completed
- [ ]

## In Progress
- [ ]

## Notes for Next Session
-
`;
    fs.writeFileSync(sessionFile, template);
    console.error(`[SessionEnd] Created session: ${today}-session.tmp`);
  }

  process.exit(0);
}

main();

6. 壓縮前狀態保存 (PreCompact)

配置範例：

{
  "PreCompact": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node /path/to/project/.claude/scripts/hooks/pre-compact.js"
        }
      ]
    }
  ]
}

pre-compact.js：

#!/usr/bin/env node
const path = require('path');
const fs = require('fs');

function main() {
  const sessionsDir = path.join(process.env.HOME, '.claude', 'sessions');
  const logFile = path.join(sessionsDir, 'compaction-log.txt');

  if (!fs.existsSync(sessionsDir)) {
    fs.mkdirSync(sessionsDir, { recursive: true });
  }

  const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
  fs.appendFileSync(logFile, `[${timestamp}] Context compaction triggered\n`);

  console.error('[PreCompact] State preserved before compaction');
  process.exit(0);
}

main();

五、 目錄結構

建議的專案 hooks 結構：

.claude/
├── settings.local.json    # Hooks 配置
├── scripts/
│   ├── hooks/
│   │   ├── session-start.js
│   │   ├── session-end.js
│   │   └── pre-compact.js
│   └── lib/
│       └── utils.js       # 共用工具函式
└── skills/                # Claude Code skills

六、 為什麼 Claude Code 仰賴這些設定？

Claude Code 本質上是一個 「事件驅動的執行環境 (Event-Driven Execution Environment)」。

1. 彌補 LLM 的缺陷：LLM 擅長生成，但不擅長「守紀律」和「記狀態」。Hooks 透過確定性的程式碼（Node.js/Shell）來彌補機率性的 AI 模型。

2. 標準輸入/輸出的管道設計： 注意到腳本中使用了 process.stdin 和 process.stdout 嗎？

    process.stdin.on('data', c => d += c); // 接收 Claude 的數據
    console.log(d); // 必須把數據傳下去，否則流程會斷掉
   

   這設計讓 Hooks 成為類似 Linux Pipe 的過濾器，可以在不打斷 AI 思路的前提下，對資料進行「偷看」、「修改」或「阻擋」。

七、 注意事項

1. Hook 必須輸出 stdin 資料：對於需要處理輸入的 hooks，必須在最後輸出 console.log(d) 將原始資料傳遞下去

2. 使用 stderr 顯示訊息：console.error() 用於顯示給使用者的訊息，console.log() 用於傳遞資料

3. 避免阻塞：Hook 腳本應快速執行，避免耗時操作

4. 錯誤處理：即使發生錯誤也應 process.exit(0)，避免阻斷 Claude Code 流程

5. 路徑處理：使用絕對路徑或相對於專案根目錄的路徑

八、 配置後帶來的行為變革

一旦部署這套 .claude/settings.local.json，你的開發體驗將發生如下質變：

總結

這套配置將 記憶持久化概念 進一步細化為針對 Go 語言特性的自動化工作流。它不僅解決了「失憶」問題，更透過 gofmt 和安全檢查，讓 AI 成為了一個「守紀律」的初級工程師，而不僅僅是一個聊天機器人。

參考資源

• Claude Code Hooks 官方文件

接續上一篇我們對 deltatocumulative Processor 的架構剖析，今天我們要進入「深水區」。

在生產環境中，你可能遇過這種情況：Metrics 莫名其妙開始 Drop，去查 deltatocumulative_datapoints 指標時，看到 error 標籤出現了 delta.ErrOutOfOrder 或 delta.ErrOlderStart。

這不僅僅是報錯，這是 Processor 在告訴你：你的數據流違反了物理定律。本文將從 Stream Identity (身份識別) 的源碼層級出發，徹底拆解這兩個錯誤的根源。

1. 核心根源：Stream Identity (身份識別)

要讀懂錯誤，首先得搞懂 Processor 怎麼判定「這是同一條 Stream」。許多人誤以為只要 Metric Name 一樣就是同一條線，這是大錯特錯。

在源碼中，Stream Identity 是一個 Hash 值，其組成結構非常嚴謹：

Stream Identity = Hash of:
┌─────────────────────────────────────────────────────────────────────┐
│  Metric                                                             │
│  ├── Scope                                                          │
│  │   ├── Resource                                                   │
│  │   │   └── resource.attributes (hash)                             │
│  │   │       (關鍵!: service.name, host.name, k8s.pod.name)          │
│  │   ├── scope.name       (例: "otelcol/prometheus")                 │
│  │   ├── scope.version    (例: "v0.90.0")                           │
│  │   └── scope.attributes (hash)                                    │
│  ├── metric.name          (例: "http_requests_total")               │
│  ├── metric.unit          (例: "ms")                                │
│  ├── metric.type          (例: Sum, Histogram)                      │
│  ├── metric.monotonic     (true/false)                              │
│  └── metric.temporality   (Delta/Cumulative)                        │
└─────────────────────────────────────────────────────────────────────┘
      +
datapoint.attributes (hash)   (例: method="GET", status="200")

實驗室發現：身份判定的黃金法則

我們在單元測試 (TestStreamIdentity) 中驗證了以下關鍵行為，這直接決定了你會不會踩坑：

1. 相同 Attributes = 相同 Stream： 即使 Timestamp 或 Value 不同，只要上述方框內的屬性完全一樣，它們就是同一條 Stream。這就是為什麼多個 Pod 如果沒有帶 pod.name 會導致 Collision（衝突）。
2. Resource 不同 = 不同 Stream： 來自 host-1 和 host-2 的數據，即使 Metric Name 一樣，也是兩條獨立的平行線，互不干擾。
3. Timestamp 與 Value 不影響 Identity：

這解釋了為什麼同一條 Stream 的多個 Datapoints 會被聚合——因為它們共享同一個 Identity。

2. 決策樹：Processor 是怎麼思考的？

Processor 在處理數據時是有優先順序的：先查身世 (Start)，再查時序 (Time)。

graph TD
    A[數據進站 DataPoint] --> B{檢查 1: 出生證明 <br>StartTimestamp}
    B -- New < Stored --> C[💥 ErrOlderStart <br> 丟棄 Drop]
    B -- New >= Stored --> D{檢查 2: 結束時間 <br> Timestamp}
    D -- New <= Stored --> E[💥 ErrOutOfOrder <br> 丟棄 Drop]
    D -- New > Stored --> F[✅ 更新狀態 Update State]

    C -.-> G[懷疑有多個 Process 撞名]
    E -.-> H[單純的網路亂序或重送]

理解了這個流程，我們就能針對兩個錯誤進行深度解析。

3. 第一道防線：ErrOlderStart (身份錯亂)

這是最嚴重、也最常被誤判的錯誤。

• 錯誤代碼：ErrOlderStart
• 直白翻譯：「你明明比我年輕，為什麼出生日期比我還老？」
• 觸發條件：New.StartTimestamp < Stored.StartTimestamp

為什麼會發生？ (The "Highlander" Rule)

這通常不是時間穿越，而是「身份撞車 (Identity Collision)」。Processor 預設一個 Stream（Identity）在同一時間只能有一個來源。

試想這個場景：你有兩個 Pod (A 和 B) 都在跑同一個 Service，但你忘記在 Metric Label 裡加上 pod_name。

1. Pod A (較新)：StartTimestamp = 1000
2. Pod B (較舊)：StartTimestamp = 500

Processor 的視角：

1. 收到 Pod A 數據 → 記住：「這個 Stream 是 1000 出生的」。
2. 收到 Pod B 數據（500 出生）。
3. 檢查：500 < 1000？報錯 ErrOlderStart 並丟棄。

診斷結論： 只要看到這個錯誤，90% 都是 Label 設定問題。你的數據來源不單純（Multiple Processes），有多個實例在搶同一個身份。

4. 第二道防線：ErrOutOfOrder (時光倒流)

如果通過了第一關，數據會來到第二關。

• 錯誤代碼：ErrOutOfOrder
• 直白翻譯：「現在已經 12 點了，你怎麼還在送 11 點的數據？」
• 觸發條件：New.Timestamp <= Stored.Timestamp

為什麼會發生？

這通常是網路或傳輸層的問題，而非配置問題：

1. 網路亂序：數據包迷路了，晚送出的反而早到。
2. 重試風暴 (Retry)：Prometheus Remote Write 因為發送失敗而重送舊數據。
3. 時鐘不同步：不同機器上的時間沒對準。

5. 深度情境分析：那些詭異的組合

這部分是高手進階的關鍵，我們來看兩種特殊組合。

情境 A：有 ErrOlderStart 但「沒有」ErrOutOfOrder

這完全可能發生，而且是診斷「多實例衝突」的鐵證。

假設有兩個進程 A (新, Start=1000) 和 B (舊, Start=500) 交錯發送：

1. 收到 A (Start=1000, Time=1100) → OK
2. 收到 B (Start=500, Time=600) → Fail (因為 500 < 1000，第一關直接擋下)

結論：B 的數據在第一關就被擋下來了，根本沒機會觸發第二關的 ErrOutOfOrder。如果你只看到 ErrOlderStart，請直接檢查你的 Label 設定。

情境 B：有 ErrOutOfOrder 但「沒有」ErrOlderStart

這反而是好消息：這代表你的 Stream Identity 是乾淨的。

這表示沒有多個 Pod 在互搶身份，純粹是單一來源的數據傳輸有點顛簸（網路延遲、Batch Flush 順序或重送）。

結論：

• 資料來自同一個 series。
• StartTimestamp 完全一致（不可能觸發 ErrOlderStart）。
• 問題僅在於傳輸順序。

6. 實戰除錯 SOP

當你在 Grafana 看到 deltatocumulative_datapoints 的 drop rate 飆高時，請依照以下步驟排查：

Step 1: 區分敵我

用這句 PromQL 撈撈看錯誤分佈：

sum by (error) (rate(otelcol_deltatocumulative_datapoints{error!=""}[5m]))

Step 2: 對症下藥

7. 附錄：測試驗證結構

為了確保上述理論正確，我們參考了以下的測試案例結構，測試程式碼：

Part 1: Stream Identity 測試

Part 2: Delta Aggregate 錯誤測試

關鍵測試日誌輸出範例

ErrOlderStart 場景:

Pod B rejected: dropped sample with start_time=...0000005..., 
because series only starts at start_time=...000001... 
consider checking for multiple processes sending the exact same series

ErrOutOfOrder 場景:

Delayed data rejected: out of order: dropped sample from time=...0000011..., 
because series is already at time=...0000012...

總結

ErrOlderStart 和 ErrOutOfOrder 雖然都會導致丟包，但意義截然不同。 ErrOlderStart 是你的設定錯了（撞名），ErrOutOfOrder 是網路環境亂了。

下次看到數據掉點，別急著重啟 Collector，先看看 error label 告訴你什麼故事。

為解決 deltatocumulative Processor 中 ErrOlderStart 錯誤而設計的 k8s_attributes 實踐配置。

核心策略：唯一性 (Uniqueness)

要根除 ErrOlderStart，我們必須確保來自不同 Pod 的數據流擁有不同的 Stream Identity。根據上一篇的分析，Resource Attributes 是 Identity 的重要組成部分。

因此，我們的目標是：強勢注入 k8s.pod.name 和 k8s.pod.uid 到每一筆數據的 Resource 中。

1. Collector 配置範例 (config.yaml)

這份配置適用於以 DaemonSet 方式運行的 OTEL Collector Agent。這是最推薦的部署模式，因為 Agent 可以直接透過來源 IP 關聯到 Pod。

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  # 1. Kubernetes 屬性增強 (關鍵步驟)
  k8sattributes:
    auth_type: "serviceAccount"
    passthrough: false
    filter:
      node_from_env_var: K8S_NODE_NAME # 只處理本節點的 Pod，提升效能

    # 這裡定義要抓取哪些 K8s Metadata 塞進 Resource Attribute
    extract:
      metadata:
        - k8s.pod.name       # <--- 絕對必要：區分不同 Pod
        - k8s.pod.uid        # <--- 強烈建議：區分同名 Pod 重啟前後
        - k8s.deployment.name
        - k8s.namespace.name
        - k8s.node.name

    # 定義如何透過網路連線找到對應的 Pod
    pod_association:
      - sources:
          - from: connection # 透過來源 IP 自動關聯

  # 2. 記憶體限制 (標準配置)
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
    spike_limit_percentage: 15

  # 3. 轉化為 Cumulative (我們的主角)
  deltatocumulative:
    max_streams: 100000 # 記得根據上一篇建議調整
    max_stale: 5m

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      # 注意順序：先加標籤 (k8sattributes)，再做聚合 (deltatocumulative)
      processors: [memory_limiter, k8sattributes, deltatocumulative] 
      exporters: [prometheus]

2. 為什麼這樣配能解決 ErrOlderStart？

讓我們回到源碼層級的 Hash 公式：

修正前 (Collision):

Stream ID = Hash(
  Resource: { service.name="payment" },  <-- 所有 Pod 都一樣
  Metric:   { name="http_requests" }
)
==> 結果：Pod A 和 Pod B 產生相同的 Hash，Processor 以為它們是同一個 Stream，導致時間戳衝突。

修正後 (Unique):

Stream ID (Pod A) = Hash(
  Resource: { service.name="payment", k8s.pod.name="payment-zx9q", k8s.pod.uid="uuid-1" },
  Metric:   { name="http_requests" }
)

Stream ID (Pod B) = Hash(
  Resource: { service.name="payment", k8s.pod.name="payment-ab12", k8s.pod.uid="uuid-2" },
  Metric:   { name="http_requests" }
)
==> 結果：Hash 不同，Processor 視為兩條平行線，ErrOlderStart 消失。

特別說明：為什麼需要 k8s.pod.uid？

雖然 k8s.pod.name 解決了不同 Pod 的衝突，但如果同一個 Pod 被殺掉重建（Recreated），名稱可能不變（例如 StatefulSet 或某些 Deployment 策略）。加上 uid 可以確保即使是「同名的轉世」也會被視為全新的 Stream，徹底杜絕舊數據干擾。

如果你不想賦予 Collector 複雜的 K8s RBAC 權限（讀取 Pods/Nodes），或者你的 Collector 是以 Sidecar 模式運作，「K8s Downward API + Resource Processor」 是完全可以取代 k8s_attributes 的最佳替代方案。

這個組合拳的邏輯是：「與其讓 Collector 去問 API Server 我是誰，不如我在啟動時直接把身分證塞進它的口袋。」

以下是完整的配置範例：

1. K8s YAML 修改 (注入身份)

首先，我們需要利用 K8s 的 Downward API，將 Pod 的 metadata 變成環境變數 (Environment Variables) 注入到 Collector 的容器中。

修改你的 Deployment 或 DaemonSet：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-sidecar
spec:
  template:
    spec:
      containers:
        - name: otel-collector
          image: otel/opentelemetry-collector-contrib:latest
          env:
            # --- 關鍵：利用 Downward API 注入變數 ---
            - name: K8S_POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: K8S_POD_UID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
            - name: K8S_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: K8S_NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            # -------------------------------------
          volumeMounts:
            - mountPath: /etc/otelcol
              name: otel-config

2. OTel Collector Config (讀取身份)

接下來，在 Collector 的配置中，我們不使用 k8s_attributes，而是改用 resource processor (注意：不是 attributes processor)。

為什麼是 resource processor？ 因為上一篇提到，Stream Identity 的判定依賴於 Resource Attributes。普通的 attributes processor 預設是修改 DataPoint 屬性，這對 Stream Identity 的修正無效。我們必須修改 Resource 層級。

processors:
  # 使用 Resource Processor 抓取環境變數
  resource:
    attributes:
      - key: k8s.pod.name
        value: "${env:K8S_POD_NAME}"  # 讀取 K8s 注入的變數
        action: upsert
      - key: k8s.pod.uid
        value: "${env:K8S_POD_UID}"   # 解決 ErrOlderStart 的核心
        action: upsert
      - key: k8s.namespace.name
        value: "${env:K8S_NAMESPACE}"
        action: upsert
      - key: k8s.node.name
        value: "${env:K8S_NODE_NAME}"
        action: upsert

  deltatocumulative:
    max_streams: 100000

service:
  pipelines:
    metrics:
      receivers: [otlp]
      # 順序很重要：先 Resource (貼標籤) -> 再 Delta (計算)
      processors: [resource, deltatocumulative] 
      exporters: [prometheus]

3. 這個方案 vs k8s_attributes 的比較

這兩種方法都能達到讓 Stream Identity 唯一化的目的，消除 ErrOlderStart。

點評：為什麼這也能防 ErrOlderStart？

deltatocumulative 並不在乎標籤是「誰」貼上去的。它只在乎當它計算 Hash 時，Resource 裡有沒有這兩個欄位：

1. k8s.pod.name: 區分了 Pod A 和 Pod B。
2. k8s.pod.uid: 區分了 Pod A (昨天死的) 和 Pod A (今天重啟的)。

透過 Downward API 注入這兩個值，Stream ID 就會變成全宇宙唯一，徹底解決身份衝突與 ErrOlderStart 問題，而且完全不需要跟 K8s API Server 打交道，效能更好、安全性更高。

1. 簡介

deltatocumulativeprocessor 的核心任務是將 Metrics 的 Temporality 從 Delta (增量) 轉換為 Cumulative (累積)。這是一個 Stateful (有狀態) 的組件，意味著它必須在記憶體中維護所有活躍 Time Series 的當前數值。

2. 核心架構與處理流程 (Architecture & Processing Flow)

此 Processor 的設計核心在於「高效的狀態管理」與「嚴格的時間序驗證」。為了在高併發下維持準確性，它採用了細粒度的鎖定策略與強型別的狀態存儲。

2.1 關鍵資料結構 (Key Data Structures)

核心邏輯位於 processor/deltatocumulativeprocessor，主要由以下結構支撐：

A. 唯一識別 identity.Stream

每個 Time Series (時間序列) 由 identity.Stream 唯一識別。這不僅僅是 Metric Name，還包含：

• Metric Signature: Name, Unit, Type, Monotonicity, Temporality.

• Attributes Hash: 所有 DataPoint 屬性 (Labels) 的雜湊值。 這確保了即使是同一個 Metric Name，不同的 Label 組合也會被視為獨立的 Stream。

B. 狀態存儲 state

Processor 內部使用 maps.Parallel (基於 xsync.MapOf) 來存儲狀態。為了效能與型別安全，它針對不同數據類型分開存儲：

• nums: 存儲 NumberDataPoint (Sum/Gauge)

• hist: 存儲 HistogramDataPoint

• expo: 存儲 ExponentialHistogramDataPoint

C. 併發控制 mutex[T]

這是效能關鍵。Processor 不使用全域鎖 (Global Lock) 來保護所有狀態。 相反，每個 Stream 都有自己獨立的 mutex。

• 意義: 不同 Stream 的更新是完全平行的，互不阻塞。只有當多個請求同時更新 同一個 Stream 時，才會發生鎖競爭。

2.2 處理流程 (ConsumeMetrics)

當 Metrics 進入 Processor 時，數據流經以下嚴格步驟：

1. 過濾 (Filter):

   • 檢查 AggregationTemporality。只有 Delta 類型的指標會被處理；Cumulative 指標直接透傳 (Pass-through)。

2. 識別與查找 (Identify & Lookup):

   • 計算 DataPoint 的 identity.Stream。

   • 嘗試從 state 中檢索現有累積值。

   • 容量檢查: 如果是新 Stream 且總數已達 max_streams，則標記 error="limit" 並丟棄該數據點。

3. 聚合運算 (delta.Aggregate):

   • 在 Stream 級別的鎖保護下執行。

   • 邏輯: New_Cumulative = Old_Cumulative + New_Delta。

4. 時間序驗證 (Validation): 在聚合前，必須通過兩項關鍵檢查 (位於 internal/delta/delta.go)：

   • 亂序檢測 (ErrOutOfOrder):

     • 條件: New.Time <= Stored.Time

     • 結果: 丟棄數據。這通常發生在發送端重試或網路亂序時。

   • 重啟檢測 (ErrOlderStart):

     • 條件: New.Start < Stored.Start

     • 結果: 丟棄數據。這代表來源進程可能已重啟，發送了屬於「上一代」的數據，或是時間戳生成有誤。

5. 寫回與標記:

   • 將計算出的 Cumulative 值寫回原始 DataPoint。

   • 將 Temporality 修改為 Cumulative。

   • 更新 stale map 中的最後活躍時間 (Last Seen)。

2.3 垃圾回收機制 (Garbage Collection)

為了釋放不再活躍的 Stream (例如短暫存在的 Pod Metrics)，Processor 運行一個背景 Goroutine：

• 頻率: 每 1 分鐘執行一次。

• 邏輯: 遍歷 stale Map。如果 now - last_seen > max_stale，則從記憶體中刪除該 Stream 的所有狀態。

3. 關鍵配置參數 (Configuration)

processors:
    deltatocumulative:
        # Stream 閒置多久後被視為過期並清除 (預設 5m)
        # 影響: 設置過短會導致頻繁的狀態重置；設置過長會增加記憶體壓力。
        max_stale: 5m

        # 允許追蹤的最大 Stream 數量 (預設為 Max Int)
        # 影響: 這是保護 Collector 不被 High Cardinality 數據撐爆的最後防線。
        # 一旦觸發，超出的 Stream 會被無情丟棄。
        max_streams: 9223372036854775807

4. 監控指標詳解 (Observability)

Processor 透過 internal/telemetry 暴露了自我監控指標 (Self-monitoring Metrics)，這是排查數據丟失問題的首要依據。

4.1 核心指標列表

5. 運營環境常見議題剖析

議題一：狀態丟失與 streams_tracked 的鋸齒狀波動

現象： 監控圖表顯示 streams_tracked 呈現週期性的鋸齒狀下跌，或者劇烈震盪。同時下游看到的數值可能突然歸零或重置。

源碼級原因： 這通常與 GC 機制 (stale check) 有關。

1. 間歇性流量: 如果某個指標每 6 分鐘才送一次，而 max_stale 設為 5 分鐘。Processor 會在第 5 分鐘刪除狀態。第 6 分鐘數據進來時，被視為全新的 Stream，累積值從 0 (或當前 Delta) 開始計算，導致狀態丟失。

2. GC 運作: 背景 Goroutine 每分鐘一次的清理動作，會導致 streams_tracked 出現階梯式下降。

對策：

• 確保 max_stale 顯著大於 metrics 的 scrape interval 或 push interval (建議至少 2-3 倍)。

議題二：Pipeline 順序導致的「數據消失之謎」

現象：batch Processor 報告發送了 2.6k 點，但 exporter 報告只發送了 2.0k 點。中間的 0.6k 憑空消失，且沒有任何 Error Log。

源碼級原因： 這是 deltatocumulative 的 max_streams 限制與 Pipeline 順序共同作用的結果。

// processor.go 片段
if maps.Exceeded(last, loaded) {
    attrs.Set(telemetry.Error("limit"))
    return drop // 直接返回 false，數據點從 Slice 中移除
}

如果 Pipeline 配置為 [batch, deltatocumulative]：

1. Batch: 收到數據，計數器 batch_send_size +2.6k。

2. DeltaToCumulative: 發現 Stream 總數超標，靜默丟棄 0.6k 數據點 (僅增加 deltatocumulative_datapoints{error="limit"})。

3. Exporter: 收到剩餘的 2.0k，計數器 sent_metric_points +2.0k。

對策：

1. 調整順序: 改為 [deltatocumulative, batch]。讓過濾發生在打包之前。

2. 監控 Drop: 設置告警監控 sum(rate(otelcol_deltatocumulative_datapoints{error="limit"}[2m])) > 0。

進階說明

deltatocumulativeprocessor 不會拆分 metric，它只做：

• Delta → Cumulative 的 temporality 轉換
• 累加數值

拆分成 _total, _sum, _bucket 是 Prometheus Exporter 的工作。

流程圖

┌─────────────────────────────────────────────────────────────────────────┐                               
  │                        OTel Collector Pipeline                          │                               
  ├─────────────────────────────────────────────────────────────────────────┤                               
  │                                                                         │                               
  │  Receiver          Processor                    Exporter                │                               
  │  ────────          ─────────                    ────────                │                               
  │                                                                         │                               
  │  ┌──────────┐     ┌─────────────────────┐     ┌───────────────────┐    │                                
  │  │ OTLP     │     │ deltatocumulative   │     │ prometheusremote  │    │                                
  │  │ Receiver │ ──▶ │ processor           │ ──▶ │ write exporter    │    │                                
  │  └──────────┘     └─────────────────────┘     └───────────────────┘    │                                
  │                                                                         │                               
  │  OTel Histogram    OTel Histogram              Prometheus format:       │                               
  │  (Delta)           (Cumulative)                • metric_bucket{le=...}  │                               
  │                    ↑                           • metric_sum             │                               
  │                    只改 temporality            • metric_count           │                               
  │                    不改結構                                              │                              
  │                                                                         │                               
  └─────────────────────────────────────────────────────────────────────────┘

各 Metric 類型在 Prometheus Exporter 的輸出

┌──────────────────────┬──────────────────────────────────────────────────────────┐                       
  │   OTel Metric Type   │                     Prometheus 輸出                      │                       
  ├──────────────────────┼──────────────────────────────────────────────────────────┤                       
  │ Sum (Counter)        │ metric_total (1 個)                                      │                       
  ├──────────────────────┼──────────────────────────────────────────────────────────┤                       
  │ Gauge                │ metric (1 個)                                            │                       
  ├──────────────────────┼──────────────────────────────────────────────────────────┤                       
  │ Histogram            │ metric_bucket{le=...} (N 個) + metric_sum + metric_count │                       
  ├──────────────────────┼──────────────────────────────────────────────────────────┤                       
  │ ExponentialHistogram │ 轉成普通 histogram 後同上                                │                       
  ├──────────────────────┼──────────────────────────────────────────────────────────┤                       
  │ Summary              │ metric{quantile=...} (N 個) + metric_sum + metric_count  │                       
  └──────────────────────┴──────────────────────────────────────────────────────────┘

範例：一個 Histogram DataPoint

  # OTel Histogram (經過 deltatocumulativeprocessor 後)                                                     
  name: http_request_duration_seconds                                                                       
  type: Histogram                                                                                           
  temporality: Cumulative  # ← processor 改了這個                                                           
  datapoint:                                                                                                
    attributes: {method: "GET"}                                                                             
    sum: 150.5                                                                                              
    count: 1000                                                                                             
    bucket_counts: [100, 300, 400, 150, 50]                                                                 
    explicit_bounds: [0.005, 0.01, 0.025, 0.05]

↓ Prometheus Exporter ↓

  # 變成多個 time series                                                                                    
  http_request_duration_seconds_bucket{method="GET", le="0.005"} 100                                        
  http_request_duration_seconds_bucket{method="GET", le="0.01"} 400                                         
  http_request_duration_seconds_bucket{method="GET", le="0.025"} 800                                        
  http_request_duration_seconds_bucket{method="GET", le="0.05"} 950                                         
  http_request_duration_seconds_bucket{method="GET", le="+Inf"} 1000                                        
  http_request_duration_seconds_sum{method="GET"} 150.5                                                     
  http_request_duration_seconds_count{method="GET"} 1000

總結

┌────────────────────────────┬──────────────────────────────────────────────────┐                         
  │            組件            │                       職責                       │                         
  ├────────────────────────────┼──────────────────────────────────────────────────┤                         
  │ deltatocumulativeprocessor │ 只改 temporality，不拆分 metric                  │                         
  ├────────────────────────────┼──────────────────────────────────────────────────┤                         
  │ Prometheus Exporter        │ 將 OTel 格式轉成 Prometheus 格式，拆分 histogram │                         
  └────────────────────────────┴──────────────────────────────────────────────────┘

所以正常 sent_metric_points 應該要更多才是。

議題三：亂序數據 (Out of Order)

現象： 數據偶爾丟失，deltatocumulative_datapoints 出現 error="out_of_order"。

源碼級原因 (internal/delta/delta.go)：

case dp.Timestamp() <= state.Timestamp():
    return ErrOutOfOrder{...}

Processor 強制要求數據的時間戳嚴格遞增。如果發送端 (如 Prometheus Remote Write 或某些 SDK) 因重試邏輯發送了重複或舊的時間戳，Processor 會為了保護累積值的單調性而拒絕該數據。

對策： 檢查發送端的 Retry 策略或時鐘同步狀態。

6. PoC Lab 環境 - 本地重現驗證

為了驗證上述理論，我們建立了一個可在本地運行的 Docker Compose PoC 環境。

6.1 環境架構

┌─────────────────┐     ┌─────────────────────────────────────┐     ┌────────────┐
│  telemetrygen   │────▶│         OTel Collector              │────▶│ Prometheus │
│  (60 instances) │     │  ┌─────────────────────────────┐    │     │  :9090     │
│  app-01 ~ 60    │     │  │ Pipeline:                   │    │     └────────────┘
└─────────────────┘     │  │ receiver → cumulativetodelta│    │
                        │  │          → batch            │    │
                        │  │          → deltatocumulative│    │
                        │  │          → exporter         │    │
                        │  │                             │    │
                        │  │ max_streams: 50 (< 60)      │    │
                        │  └─────────────────────────────┘    │
                        └─────────────────────────────────────┘

設計理念：

• 60 個 telemetrygen 實例，每個發送不同的 service.name (app-01 ~ app-60)

• max_streams 設為 50，刻意製造 Stream 超限

• Pipeline 順序為 [cumulativetodelta, batch, deltatocumulative]，重現「先 batch 後過濾」的問題

6.2 檔案結構

Soruce Code

poc-lab/
├── docker-compose.yaml   # Docker Compose 配置
├── otel-config.yaml      # OTel Collector 配置
└── prometheus.yaml       # Prometheus scrape 配置

6.3 配置檔案

otel-config.yaml

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

processors:
  # 將 telemetrygen 產生的 Cumulative 轉成 Delta
  cumulativetodelta:

  batch:
    send_batch_size: 100
    timeout: 1s

  deltatocumulative:
    max_stale: 1m
    # 【關鍵設定】設定極低的上限，強迫發生 Drop
    max_streams: 50

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
    namespace: "poc_app"

  debug:
    verbosity: normal

service:
  telemetry:
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: "0.0.0.0"
                port: 8888

  pipelines:
    metrics:
      receivers: [otlp]
      # 【關鍵錯誤順序】重現問題
      processors: [cumulativetodelta, batch, deltatocumulative]
      exporters: [prometheus, debug]

prometheus.yaml

global:
  scrape_interval: 5s
  evaluation_interval: 5s

scrape_configs:
  # Job 1: 監控 Collector 本身
  - job_name: 'otel-collector-internal'
    static_configs:
      - targets: ['otel-collector:8888']

  # Job 2: 監控實際輸出的數據
  - job_name: 'app-metrics'
    static_configs:
      - targets: ['otel-collector:8889']

docker-compose.yaml (精簡版)

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.142.0
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-config.yaml:/etc/otel-collector-config.yaml:ro
    ports:
      - "4317:4317"
      - "8888:8888"   # Collector Internal Metrics
      - "8889:8889"   # Prometheus Exporter
    networks:
      - otel-network

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yaml:/etc/prometheus/prometheus.yml:ro
    ports:
      - "9090:9090"
    depends_on:
      - otel-collector
    networks:
      - otel-network

  # 使用 YAML anchor 定義 60 個 telemetrygen 實例
  telemetrygen-01: &telemetrygen-base
    image: ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest
    command: ["metrics", "--otlp-insecure", "--otlp-endpoint=otel-collector:4317",
              "--rate=5", "--duration=1000h", "--metric-type=Sum", "--service=app-01"]
    depends_on: [otel-collector]
    networks: [otel-network]

  telemetrygen-02: { <<: *telemetrygen-base, command: [..., "--service=app-02"] }
  # ... (app-03 ~ app-60)

networks:
  otel-network:
    driver: bridge

6.4 運行與驗證

步驟 1: 啟動環境

cd poc-lab
docker compose up -d

步驟 2: 等待數據累積 (約 30-60 秒)

docker compose ps  # 確認所有容器運行中

步驟 3: 驗證查詢

打開 Prometheus UI (http://localhost:9090) 或使用 curl：

查詢 1: Streams 追蹤數量 (應該達到上限 50)

otelcol_deltatocumulative_streams_tracked

查詢 2: 數據點處理結果 (按 error 分類)

otelcol_deltatocumulative_datapoints_total

查詢 3: 比較 Batch vs Exporter

# Batch 處理量
otelcol_processor_batch_batch_send_size_sum

# Exporter 發送量
otelcol_exporter_sent_metric_points_total

6.5 驗證結果 - 問題重現 (錯誤順序)

使用錯誤的 Pipeline 順序 [cumulativetodelta, batch, deltatocumulative] 運行後：

數據點處理詳情：

關鍵發現：

• 發送端: 60 個 telemetrygen 實例

• 限制: max_streams = 50

• 被完全丟棄的實例: 10 個 (60 - 50)

• Batch (13,000) ≠ Exporter (11,000)：差異 2,000 個數據點「憑空消失」

• 丟棄僅標記 error="limit"，無 Error Log，難以察覺

6.6 修正驗證 - 正確順序

修改 otel-config.yaml 中的 processors 順序：

# 修正前 (問題配置)
processors: [cumulativetodelta, batch, deltatocumulative]

# 修正後 (正確配置)
processors: [cumulativetodelta, deltatocumulative, batch]

修正後驗證結果：

數據點處理詳情：

6.7 修正前後對比

關鍵結論：

修正前: Batch (13,000) ≠ Exporter (11,000)  ← 數據「消失」，難以排查
修正後: Batch (14,950) = Exporter (14,950)  ← 指標一致，問題可追溯

1. Pipeline 順序修正有效 - Batch 和 Exporter 的數值現在完全一致

2. 丟棄仍然發生 (error="limit")，但這是預期行為，因為來源數 (60) > max_streams (50)

3. 監控指標正確反映實際狀態 - 運維人員可直接從 error="limit" 指標看到丟棄量

6.8 清理環境

docker compose down

7. PHP 與 Delta To Cumulative Processor 的關聯

7.1 為什麼是 PHP？ (The "Share-Nothing" Architecture)

大多數的應用程式（如 Java, Go, Python, Node.js）通常是以常駐進程 (Long-running process) 的方式運行。它們在記憶體中有一個全域的計數器，可以一直累加數值：

• 00:01: 累計 10 次

• 00:02: 累計 15 次 (累加了 5 次)

• 00:03: 累計 20 次 (又累加了 5 次)

這就是 Cumulative (累積) 模式，也是 Prometheus 等後端系統最喜歡的格式。

但是，PHP 通常運行在 PHP-FPM 或 CGI 模式下。其生命週期是「一個請求一個進程」 (Per-request process)：

1. 收到請求 -> 啟動 (或重用) PHP worker。
2. 執行腳本 -> 處理指標 (Metrics)。

3. 請求結束 -> 記憶體釋放/重置。

   因為 PHP 進程之間通常不共享記憶體 (Share-nothing)，要維護一個「自從伺服器啟動以來的所有請求總數」是非常困難且昂貴的（需要依賴外部 Redis 或 Shared Memory）。

   因此，PHP 最自然的做法是只回報「這一次請求發生了什麼」：

4. 請求 A: 我處理了 1 個 DB 查詢 (Delta) -> 結束

5. 請求 B: 我處理了 1 個 DB 查詢 (Delta) -> 結束

   這就是 Delta (增量) 模式。

7.2 Delta to Cumulative Processor 的角色

當您的後端資料庫（如 Prometheus）只接受 Cumulative 資料，但您的應用程式（如 PHP 或 Serverless Functions）只能提供 Delta 資料時，就會發生格式不相容。

這時候就需要 deltatocumulative processor 擔任「狀態管理者」 (Stateful Intermediary) 的角色：

1. 接收 (Receive): 它接收來自 PHP 的無數個小 Delta (例如：+1, +1, +1)。
2. 記憶 (Remember): 它在 Collector 的記憶體中維護一個對應的 Stream，並幫忙做加法運算 (State Management)。
3. 轉換 (Convert): 它算出累積值 (例如：目前總共是 3)，並將其轉換為 Cumulative 格式。
4. 輸出 (Export): 發送給 Prometheus。

雖然 Serverless (如 AWS Lambda) 或 CLI 工具也有類似需求，但 PHP的廣泛使用以及其標準的運行模式，使其成為這個 Processor 最常見的使用案例。

8. 結論與最佳實踐

1. Pipeline 順序: 將 deltatocumulative 放在 batch 之前，讓過濾發生在打包前

2. 監控告警: 設置對 error="limit", error="out_of_order" 的告警

3. 容量規劃: 根據預期的 Stream 數量合理設置 max_streams

4. Stale 設定: max_stale 應大於最大的 push/scrape interval (建議 2-3 倍)

在開發高併發應用程式（如股票分析機器人）時，我們常面臨 「驚群效應」(Thundering Herd)：當快取失效或系統剛啟動時，大量請求同時湧入，導致昂貴的 API（如 Gemini）成本爆炸或資料庫崩潰。

singleflight 是 Go 官方擴充套件（golang.org/x/sync/singleflight）中的神兵利器，確保當多個請求同時要求同一個結果時，實際的運算只會執行一次。

1. 為什麼需要 Singleflight？

想像 1,000 個用戶同時查詢「台積電 (2330)」的分析報告：

• 無控制：1,000 次 Gemini API 呼叫（帳單飆升）、1,000 次資料庫連線（系統卡死）。
• 有 Singleflight：1 次 API 呼叫，其餘 999 人在記憶體中等待結果，隨後共享同一份數據。

2. 深入核心：Singleflight 原始碼拆解

理解 singleflight 的底層源碼結構，能幫助我們更精準地掌握並發控制。

核心結構定義

1. Group: 代表一個命名空間，管理所有正在進行中的任務。
2. m map[string]*call: 記錄目前有哪些 Key 正在「飛行中」(In-flight)。
3. mu sync.Mutex: 保護 Map，防止高併發下的 Race Condition。

2. call: 代表一個正在執行的具體任務。
3. wg sync.WaitGroup: 最關鍵的同步元件。用來讓「後到」的請求等待「先到」的請求完成。
4. val / err: 存放執行後的結果與錯誤。

運作流程圖解：Do(key, fn)

sequenceDiagram
    autonumber
    participant G as Group (櫃台)
    participant C as Call (任務)
    participant FN as 執行函數 (fn)

    Note over G: 1. 鎖定 Map 並檢查 Key
    alt 情境 A：已經有人在做了 (Duplicate Call)
        G->>C: 發現 Key 存在
        G->>C: c.dups++ (記錄重複)
        G->>G: Unlock Map
        G->>C: c.wg.Wait() (原地卡住等待)
        C-->>G: 喚醒並回傳結果
    else 情境 B：我是第一個做的 (Original Call)
        G->>C: 建立 new(call)
        G->>C: c.wg.Add(1) (任務開始標記)
        G->>G: 將 call 掛入 Map
        G->>G: Unlock Map
        G->>FN: g.doCall(c, key, fn)
        FN-->>C: 填入結果與錯誤
        Note over G: 2. 清理與廣播
        G->>G: 鎖定 Map 並 delete(key)
        G->>C: c.wg.Done() (大喊：好囉！)
    end

3. 核心實作範例：L1 快取 + Singleflight

我們在 AnalysisService 中構建兩層防護：記憶體快取 (L1) 與 Singleflight。

package analyzer

import (
    "context"
    "sync"

    "golang.org/x/sync/singleflight" 
    "github.com/nathan/stock_bot/internal/storage"
)

type AnalysisService struct {
    genai      *GenAIClient
    d1Client   *storage.D1Client
    stockCache map[string]*StockAnalysisResult
    mu         sync.RWMutex
    sf         singleflight.Group
}

func (s *AnalysisService) analyzeStock(ctx context.Context, code, name string) (*StockAnalysisResult, error) {
    // 1. 第一層防護：檢查記憶體快取 (L1 Cache)
    s.mu.RLock()
    if result, ok := s.stockCache[code]; ok {
        s.mu.RUnlock()
        return result, nil
    }
    s.mu.RUnlock()

    // 2. 第二層防護：Singleflight (請求合併)
    key := "stock:" + code
    v, err, _ := s.sf.Do(key, func() (interface{}, error) {
        // 3. 執行昂貴的邏輯 (DB + Gemini API)
        result, err := s.doAnalyzeStock(ctx, code, name) 
        if err != nil {
            return nil, err
        }

        // 4. 寫入快取 (務必在 singleflight 內部完成，防止下一波瞬間擊穿)
        s.mu.Lock()
        s.stockCache[code] = result
        s.mu.Unlock()

        return result, nil
    })

    if err != nil {
        return nil, err
    }
    return v.(*StockAnalysisResult), nil
}

4. 進階實戰：處理「巢狀 Context」與非同步操作

在 doAnalyzeStock 內部，如果我們有其他的非同步操作（例如同時查多個 API），我們必須正確傳遞並檢查 ctx.Err()。這樣做是為了確保：如果外部請求（領頭者）超時了，後續的耗時運算能立即停止，釋放資源。

func (s *AnalysisService) doAnalyzeStock(ctx context.Context, code, name string) (*StockAnalysisResult, error) {
    // 建立一個子 Context 用於內部的多個非同步任務
    g, ctx := errgroup.WithContext(ctx)

    var dbData string
    var aiResult string

    // 任務 1：查資料庫
    g.Go(func() error {
        // 隨時檢查 Context 是否已取消
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            // 模擬資料庫查詢
            dbData = "Historical Data"
            return nil
        }
    })

    // 任務 2：呼叫 Gemini API
    g.Go(func() error {
        // 將 ctx 傳入 API 客戶端，讓它能跟隨整體的超時控制
        res, err := s.genai.Generate(ctx, "Analyze this: "+code)
        if err != nil {
            return err
        }
        aiResult = res
        return nil
    })

    // 等待所有任務完成或其中一個出錯
    if err := g.Wait(); err != nil {
        return nil, err
    }

    return &StockAnalysisResult{Data: dbData, Analysis: aiResult}, nil
}

5. 性能數據對比 (100 個併發請求)

6. 監控與量化：加入 OpenTelemetry 追蹤

為了知道 Singleflight 幫我們省了多少錢，我們可以追蹤 shared 這個回傳值。shared 為 true 表示該請求是「搭便車」成功的。

func (s *AnalysisService) analyzeStockWithMetrics(ctx context.Context, code string) (*StockAnalysisResult, error) {
    key := "stock:" + code
    v, err, shared := s.sf.Do(key, func() (interface{}, error) {
        return s.doAnalyzeStock(ctx, code, "Name")
    })

    // 紀錄監控指標：分辨是「原始呼叫」還是「共享結果」
    status := "original"
    if shared {
        status = "shared"
    }

    s.sfCounter.Add(ctx, 1, metric.WithAttributes(
        attribute.String("stock_code", code),
        attribute.String("type", status),
    ))

    if err != nil {
        return nil, err
    }
    return v.(*StockAnalysisResult), nil
}

儀表板觀測指標 (Prometheus / Grafana) 透過這組指標，你可以在 Grafana 畫出以下圖表：

1. Request Stacked Area Chart:

   • type="original": 實際產生的 API 呼叫次數（你的成本預算）。

   • type="shared": 被合併的請求次數（你省下的錢）。

2. Saving Ratio (節省率):

   • 公式：sum(rate(shared)) / sum(rate(total))。

7. 總結

singleflight 的機制就像是：

1. 進門先看櫃台 (Map)：有沒有掛牌子 (Key)？
2. 有牌子：代表有人處理了，我就站在旁邊等 (Wait)，等他處理好直接拿結果。
3. 沒牌子：我掛上牌子 (Add Map)，開始處理 (Do Fn)。

開發者筆記：

• 快取寫入：務必在 sf.Do 的 func 內部寫入快取。
• Context 意識：傳遞並檢查 ctx.Err() 是確保系統在高壓下不會資源洩漏的關鍵。
• 可觀測性：沒有監控，優化就只是傳說。加入 OTel 讓數據說話。

「多人請求，一人做事，結果共享」 —— 這不僅是效能優化，更是對昂貴資源與系統穩定性的極致追求。

以下是影片內容的完整解釋與重點摘要：

1. 2025 年 Log 的角色與重要性

• Log 是否仍有一席之地？ [05:30]

  • 來賓們討論在現代可觀測性Observability）中 Log 的地位。Ed認為 Log 是「唯一真實的可觀測性訊號」，因為它是最容易獲取的（從 Hello World 就開始用），且無法被完全取代（如 process 的 stdout/stderr）。

  • Zero Duration Spans (零持續時間的 Span) [08:33]：Jack 提到一種反模式，即人們將 Log 記錄為「持續時間為零」的 Span。他認為如果不具備層級結構且沒有持續時間，那它本質上就是 Log，不應硬套用 Span 的概念。

2. OpenTelemetry 為何需要 Logng API？ [17:23]

• 儘管已有很多成熟的 Log [框架（如 Log4j,Python logging），OpenTelemetry 仍推出了自己的 Logging API。

• 互操作性（Interoperability）：最初目的是為了橋接現有的 Log 系統（Log Bridge API）。

• 統一性：讓使用者能用同一套 API 處理 Metrics、Traces 和 Logs。

• 強型別與結構化：OpenTelemetry 希望推動 Log 往「結構化（Structured）」方向發展，包含明確的事件名稱（Event Name）與屬性（Attributes），而非僅是純文字字串。

3. 結構化 Log vs. 人類可讀性

• 兩難：純文字 Log 對人類閱讀除錯很友善，但對機器分析不便；結構化 Log（如 JSON）對機器友善，但人類難以直接閱讀。

• 建議：Log 應該是結構化的，但保留一個人類可讀的訊息欄位（或將其轉化為 Event Name）。[34:51]

[4. Log 的最佳實踐建議

來賓們分享了具體的實戰建議：

• 撰寫有意義的錯誤訊息[36:52]

  • Ed強調：當你寫 error log 時，請告訴讀者（通常是未來的你）該怎麼做。不要只寫「資料庫連線失敗」，要寫「資料庫連線失敗，正在重試」或「請檢查某設定」。

• 直接傳送 vs檔案抓取**[42:50]

  • Jack 建議應用程式應直接透過網路（OTLP協定）發送Log後端，而不是寫入檔案再由 Agent 去抓取（Tail）。這樣能更無縫地保留 Context（如 Trace ID）。

  • Ed 補充建議：在應用程式與後端之間最好有一個本地的Collector**。這樣當需要過濾大量垃圾 Log 時，可以在 Coller 端調整設定，而無需重新部署應用程式。

• 不要濫用 Log

  • Metrics vs. Logs[47:28]：不要用 Lo 來做高基數（High Cardinality）的計數統計，那應該用 Metrics。

  • Traces vs. Logs [48:29]：如果你想知道「請求花費了多少時間」或「請求的路徑」，請使用 Traces，不要用 Log 印出「開始]請求」、「結束請求」。

• [Log 等級（Severity[01:03:36]：絕對不要記錄沒有等級的 Log。至少要區分 INFO、ERROR、DEBUG，這對過濾和警報至關重要。

• 安全性 [01:01:53]：小心不要在 Log 中記錄 PII（個人識別資訊）或 Secrets，也不要記錄完整的 HTTP Headers。

5. 快速問答環節（Good or Bad?）

影片末尾[[57:12]] 進行了一個快問快答遊戲：

• 格式化 Log 字串？** 不建議（應使用參數化/結構化）。

• 將所有 Excetion 都記為 Error？ 同意。

• 記錄 Request/Response Body？ 通常不建議（成本太高且易洩漏個資，除非有極強烈的除錯需求。

• 記錄所有細節？ 不建議，每一個 bytes都要錢，請有意識地選擇要記錄的內容（Be intention）。

在 Cloud Native 與微服務架構盛行的 2025 年，Log（日誌）這個最古老的除錯工具，是否已經過時？或者它只是需要一點「現代化」的改造？

最近觀看了 Grafana Labs 與 OpenTelemetry (OTel) 技術委員會成員的一場深度對談（Community Call），主題聚焦於 Logging Best Practices。這場討論並非單純的操作教學，而是對於 Log 在現代可觀測性（Observability）中角色的重新定義。

以下整理了影片中的核心觀點，希望能幫助開發者與維運人員打破舊有的 Log 思維，建立更具「意圖性」的可觀測性策略。

1. 觀念翻轉：Log 的定位與「反模式」

在 Tracing（追蹤）技術日益普及的今天，很多人會問：「我還需要 Log 嗎？」答案是肯定的，而且 Log 是不可取代的「唯一真實訊號」。

然而，為了追求新技術，社群中出現了一種名為 Zero Duration Spans（零持續時間 Span） 的怪現象。

什麼是 Zero Duration Span？

開發者為了利用 Tracing 工具的視覺化，將原本該是 Log 的單點事件，包裝成「開始時間等於結束時間」的 Span。

OpenTelemetry 技術委員會成員 Jack Berg 對此提出了精闢的見解：

"If it walks like a log, talks like a log, it's a log." （如果它走起來像 Log，叫起來像 Log，那它就是 Log，別裝了。）

判斷標準

• Span (Traces)：具有層級結構（Hierarchy）與持續時間（Duration）。用來回答「這個請求花了多久？路徑為何？」。

• Log：發生在特定時間點的事件。用來回答「當下發生了什麼事？」。

最佳實踐：誠實面對資料的本質，不要硬套用 Span 的概念。Log 依然是一等公民。

2. 結構化革命：從「給人看」到「機器優先」

傳統的 Log 是一行行給人類閱讀的字串（Text-based），但在微服務與海量資料的場景下，這種模式已經行不通。OpenTelemetry 正推動 Log 往 結構化（Structured） 與 強型別（Strongly typed） 發展。

為什麼需要結構化？

• 查詢效率：試想在幾億行 Log 中 grep 字串，與在資料庫中查詢 attributes.http_status_code == 500 的區別。

• 關聯性：OTel 的目標是讓 Logs、Traces、Metrics 使用統一的語意規範（Semantic Conventions）。

兩難與解法

結構化 Log（如 JSON）對機器友善，但對人類閱讀不便。

• 建議做法：保留 Log 的結構化欄位（Attributes）供機器分析，但同時保留一個 message 欄位或是將其轉化為易讀的 Event Name 供人類快速瀏覽。

3. 架構演進：File Tail vs. OTLP Direct

你的 Log 是怎麼送到後端的？這涉及到架構的解耦。

傳統模式：File Scraping

應用程式將 Log 寫入磁碟檔案 -> Agent (如 Promtail) 去抓取 (Tail) -> 傳送後端。

• 缺點：容易丟失 Context（如 Trace ID），且依賴硬碟 I/O。

現代模式：OTLP Direct

應用程式透過網路協定（OTLP）直接將 Log 發送出去。

• 優點：原生支援結構化，保留完整 Context，無需檔案權限。

🔥 進階技巧：Local Collector Pattern

Grafana Loki 的維護者 Ed 提出了一個極佳的架構建議：在應用程式旁跑一個 Local Collector（作為 Sidecar 或 DaemonSet）。

好處：當你需要將 Log Level 從 INFO 改為 DEBUG 時，你只需要調整 Collector 的過濾規則，完全不需要重新部署應用程式。這實現了極致的維運解耦。

4. 實戰指南：如何寫出「有靈魂」的 Log？

當開發者敲下 logger.error(...) 時，請記住以下原則：

✅ 1. 寫給未來的自己 (Actionable Errors)

不要只寫「連線失敗」。錯誤訊息必須包含「接下來該做什麼」。

• ❌ Bad: Connection failed.

• ✅ Good: Connection to DB failed, retrying in 5s. Please check network config. 精神：同理心。 給半夜修 Bug 的人一條明路。

✅ 2. Context is King

沒有 Trace ID 或 User ID 的 Log，在高併發環境下幾乎是雜訊。務必確保 Log 包含足夠的上下文屬性。

⛔ 3. 避免高成本操作

• 不要 Log Request Body：除非在開發環境，否則這會導致儲存成本爆炸，且有洩漏 PII（個資）與 Secrets（金鑰）的風險。

• 不要用 Log 做統計：如果你想知道「API 被呼叫幾次」，請用 Metrics，不要用 Log。

總結：Be Intentional (保持意圖)

整場討論可以用這兩個字總結："Be Intentional"。

Log 不再是廉價的 printf。每一行 Log 都有儲存成本、傳輸成本與認知成本。

• 這條 Log 是給誰看的？（人還是機器？）

• 它的目的是什麼？（除錯、稽核還是統計？）

• 它包含了足夠的資訊嗎？

在 2025 年，寫好 Log 不僅是技術能力的展現，更是一種對系統架構與團隊協作的深層思考。

參考來源：Grafana & OpenTelemetry Community Call - Logging Best Practices

原文 :12 OpenTelemetry Dashboards That Surface Real Bottlenecks https://medium.com/@sparknp1/12-opentelemetry-dashboards-that-surface-real-bottlenecks-f81d36e043a4

「正確的儀表板感覺就像作弊程式碼」。遙測的目標並非擁有更多數據，而是要讓少數視圖清晰易讀，使你的下一步行動顯而易見。實用、簡潔的 OTel 視圖能將雜亂的噪音轉化為具體的解決方案。

前言

你把一切都可監測了。現在，圖表牆正在回望。哪些實際上可以幫助您解決結帳速度慢、API 不穩定或神秘的 p99 問題？

說實話：正確的儀表板感覺就像作弊程式碼。

以下是我使用（並調整過）的 12 個 OpenTelemetry 儀表板，它們一致地揭示了實際瓶頸和下一步行動。

┌─────────────────────────────────────────────────────────┐
│  OpenTelemetry 監控全景                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │   應用    │  │   服務    │  │  微服務   │              │
│  └─────┬────┘  └─────┬────┘  └─────┬────┘              │
│        │             │             │                    │
│        └─────────────┴─────────────┘                    │
│                      │                                  │
│                      ▼                                  │
│            ┌─────────────────┐                          │
│            │  OTel Collector │                          │
│            └────────┬────────┘                          │
│                     │                                   │
│         ┌───────────┼───────────┐                       │
│         ▼           ▼           ▼                       │
│    ┌────────┐  ┌───────┐  ┌────────┐                   │
│    │ Metrics│  │Traces │  │  Logs  │                   │
│    └────────┘  └───────┘  └────────┘                   │
│         │           │           │                       │
│         └───────────┴───────────┘                       │
│                     │                                   │
│                     ▼                                   │
│         📊 12 個關鍵儀表板                                │
└─────────────────────────────────────────────────────────┘

🎯 核心監控儀表板

1. RED for Every Critical Endpoint（每個關鍵端點的 RED 指標）

顯示內容：每條高價值路線的 Rate（速率）、Errors（錯誤）、Duration（持續時間）

為什麼有效：RED 三元組是快速故障檢測器和深入分析的指南針

如何構建：使用由 http.route 鍵入的跨度指標（持續時間直方圖 + 錯誤計數）

# 如何建立：使用由 http.route 鍵入的 span metrics
# OpenTelemetry Collector (span metrics)
processors:
  spanmetrics:
    metrics_exporter: prometheus
    dimensions:
      - name: http.route
      - name: http.method
    histogram:
      unit: "ms"
      explicit_buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500]

service:
  pipelines:
    traces:
      processors: [spanmetrics]

┌────────────────────── RED 儀表板 ──────────────────────┐
│                                                        │
│  📈 Rate (請求速率)                                     │
│  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬                           │
│  /checkout    ████████████████░░  1,250 req/s         │
│  /login       ████████░░░░░░░░░░    450 req/s         │
│  /quote       ██████████████████  1,800 req/s         │
│                                                        │
│  ❌ Errors (錯誤率)                                     │
│  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬                           │
│  /checkout    ██░░░░░░░░░░░░░░░░    1.2%              │
│  /login       ░░░░░░░░░░░░░░░░░░    0.1%              │
│  /quote       ████░░░░░░░░░░░░░░    2.8% ⚠️           │
│                                                        │
│  ⏱️  Duration (回應時間)                                │
│  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬                           │
│  /checkout    p50: 120ms  p95: 450ms  p99: 890ms     │
│  /login       p50:  45ms  p95: 125ms  p99: 280ms     │
│  /quote       p50: 180ms  p95: 620ms  p99: 1.2s 🔥   │
└────────────────────────────────────────────────────────┘

要建立每個關鍵端點的 RED 指標，您需要使用 OpenTelemetry Collector 中的 spanmetrics 處理器。這是將追蹤 (Traces) 數據轉換為指標 (Metrics) 的核心步驟。

具體的 Collector 配置示例如下，它使用 http.route 和 http.method 作為維度鍵入跨度指標：

# 如何建立：使用由 http.route 鍵入的 span metrics [6]
processors:
  spanmetrics:
    metrics_exporter: prometheus
    dimensions:
      - name: http.route
      - name: http.method
    histogram:
      unit: "ms"
      # 設定明確的持續時間分桶，用於精確計算延遲百分位數（例如 p95, p99）
      explicit_buckets: [9-11] [5, 6]

service:
  pipelines:
    traces:
      processors: [spanmetrics] [6, 12]

💡 解讀技巧：p95 在流量沒有增長的情況下突然上升通常意味著飽和或下游依賴性問題。

2. Tail Latency Anatomy（尾部延遲剖析）

顯示內容：隨時間變化的 p50/p95/p99，加上差異面板 (p99–p50)

┌──────────────── 尾部延遲追蹤 ────────────────┐
│                                              │
│  延遲分佈 (ms)                                │
│  2000│                              ╱╲       │
│      │                            ╱    ╲     │
│  1500│                          ╱        ╲   │ p99
│      │                        ╱            ╲ │
│  1000│              ╱╲      ╱                │
│      │            ╱    ╲  ╱                  │ p95
│   500│      ╱╲  ╱        ╲                   │
│      │    ╱    ╲                             │ p50
│      │  ╱                                    │
│     0└──┴───┴───┴───┴───┴───┴───┴───┴───┴─  │
│       8:00 9:00 10:00 11:00 12:00 13:00     │
│                                              │
│  📊 差異分析 (p99 - p50)                      │
│  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬                  │
│  正常時段:  ~200ms                           │
│  高峰時段:  ~1,100ms ⚠️  (5.5x 差距)         │
│                                              │
│  💡 建議: 檢查 11:00 時段的依賴服務             │
└──────────────────────────────────────────────┘

為什麼有效：

• p50 代表用戶幸福感

• p99 代表執行壓力

• 差距顯示長尾疼痛

🎯 專業提示：從追蹤中添加示例，直接從尖峰跳到有問題的跨度。

3. Saturation Heatmap by Resource（按資源劃分的飽和度熱圖）

顯示內容：按服務劃分的 CPU、內存、I/O 和線程池利用率，按剩餘空間排序

┌─────────────── 資源飽和度熱圖 ───────────────┐
│                                              │
│  服務名稱      CPU    Memory   I/O   Thread  │
│  ────────────────────────────────────────   │
│  api-gateway   ██░░   ███░░   █░░░   ████   │
│                52%     68%     18%     89% 🔥│
│                                              │
│  auth-service  ████   ████░   ██░░   ███░   │
│                89% 🔥  92% 🔥  42%     72%   │
│                                              │
│  payment-svc   █░░░   ██░░░   ████   ██░░   │
│                23%     48%     91% 🔥  45%   │
│                                              │
│  user-service  ██░░   ███░░   █░░░   ███░   │
│                55%     71%     25%     68%   │
│                                              │
│  ▓▓▓▓ > 80% (危險)  ███ 60-80%  ██ 40-60%   │
│  █ < 40% (健康)                              │
│                                              │
│  ⚠️  警報: auth-service CPU & Memory 接近飽和 │
│  💡 建議: 擴展 payment-svc I/O 容量           │
└──────────────────────────────────────────────┘

為什麼有效：如果當淨空下降到低於 ~20% 時 p95 上升，那麼您就發現了資源瓶頸

建議添加：

• 限制標誌（CPU 限制計數、容器 OOM 終止）

• 每個服務的隊列積壓

📊 依賴與性能追蹤

4. Queue Health: Depth × Age × Drains（隊列健康度）

當服務在高負載下，隊列成為了減震器，但同時也可能是問題的「犯罪現場」。在監控隊列健康度（深度、年齡、消耗率）時，應遵循以下分類規則：

• 分類規則：如果隊列深度 (Depth) 增加且最早的消息年齡 (Age) 攀升，而消費者消耗率 (Drains) 保持平坦，這表示瓶頸在於消費者數量不足，或者下游服務運行緩慢，應優先增加消費者或解決下游緩慢問題。

顯示內容：消息深度、最早的消息年齡以及每個隊列/主題的消費者消耗率

┌────────────── 隊列健康監控 ──────────────┐
│                                          │
│  📬 order-queue                          │
│  ┌────────────────────────────────────┐ │
│  │ 深度: 1,240 msgs  ████████░░░       │ │
│  │ 年齡: 8.5 min     ████████████░ 🔥  │ │
│  │ 消耗: 145 msg/s   ██████░░░░░░      │ │
│  └────────────────────────────────────┘ │
│                                          │
│  📬 notification-queue                   │
│  ┌────────────────────────────────────┐ │
│  │ 深度: 45 msgs     █░░░░░░░░░        │ │
│  │ 年齡: 1.2 min     ██░░░░░░░░        │ │
│  │ 消耗: 380 msg/s   ████████████      │ │
│  └────────────────────────────────────┘ │
│                                          │
│  📬 payment-queue                        │
│  ┌────────────────────────────────────┐ │
│  │ 深度: 3,890 msgs  ████████████░ ⚠️  │ │
│  │ 年齡: 15.3 min    ████████████████ 🔥│ │
│  │ 消耗: 62 msg/s    ███░░░░░░░░░      │ │
│  └────────────────────────────────────┘ │
│                                          │
│  ⚠️  payment-queue 積壓嚴重              │
│  💡 建議: 增加消費者或檢查下游服務         │
└──────────────────────────────────────────┘

為什麼有效：在負載情況下，隊列會成為您的減震器——或者成為您的犯罪現場

⚠️ 分類規則：如果深度增加且年齡增加，而排水管保持平坦 → 首先添加消費者或解決下游緩慢問題

5. Dependency Waterfall（依賴瀑布）

顯示內容：按 peer.service/db.system 聚合的跨度指標及對總延遲的貢獻

┌──────────────── 依賴瀑布分析 ────────────────┐
│                                              │
│  請求: GET /checkout (總時長: 1,240ms)        │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                              │
│  ├─ API Gateway           45ms   ██         │
│  │                                          │
│  ├─ Auth Service          120ms  █████      │
│  │                                          │
│  ├─ User Service           85ms  ███        │
│  │                                          │
│  ├─ Inventory Check       180ms  ███████    │
│  │                                          │
│  ├─ Tax Calculator        680ms  ████████████████████ 🔥
│  │   (第三方 API)                            │
│  │                                          │
│  ├─ Payment Gateway       95ms   ████       │
│  │                                          │
│  └─ Order Creation        35ms   █          │
│                                              │
│  📊 延遲貢獻分析:                             │
│  ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬                     │
│  Tax Calculator    54.8%  ████████████████  │
│  Inventory Check   14.5%  ████              │
│  Auth Service       9.7%  ███               │
│  其他              21.0%  ██████             │
│                                              │
│  🎯 優化目標: 優先處理 Tax Calculator         │
└──────────────────────────────────────────────┘

為什麼有效：快速指出罪魁禍首：數據庫、身份驗證、緩存、第三方 API

📝 真實案例：我發現 60% 的結帳延遲與隱藏在三層深處的「稅務計算器」跨度相關。這個視圖在五分鐘內就暴露了問題。

6. N+1 Query Detector（N+1 查詢檢測器）

N+1 查詢模式通常表現為部署後每個請求的跨度中值計數跳躍，隨之而來的是延遲攀升。

顯示內容：每個事務的請求與響應時間，以及每個路由跨度計數分佈

┌─────────────── N+1 查詢檢測 ───────────────┐
│                                            │
│  路由: /api/users/{id}/orders              │
│                                            │
│  部署前 (v1.2.3) │ 部署後 (v1.2.4)         │
│  ─────────────────────────────────────    │
│                                            │
│  每請求跨度數:                              │
│  ┌──────────┐  │  ┌──────────┐            │
│  │    8     │  │  │   156    │ 🔥         │
│  │  spans   │  │  │  spans   │            │
│  └──────────┘  │  └──────────┘            │
│                                            │
│  平均延遲:                                  │
│  ┌──────────┐  │  ┌──────────┐            │
│  │  245ms   │  │  │  3,840ms │ 🔥         │
│  └──────────┘  │  └──────────┘            │
│                                            │
│  🔍 檢測到的模式:                           │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━         │
│  for order in orders:                     │
│    ├─ SELECT * FROM order_items           │
│    ├─ SELECT * FROM order_items           │
│    ├─ SELECT * FROM order_items           │
│    └─ ... (重複 150+ 次) ⚠️                │
│                                            │
│  💡 建議: 使用 JOIN 或批量查詢優化          │
└────────────────────────────────────────────┘