# 可觀測性設計 (Observability Design) 知識合約指南

## 概述
`observability-design` 是知識合約，用來提供可觀測性設計的原則與模式。涵蓋 Logs、Metrics、Traces、Correlation IDs、Alerts 與 SLOs。供 `design-architecture` 在定義 Observability Strategy 時參考。

## 核心原則
### 可觀測性三支柱
- **Logs**：離散事件，含上下文（誰、什麼、何時、何地）
- **Metrics**：時間聚合的數值測量（速率、長條圖、Guage）
- **Traces**：跨服務端到端請求流

### 可觀測性不是監控
- 監控告訴你什麼時候壞了（已知未知）
- 可觀測性讓你能問為什麼壞了（未知未知）
- 必須從一開始就內建可觀測性，不能事後追加

## 設計重點
- **Logs**：Log 等級、結構化 Log（JSON）、集中式 Log 聚合
- **Metrics**：Counter、Gauge、Histogram、Summary；命名慣例
- **Traces**：分散式追蹤、Correlation ID 傳播、Span 設計
- **Alerts**：症狀警報、非操作警報；閾值與升遷路徑
- **SLOs**：可用性、延遲、正確性；Error Budget 與 Burn Rate Alerting

## 知識合約職責
- 提供可觀測性設計的理論指引
- 不直接產生監控設定或警報配置

## 不應做的事
- 不替系統選擇特定可觀測性工具
- 不定義具體的指標名稱或警報閾值
- 不產生監控設定檔案