---
# System prepended metadata

title: o11y

---

o11y 

-------

![image](https://hackmd.io/_uploads/H1hYhpc3ex.png)

## 系統可觀測性基礎與價值（約 30 分）
🎯 學習目標

- 理解 可觀測性（O11y） 的核心目標：在複雜系統中快速定位問題與歸因。

- 認識可觀測性與傳統監控的差異與互補。

- 掌握基礎遙測訊號（Logs / Metrics / Traces）及其關聯性。

- 初步了解 SLO/SLI 的基本概念，知道「量化可靠性」的重要性。

📌 內容重點

- O11y 的問題定義：在複雜系統中「快速定位問題與歸因」

- 現代系統的挑戰

    - 微服務、雲原生、分散式架構

    - 系統邊界模糊

- Debug 困境

    - 一個請求可能跨十幾個服務

    - 單看 CPU、Memory 只能知道「系統卡住了」，卻不知道「哪裡卡住」

- 核心目標：不只是「監控數值」，而是提供足夠的訊號，讓工程師能回答未知的問題

🔍 與傳統監控的差異與互補

- 傳統監控

    - 側重基礎設施指標：CPU、Memory、Disk、Network

    - 靜態告警：閾值超過就報警（如 CPU > 80%）

- 可觀測性

    - 注重應用程式層與使用者體驗

    - 不只看數值，而是可查詢、可探索未知問題

    - 常見問題：

        - 「該請求的哪個服務的哪個操作慢？」

        - 「這個 5xx 是從哪個下游冒出來的？」

        - 「不同租戶的體驗有差嗎？」

- 互補關係

    - 監控 = 偵測已知問題（known unknowns）

    - 可觀測性 = 協助探索未知問題（unknown unknowns）

📊 遙測訊號與 SLO/SLI 基本概念

- 基礎遙測訊號

    - Logs：事件細節，適合看「發生了什麼」

    - Metrics：數值化趨勢，適合監控「是否正常」

    - Traces：端到端鏈路，適合找「哪裡出問題」

- 演示其關聯性
    - Log → Trace（trace_id）

    - Metrics → Trace（exemplar）

    - Trace ↔ Logs/Metrics（上下文串連）

- SLO/SLI

    - SLI：可量測的可靠性指標（例：成功率 99%）

    - SLO：服務目標（例：99.9% 可用性）


⚠️ 常見反模式

- 僅有監控，缺乏關聯性

- 資料孤島：Logs、Metrics、Traces 各自分離

- 無上下文關聯（缺 trace_id）

- 工具過多，排查體驗過於割裂

### Observability in the Development Cycle (10 分)
- 開發週期中可觀測性的角色（Dev → Test → Prod → Incident → Feedback）

- 「設計即可觀測性」(Observability by Design) 思維

- 強調可觀測性左移的概念，設計階段即可設計 SLI 與討論 log 內容與關聯


### Log（含 Log Level）（20 分）

🎯 學習目標

- 能寫出可查詢、可關聯的「結構化日誌」

- 正確使用 log 等級

結構化日誌：JSON 格式、關鍵欄位（timestamp、level、message、service、trace_id、span_id、user/tenant、http.method、route、status 等）

📌 內容重點

- 結構化日誌：JSON 格式，關鍵欄位

    - timestamp, level, message, service, trace_id, span_id, user/tenant, http.method, route, status

    - Log Level 原則

    - TRACE：函式級、逐步細節（套件提供的，僅本機/診斷）

    - DEBUG：除錯訊息（自己加入且預設不開啟）

    - INFO：正常業務事件

    - WARN：可恢復異常（重試、降級）

    - ERROR：請求失敗（單筆）

    - FATAL/CRITICAL：無法繼續（觸發告警/重啟）

- 最佳實務

    - 避免高基數 label

    - 避免敏感資訊

    - 加上 trace_id

💻 Demo / 練習

- 把應用日誌改為 JSON

- 在每條 log 注入 trace_id


### Grafana Loki（15 分）

🎯 學習目標

- 學會以 Loki 集中查詢，把 Log 轉成洞察

📌 內容重點

- 資料模型：labels（索引）+ log stream（內容），控制標籤基數

- 常用 labels：app, service, env, trace_id

- LogQL 入門

    - 基礎：{app="api",env="prod"} |= "timeout"

    - 結構化：| json / | logfmt

    - 指標化：sum(rate({app="api"} |= "error" [5m])) by (service)


💻 Demo / 練習

- 用 LogQL 找出「錯誤最多的路由」



### Metrics（20 分）

🎯 學習目標

- 理解指標類型與設計方法

- 能為 API 設計關鍵指標

📌 內容重點

- 指標類型

    - Counter、Gauge、Histogram、Summary

- 設計方法

    - RED（Rate/Errors/Duration）

    - USE（Utilization/Saturation/Errors）
    - The Four Golden Signals（Latency/Traffic/Errors/Saturation）


💻 Demo / 練習

- 為 GET /orders 增加 requests_total 與 request_duration_seconds (Histogram)

### Grafana + Prometheus（15 分）

學習目標：能建立 PromQL 查詢與 Grafana 儀表板與告警。
內容重點

📌 內容重點
常用 PromQL

- QPS：sum(rate(http_requests_total[1m])) by (route)

- 5xx 率：sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))

- p90 延遲：histogram_quantile(0.9, sum by (le,route) (rate(http_request_duration_seconds_bucket[5m])))


Demo/練習：做一張「API 健康」總覽，含 QPS、Error%、p90 延遲，並綁定 dashboard 變數（env、service）。

展示「從指標跳到 Trace（Exemplars）」的入口


### Tracing（20 分）

🎯 學習目標
- 掌握 trace 的核心概念並能讀懂一條鏈路圖。

📌 內容重點

- Trace / Span 基礎

- Span Attributes、Events、Links

- Context Propagation

- 取樣（head / tail）、W3C Trace Context（traceparent / baggage）

- 典型用例：找瓶頸、跨服務錯誤歸因、N+1 查找

💻 Demo / 練習

- 演示怎在程式中取得 span context，並注入到 log 中

### Grafana + Tempo（15 分）

🎯 學習目標

- 能在 Grafana 以 Tempo 查詢追蹤並與 Logs/Metrics 串連

📌 內容重點

- Grafana 串接方式
    - 以 TraceID 查詢

    - 從 Metrics Exemplars 跳到 Trace

    - 從 Log 的 trace_id 進入 Trace

-（可選）TraceQL 概念

💻 Demo / 練習

- 在儀表板找一個 p90 飆高點

- 點 exemplar → 進入該請求的 Trace → 對照同時間段 Log


強化「三種遙測訊號戶跳」的記憶。

> 5 分鐘「故障排查實戰」
> 給定一個模擬場景：「API 突然變慢，5xx 增加」
> 示範完整流程：
> - 從 Metrics 看到異常（QPS 正常但延遲飆高）
> - 點 Exemplar 進入 Trace 找到慢在哪個 span
> - 用 trace_id 撈 Logs 看錯誤細節
> - 歸因到具體程式碼問題


### OpenTelemetry 簡介 (15 分)
🎯 學習目標

- 認識 OpenTelemetry (OTel) 在可觀測性生態中的角色。

- 了解 OTel 的核心組件：API、SDK、Collector、協議。

- 理解為什麼 OTel 成為事實標準，以及它解決了哪些痛點。

📌 內容重點
1. 為什麼需要 OpenTelemetry？

    - 可觀測性遙測資料對應工具太多：每家廠商都有自己的 Agent、SDK。

    - 開發者痛點：

        - 綁定特定 APM 廠商 → Vendor Lock-in

        - 每種工具 API 不一樣，學習成本高

        - 難以跨 Logs / Metrics / Traces 做關聯

- OTel 的目標：提供一個統一、開源、跨語言的標準。

2. OpenTelemetry 的定位

    - CNCF 項目：雲原生基金會下的畢業專案。

    - 事實標準：被主流雲廠商（AWS、GCP、Azure）與工具（Grafana、Prometheus、Jaeger、Datadog、New Relic）採用。

    - 涵蓋範圍：

        - API / SDK：開發者在程式中 instrument 的介面

        - Collector：資料收集管道，可輸出到任何後端

        - 協議 OTLP：標準化傳輸格式

3. OpenTelemetry 的核心組件

    - API

        - 定義資料結構與操作方法（如建立 span、紀錄 metrics）。

    - SDK

        - 各語言的具體實作（Java、Go、Python、Node.js）。

    - Collector

        - 可插拔式代理：接收 → 處理 → 輸出。

        - 可同時送到多個後端（例如：ElasticSearch + Loki）。

    - OTLP (OpenTelemetry Protocol)

        - 標準化的傳輸協定，統一 Logs / Metrics / Traces。

4. OTel 的價值

    - 跨語言一致性（支援主流語言）

    - 跨後端可移植性（一次 instrument，多個工具可用）

    - 避免 vendor lock-in

    - 支援 Zero-code 與 Manual Instrumentation

### OpenTelemetry – Instrumentation 入門 (15 分)
🎯 學習目標

- 體驗零程式碼自動化 Zero-code Instrumentation

📌 內容重點

- Zero-code Instrumentation（Python/Node/Go 框架：HTTP、DB、Kafka）


💻 Demo

- 啟用自動化 SDK

- 驗證 log / metrics / trace 自動收集



