Observability Spec · 可觀測規格

---
doc_type: "observability-spec"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["slo", "service-map"]
  optional: ["user-journey", "pii-classification"]
---

# Observability Spec: <service-name>

**Status:** Draft v0.X · **Owner:** <Architect / DevOps> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 5, 6, 9），全部必填——刻意沿用完整版章節編號讓兩版可對照。每結論行內加 `（依據：SLO §XXX / journey §YYY）`；每量化欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造；每個 metric 必須標 label + cardinality 估算（≤ 10k unique series 預設）；每個 SLI 必須有對應 metric；PII 欄位無分類資料寫 `_TODO_` 不假設可採集。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行，主管 30 秒讀完。內容：要觀測哪個服務、有幾條 SLI、cardinality 估算、最敏感 PII 處理 -->

<3-5 行說明>

> **TL;DR:** <一句話：本卡定義 X 服務的 N 條 metric / M 條 log / K 條 trace，覆蓋 Y 條 SLI>

---

## 2. Signals Required（metric / log / trace 三層）

<!-- ai-rule: 每個 metric 必填 type + labels + cardinality + sli_ref；每個 SLI 必須有對應 metric -->

### Metrics

| Name | Type | Labels | Cardinality | Unit | SLI ref | Confidence |
|---|---|---|---|---|---|---|
| http_request_duration_seconds | histogram | route, method, status_class | 500 | seconds | SLI-001 | **[H]** |
| db_query_duration_seconds | histogram | query_kind | 50 | seconds | SLI-002 | **[H]** |

### Logs

| Event | Fields | PII handling | Retention tier |
|---|---|---|---|
| checkout_failed | user_id_hash, order_id, error_code, latency_ms | hash user_id | hot |
| auth_login | user_id_hash, ip_truncated, ua_fingerprint | truncate ip | warm |

### Traces

| Span | Attributes | Parent span |
|---|---|---|
| db.query.checkout | db.statement_truncated, db.rows_examined | http.handler.checkout |

---

## 3. Cardinality Budget & Retention

<!-- ai-rule: per_metric_max ≤ 10k 預設；retention tier 須對應 hot/warm/cold 三檔 -->

### Cardinality budget

| Field | Value |
|---|---|
| **Per metric max** | 10,000 unique series |
| **Per service max** | 100,000 unique series |
| **Enforcement** | reject_on_ingest |

### Retention per tier

| Tier | Retention | Use case |
|---|---|---|
| **Hot** | 14d | 即時 debug |
| **Warm** | 90d | trend / weekly review |
| **Cold** | 13 months | SOC 2 audit |

---

## 5. Alert Rules（top 3-5）

<!-- ai-rule: 每條 alert 對應 ≥ 1 條 SLI；含 expression + threshold + duration + runbook -->

| Name | Expression (PromQL or eq) | Threshold | Window | SLO ref | Severity | Runbook |
|---|---|---|---|---|---|---|
| slo_burn_fast | error_rate / target_error_rate | 14.4× | 1h | SLO-001 | SEV2 | <link> |
| slo_burn_slow | error_rate / target_error_rate | 6× | 6h | SLO-001 | SEV3 | <link> |

---

## 6. Sampling & PII Redaction

<!-- ai-rule: sampling 必須說明 head-based + tail-based 策略；PII 欄位無分類寫 _TODO_ -->

### Sampling strategy

| Signal | Strategy | Rationale |
|---|---|---|
| Traces | head-based 1% + tail-based 100% for error | 控成本 + 保留錯誤 debug 力 |
| Logs | full ERROR, sample 10% INFO | 同上 |

### PII redaction

| Field | Rule | Compliance basis |
|---|---|---|
| email | hash with HMAC-SHA256 | GDPR Art.32 |
| credit_card | drop entirely | PCI DSS |
| ip_address | truncate last octet | GDPR Art.5 |

---

## 9. Decision Log（key 2-3 條）

<!-- ai-rule: 每條必含 chosen + 至少 1 個 rejected + 拒絕原因 -->

| Date | Decision | Options | Chosen | Rejected why | Confidence |
|---|---|---|---|---|---|
| YYYY-MM-DD | Trace sampling rate | 1% / 10% / 100% | 1% head + 100% tail-on-error | 10% (太貴)、100% (違反 cardinality budget) | **[H]** |

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 5, 6, 9）
> - [ ] 每個 metric 含 type + labels + cardinality + SLI ref
> - [ ] 每條 SLI 在 metric 表有對應條目
> - [ ] Per-metric cardinality ≤ 10k
> - [ ] Retention 三檔（hot / warm / cold）
> - [ ] Alert rules 每條對應 ≥ 1 條 SLI + 有 runbook link
> - [ ] PII 表逐項對應 compliance basis（GDPR / PCI / HIPAA）
> - [ ] Sampling 含 head + tail 策略
> - [ ] Decision Log ≥ 1 條，每條有 rejected reason
> - [ ] 無 YAML / JSON schema 輸出