Skip to content
Skills Library
DevOps & cloud · Planning

observability

/observability

讓程式在正式機上「看得見」—— 先寫下 on-call 會問的問題,再選對訊號(log / metric / trace),最後對症狀而非成因告警。Use when shipping a feature to production, adding an endpoint, background job, retry, queue, or external integration, when an incident took too long to diagnose, or when setting up alerts. NOT for debugging a failure happening right now.

Repository
dotfiles ↗
Licence
MIT
Last repository change
10.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

讓程式在正式機上「看得見」—— 先寫下 on-call 會問的問題,再選對訊號(log / metric / trace),最後對症狀而非成因告警。Use when shipping a feature to production, adding an endpoint, background job, retry, queue, or external integration, when an incident took too long to diagnose, or when setting up alerts. NOT for debugging a failure happening right now.

Arguments

/observability [要加上觀測的功能或服務]
Original author description

讓程式在正式機上「看得見」—— 先寫下 on-call 會問的問題,再選對訊號(log / metric / trace),最後對症狀而非成因告警。Use when shipping a feature to production, adding an endpoint, background job, retry, queue, or external integration, when an incident took too long to diagnose, or when setting up alerts. NOT for debugging a failure happening right now.

How it works

  1. 什麼時候用
  2. Step 1 — 先定義「正常」,再開始埋
  3. Step 2 — 一個問題配一種訊號
  4. Step 3 — 結構化 log
  5. Step 4 — Metrics
  6. Step 5 — Tracing
  7. Step 6 — 告警:對症狀,不對成因
  8. Step 7 — 驗證 telemetry 本身
  9. 常見的自我開脫
  10. 紅旗
Original SKILL.md headings · 184 lines, 653 words
SKILL.md preview
---
name: observability
description: 讓程式在正式機上「看得見」—— 先寫下 on-call 會問的問題,再選對訊號(log / metric / trace),最後對症狀而非成因告警。Use when shipping a feature to production, adding an endpoint, background job, retry, queue, or external integration, when an incident took too long to diagnose, or when setting up alerts. NOT for debugging a failure happening right now.
argument-hint: "[要加上觀測的功能或服務]"
---

# /observability — 看不見的程式就是不能維運的程式

Instrumentation 不是上線後的附加品,它跟測試一樣是**跟功能一起寫**的。
功能沒有 telemetry 就上線,第一個使用者回報的 bug 就會變成考古工作。

---

## 什麼時候用

- 要上正式機的功能、新的 endpoint、背景工作、外部整合
- 出過一次「事後查不出發生什麼事」的意外
- 在 review 一個含 retry / queue / 跨服務呼叫的 PR
- 在設定或檢討告警規則

### 不要用在

| 情境 | 該用什麼 |
| --- | --- |
| **現在**正在爆的問題 | 先除錯(這支是讓下一次除錯變快的投資) |
| 已量測到的效能問題 | 效能分析與最佳化 |
| 上線當天的監看清單 | 發版流程;這支負責的是餵給它的資料 |

---

## Step 1 — 先定義「正常」,再開始埋

沒有問題的 telemetry 就是雜訊。埋之前先寫下 on-call 會問的 2–4 個問題:

```
功能:結帳付款重試
ON-CALL 會問:
1. 第一次就成功 vs 重試後成功的比例是多少?
2. 永久失敗時,原因是什麼?(provider 錯誤?逾時?驗證失敗?)
3. 金流商今天是不是比平常慢?
→ 底下每一個訊號都必須回答其中一題。
```

⚠️ 寫不出這幾個問題,代表還沒準備好埋 —— 你會什麼都 log,然後什麼都不知道。

## Step 2 — 一個問題配一種訊號

| 訊號 | 回答什麼 | 成本 | 例子 |
| --- | --- | --- | --- |
| **結構化 log** | 「這一筆到底發生什麼事?」 | 隨流量線性成長 | `payment_failed` 帶 provider 錯誤碼 |
| **metric** | 「總體上多常、多快?」 | 每個 series 固定,查詢便宜 | provider 呼叫的 p99 延遲 |
| **trace** | 「時間花在跨服務的哪一段?」 | 每請求,通常取樣 | 一筆慢結帳的逐段拆解 |

口訣:**metric 告訴你「出事了」,trace 告訴你「在哪」,log 告訴你「為什麼」。**

## Step 3 — 結構化 log

記**事件**,不要記散文。每一行是一個 JSON 物件,事件名稱要穩定:

```typescript
// ✗ 字串內插 —— 查不了、格式不一致
logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`);

// ✓ 穩定的事件名 + 機器可讀欄位
logger.warn({ event: 'payment_failed', paymentId: id, provider: 'stripe',
              errorCode: err.code, attempt: n }, 'payment failed');
```

| 等級 | 意思 | on-call 該做什麼 |
| --- | --- | --- |
| `error` | 不變量被打破,可能需要有人處理 | 調查 |
| `warn` | 降級但已處理(重試成功、走了 fallback) | 看趨勢 |
| `info` | 有意義的業務事件(訂單成立、工作完成) | 不用做事 |
| `debug` | 診斷細節 | 正式機預設關閉 |

**correlation ID 是必要的,不是加分項。** 在系統邊界產生(或接受)一個 request ID,
掛到每一行 log、每個 span、每個對外呼叫上。沒有它,你無法從交錯的 log 裡還原一筆請求。

```typescript
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
  req.log = logger.child({ requestId: req.id });
  res.setHeader('x-request-id', req.id);
  next();
});
```

⚠️ **絕不記錄 secret、token、密碼、完整 PII。** telemetry pipeline 是典型的資料外洩路徑。
用欄位白名單,不要整包 request body 丟進去。

## Step 4 — Metrics

請求型服務:每個 endpoint、每個外部相依都量 **RED** ——
**R**ate(每秒請求)、**E**rrors(失敗率)、**D**uration(延遲**直方圖**,不是平均)。
資源型(queue、connection pool、機器)用 **USE** —— Utilization、Saturation、Errors。

```typescript
const httpDuration = new Histogram({
  name: 'http_request_duration_seconds',
  labelNames: ['method', 'route', 'status_class'],   // '2xx',不是 '200'
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
});
```

**cardinality 是這裡唯一會炸的東西。** 每一組 label 組合都是一條獨立時間序列。
label 只能來自小而固定的集合。

```
可以當 label:route="/api/tasks/:id"  status_class="5xx"  provider="stripe"
絕不能當 label:user_id、email、request_id、完整 URL、錯誤訊息原文
```

高基數的東西屬於 log 和 trace,不屬於 metric。
**永遠不看平均,永遠看分位數** —— 平均會藏住那 1% 過得很慘的使用者。

## Step 5 — Tracing

用 OpenTelemetry(廠商中立,auto-instrumentation 幾乎零程式碼就涵蓋 HTTP / gRPC / 常見 DB client)。
手動 span 只加在有意義的內部工作單元上(`applyDiscounts`、`chargeProvider`),
並掛上 on-call 會拿來篩選的屬性。

⚠️ **每個非同步邊界都要傳遞 context** —— HTTP header、queue message metadata。
漏一個,trace 就在那裡斷掉。預設用低比例 head-based 取樣;後端支援的話錯誤留 100%。

## Step 6 — 告警:對症狀,不對成因

```
症狀(值得叫醒人)              成因(放 dashboard,不要叫人)
錯誤率 > 1% 持續 5 分鐘          CPU 85%
p99 延遲 > 2s                    某個 pod 重啟過
queue 積壓 > 10 分鐘             磁碟 70%
```

成因型告警會在沒事的時候響,然後在你沒預料到的失效模式上完全沉默。

每一條告警的規矩:

1. **必須可行動。** 如果反應是「不用理它,會自己好」,就刪掉這條告警。
2. **必須連到 runbook** —— 三行也行:這代表什麼、第一個要跑的查詢、往上找誰。
3. **閾值與持續時間要有依據** —— 來自 SLO 或歷史資料,不是拍腦袋。
4. **只用兩級**:page(使用者正在痛,現在處理)、ticket(降級,這週處理)。
   第三級一定會變成雜訊,然後訓練所有人忽略全部。

## Step 7 — 驗證 telemetry 本身

instrumentation 也是程式碼,也會寫錯。收工前實際觸發一次:

- 在測試機刻意觸發錯誤 → 用 `requestId` 撈得到,欄位是結構化的(不是 `[object Object]`)
- 打一些測試流量 → metric series 出現、label 正確、數值合理
- 在 tracing UI 裡追一筆請求走完全程 → 沒有斷掉的 span
- 每條新告警實際觸發一次(暫時調低閾值)→ 通知有進到正確的頻道,runbook 連結打得開

---

## 常見的自我開脫

| 你會這樣想 | 事實 |
| --- | --- |
| 「先做好功能,log 之後補」 | 「之後」會變成「第一次出事之後」,那是最貴的時間點。 |
| 「log 越多觀測性越好」 | 沒結構的雜訊只會讓事故變慢。三個查得到的事件贏過三百行散文。 |
| 「先用 console.log 就好」 | 沒結構就篩不了、關聯不了、告警不了。換成結構化 logger 只花五分鐘,一次。 |
| 「出事再看 dashboard 就好」 | 沒有先定義問題就做的 dashboard,什麼都有,就是沒有答案。 |
| 「重要的都先告警,之後再調」 | 會吵的 pager 會訓練人忽略它。調整永遠不會發生,漏掉的那次真的會。 |
| 「user_id 當 label 比較好 debug」 | 也會讓 metric 後端倒掉。高基數查詢屬於 log 和 trace。 |
| 「才兩個服務,tracing 太over」 | 兩個服務就已經有 log 回答不了的跨服務延遲問題了。auto-instrumentation 成本趨近於零。 |

## 紅旗

- 一個含 retry / queue / 外部呼叫的 PR,零新增 telemetry
- log 用字串內插組出來,不是結構化欄位
- 沒有 correlation ID,每行 log 都是孤兒
- metric 的 label 是 user ID、完整 URL 或錯誤訊息原文(cardinality 炸彈)
- 延遲只有平均值,沒有分位數
- 每天都響、每次都是「已讀」然後沒有任何動作的告警
- 對 CPU / 記憶體告警叫醒人,但使用者面的錯誤率沒人監控
- log 裡出現 secret、token 或完整 request body
- 一個正式機功能唯一的健康證據是「我機器上是好的」

## 驗收

- [ ] on-call 會問的問題有寫下來,每個訊號都對應到其中一題
- [ ] 所有 log 都是結構化的,事件名穩定,每行都有 correlation ID
- [ ] 實際抽查過輸出,沒有 secret / token / 未遮蔽 PII
- [ ] 每個新 endpoint 與外部相依都有 RED metric,label 集合有界
- [ ] 延遲是直方圖,p95/p99 查得到
- [ ] 一筆請求可以在 tracing UI 裡端到端追完,沒有斷 span
- [ ] 每條新告警都是症狀型、有 runbook 連結、實際觸發過一次
- [ ] 在測試機刻意製造的失敗,**只靠 telemetry** 就定位得到,不用讀原始碼

Versions

RepositoryScoreLicence
This page · htlin222/dotfiles100MIT
maragudk/fabrik100MIT
matteocodogno/wellforge100MIT
iuliandita/skills100MIT
ctxpipe-ai/ctxpipe100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
wrongstack/wrongstack100MIT
nvidia/ai-factory-operations-agent100Apache-2.0

Database snapshot: 13.11.2026 · package version 5a1b773c6aa5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100monitoring-observability
    OpenTelemetry, structured logging, distributed tracing, alerting, and dashboards. Use when instrumenting services, designing logs/traces/metrics, defining SLOs and alerts, or debugging production behavior from telemetry.
  • 100observability-and-instrumentation
    Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what…
  • 90vercel-observability
    Vercel observability for Web Analytics, Speed Insights, logs, tracing, alerts, and observability tooling. Use when monitoring performance or debugging production behavior on Vercel.
  • 100observability-and-instrumentation
    Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what…
  • 100observability-and-instrumentation
    Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what…
  • 100observability-and-instrumentation
    Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.