---
name: observability-instrument
description: Adds production observability to a service — structured logging, RED/USE metrics, OpenTelemetry distributed tracing, plus Prometheus/Grafana dashboards and actionable SLO-based alerts. Triggers when instrumenting code, designing metrics/dashboards, defining SLI/SLO, or fixing noisy/missing alerts.
when_to_use: เพิ่ม logging/metrics/tracing ลง service, ออกแบบ dashboard, ตั้ง SLI/SLO/alert, alert noisy หรือ blind spot
---

## When to Use

ใช้ skill นี้เมื่อทำงานข้อใดข้อหนึ่ง:

- เพิ่ม observability (logging/metrics/tracing) ลง service ที่ยัง blind
- ออกแบบ metric/dashboard ใหม่ หรือต้องเลือกว่าจะวัด signal อะไร
- กำหนด SLI/SLO + error budget
- แก้ alert ที่ noisy (เด้งบ่อยจนคนเมิน) หรือ blind spot (incident เกิดแต่ไม่มี alert)
- debug latency/error ที่กระจายข้ามหลาย service (ต้อง distributed tracing)

**ไม่ใช้เมื่อ:** แค่ debug ครั้งเดียวด้วย print/log ชั่วคราว, service เป็น prototype throwaway, หรือมี platform team จัดการ instrumentation มาตรฐานให้แล้ว (ใช้ของเขา)

## Steps

ทำตามลำดับ — แต่ละ step verify ได้จริง ห้ามข้ามไป dashboard ก่อนมี metric

### 1. เลือก signal: RED สำหรับ request-driven, USE สำหรับ resource

- **RED** (service ที่รับ request: API, RPC, consumer) → วัด 3 ตัวต่อ endpoint/route:
  - **Rate** — requests/sec
  - **Errors** — failed requests/sec (แยกจาก rate, ไม่ใช่ ratio ตอน emit — คำนวณ ratio ตอน query)
  - **Duration** — latency distribution (histogram เสมอ ไม่ใช่ avg)
- **USE** (resource: CPU, memory, disk, queue, connection pool) → วัด **Utilization, Saturation, Errors**
- เริ่มจาก golden path: instrument entry point (HTTP handler / message consumer) ก่อน แล้วค่อยลงลึก dependency call (DB, cache, downstream HTTP)

### 2. Structured logging — JSON + correlation/trace id ทุก log line

- ออก log เป็น **JSON (one object per line)** ไม่ใช่ printf string — เพื่อ query/filter ได้
- ทุก log entry ต้องมี field: `timestamp` (RFC3339/ISO8601 UTC), `level`, `message`, `service`, `trace_id`, `span_id`
- **inject `trace_id` จาก context** ทุก log ที่อยู่ใน request scope — เพื่อ jump จาก log → trace ได้ (logs↔traces correlation)
- log levels จริง: `ERROR` = ต้องมีคนดู / `WARN` = degraded แต่ทำงานได้ / `INFO` = state change สำคัญ (start/stop/deploy) / `DEBUG` = ปิดใน prod ปกติ
- **ห้าม log PII/secret** (password, token, full card, email เต็ม) — redact ก่อน ออก field ที่ filter ได้แทน (เช่น `user_id` ไม่ใช่ email)
- ใส่ context เป็น field ไม่ใช่ string interpolation: `{"event":"order_failed","order_id":"123","reason":"timeout"}` ไม่ใช่ `"order 123 failed: timeout"`

### 3. OTel tracing — span ครอบ unit of work + propagate context

- ใช้ **OpenTelemetry SDK** (vendor-neutral) — auto-instrumentation สำหรับ HTTP/gRPC/DB client ก่อน, manual span เฉพาะ business logic สำคัญ
- 1 span = 1 unit of work ที่มีความหมาย (handle request, query DB, call downstream, ประมวลผล batch)
- **propagate context ข้าม boundary** — ใส่ `traceparent` header (W3C Trace Context) ทุก outbound HTTP/RPC/message; ฝั่งรับ extract → ต่อ trace เดียวกัน
- ใส่ span attributes ที่ filter ได้: `http.route`, `http.status_code`, `db.system`, `messaging.destination` — **ห้ามใส่ high-cardinality** (user_id, request_id) เป็น attribute ถ้าจะ aggregate (ใส่เป็น event/log แทน)
- mark span error ให้ถูก: set status `ERROR` + record exception → ไม่งั้น trace ดู green ทั้งที่ fail
- **sampling**: head-based (เช่น 10%) สำหรับ traffic สูง แต่ **always-sample error/slow span** (tail-based ถ้า backend รองรับ) — ไม่งั้น trace ของ incident หาย

### 4. Prometheus metrics — naming + label กัน cardinality ระเบิด

- metric type ให้ถูก: **Counter** (monotonic: requests, errors) / **Histogram** (latency, size — ได้ percentile) / **Gauge** (queue depth, pool in-use)
- naming convention: `<namespace>_<subsystem>_<name>_<unit>` + suffix มาตรฐาน — `_total` (counter), `_seconds` (duration), `_bytes` (size)
  - ดี: `http_requests_total`, `http_request_duration_seconds`, `db_pool_connections_in_use`
- **base unit เสมอ**: seconds ไม่ใช่ ms, bytes ไม่ใช่ MB
- **🔴 cardinality discipline (gotcha ที่ทำ Prometheus ล่มบ่อยสุด):**
  - label = bounded set เท่านั้น: `method`, `route` (template `/users/:id` ไม่ใช่ `/users/42`), `status_code`, `status_class` (2xx/4xx/5xx)
  - **ห้ามใส่ unbounded เป็น label**: user_id, request_id, email, full URL with query, raw error message, timestamp
  - cardinality = ผลคูณของจำนวนค่าทุก label → 3 labels × (10 routes × 5 methods × 6 status) = 300 series/metric; ถ้าใส่ user_id (1M users) = 1M series → OOM
- histogram bucket: ตั้ง bucket ให้ครอบ SLO threshold (เช่น SLO p99 < 300ms → ต้องมี bucket ที่ 0.3) ไม่งั้นวัด SLO ไม่ได้

### 5. Grafana dashboard — RED panels + SLI ต่อ service

- 1 dashboard ต่อ service, layout top→down: **SLI summary → RED → dependencies → saturation**
- RED panels (PromQL):
  - Rate: `sum(rate(http_requests_total[5m])) by (route)`
  - Errors: `sum(rate(http_requests_total{status_class="5xx"}[5m])) by (route)` และ error ratio = errors/rate
  - Duration: `histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, route))` — **p50/p95/p99 แยกเส้น ห้ามใช้ avg**
- ใช้ template variable (`$service`, `$route`) ให้ reuse dashboard ได้หลาย service
- ทุก panel ต้อง answer คำถาม operational จริง — panel ที่ไม่เคยถูกดูตอน incident = ลบทิ้ง

### 6. SLO + error budget → alert ที่ actionable (multi-window burn rate)

- กำหนด **SLI** (วัดได้จาก metric ที่มีจริง): availability = `good_requests / total_requests`, latency = `% requests < threshold`
- ตั้ง **SLO** เป็นเป้า (เช่น 99.9% / 30 วัน) → **error budget** = 0.1% = ~43 นาที downtime/เดือน
- **alert บน burn rate ของ error budget ไม่ใช่ raw threshold** — นี่คือกุญแจกัน noise:
  - **multi-window, multi-burn-rate**: fast burn (เช่น 14.4× budget ใน 1h window + 5m window ยืนยัน) → page; slow burn (เช่น 3× ใน 6h) → ticket
  - 2 window (long + short) กัน flapping: long window จับว่า "เผาจริง", short window กัน alert ค้างหลังหายแล้ว
- **ทุก alert ต้อง actionable**: มี runbook link, บอกว่าใคร impact, มี action ชัด — alert ที่ทำอะไรไม่ได้ = ลบ
- แยก **symptom-based** (user เจ็บจริง: error rate, latency สูง → page) ออกจาก **cause-based** (CPU สูง, disk เต็ม → ticket/warn) — page เฉพาะ symptom

### 7. Verify — sample query + trace จริง

- ดู Common Errors + Verify ด้านล่าง รัน end-to-end ก่อน declare done

## Common Errors

Gotcha จริงที่เจอซ้ำ — เช็คก่อน ship:

- **Cardinality bomb** — ใส่ user_id/request_id/raw error เป็น Prometheus label → series ระเบิด → Prometheus OOM/ช้า. แก้: label เป็น bounded set, route ใช้ template (`/users/:id`), error เก็บใน trace/log แทน
- **avg latency โกหก** — `avg(duration)` ซ่อน tail; p99 800ms แต่ avg 50ms = ผู้ใช้ 1% เจ็บแต่ dashboard เขียว. ใช้ `histogram_quantile` percentile เสมอ
- **histogram bucket ไม่ครอบ SLO** — SLO p99<300ms แต่ bucket กระโดด 0.1→0.5 → คำนวณ p99 ผิดเพราะ interpolate. ตั้ง bucket ให้มีขอบที่ threshold พอดี
- **trace ขาดตอน** — ลืม propagate `traceparent` ที่ boundary (async job, message queue, new HTTP client) → trace แตกเป็นหลายอัน หา root cause ไม่ได้. เช็คทุก outbound call ใส่ context
- **error span ดู green** — catch exception แล้วไม่ set span status ERROR → trace ดูปกติทั้งที่ fail. ต้อง `span.recordException` + set status
- **rate() บน gauge / sum บน histogram_bucket ผิด le** — `rate()` ใช้กับ counter เท่านั้น; `histogram_quantile` ต้อง `by (le, ...)` มี `le` เสมอ ไม่งั้นได้ NaN
- **alert บน raw threshold** (เช่น CPU>80%) → noisy, page ตอนตี 3 โดยไม่มี user เจ็บ. ย้ายไป burn-rate/symptom-based
- **counter ไม่มี `_total`, duration เป็น ms** → ผิด convention, query/recording rule พัง. base unit + suffix มาตรฐานเสมอ
- **log PII รั่ว** — ออก email/token/PII ลง log JSON → compliance/security incident. redact ก่อน emit
- **sampling กิน error traces** — head sampling 10% ทำให้ trace ของ incident หาย 90%. always-keep error/slow span
- **double-counting จาก label ที่หาย** — เปลี่ยน label set ของ metric เดิม → recording rule/alert คำนวณผิดช่วง transition. version metric หรือ migrate พร้อม recording rule

## Verify

ก่อน declare done ต้องผ่านทุกข้อ (มีหลักฐานจริง ไม่ใช่ "น่าจะได้"):

1. **Metrics scrape ได้** — `curl localhost:<port>/metrics` เห็น metric ที่ instrument + format ถูก (มี `_total`/`_seconds`, HELP/TYPE line). ตรวจ Prometheus target = `UP`
2. **PromQL ของ RED ทั้ง 3 คืนค่า** — รัน query rate/errors/duration จริง ได้ตัวเลข ไม่ใช่ empty/NaN; `histogram_quantile` มี `le` ครบ
3. **Cardinality check** — `count({__name__="<metric>"})` ดู series count สมเหตุผล (สิบ–พัน ไม่ใช่ แสน+); ยิง test request ด้วย id ต่างกันหลายตัว → series ต้องไม่เพิ่มตาม id
4. **Trace ครบ end-to-end** — ยิง request ผ่าน ≥2 service เห็น 1 trace เดียวเชื่อม span ครบ ใน tracing backend; error case → span status = ERROR + exception ติด
5. **Log↔trace correlation** — เปิด log ของ request นั้น เห็น `trace_id` ตรงกับ trace; click จาก log ไป trace ได้
6. **Alert ยิงจริงตอนควรยิง** — trigger error/latency เกิน SLO (load test / fault inject) → burn-rate alert fire ภายใน window ที่ตั้ง; พอหาย → alert resolve (ไม่ค้าง)
7. **Alert เงียบตอนควรเงียบ** — spike สั้นๆ ใต้ burn-rate threshold → ไม่ page (กัน noise); confirm short+long window ทำงาน
8. **Dashboard อ่านออกตอน incident** — เปิด dashboard ระหว่าง fault inject เห็น RED panel เปลี่ยนชัด ชี้ไป root cause ได้