save

sa-output/e-commerce/02-architecture/adr/ADR-010_kien-truc-observability-alerting.md

@@ -0,0 +1,166 @@
+# ADR-010 — Kiến trúc observability & alerting cho dịch vụ giao dịch lõi
+
+*Tên file: `adr/ADR-010_kien-truc-observability-alerting.md`*
+
+| | |
+|---|---|
+| **Status** | `Proposed` |
+| **Date** | 2026-09-15 |
+| **Người quyết** | SA + Ops/SRE (hạ tầng — `decision-radar.md §5`) |
+| **Người đề xuất** | SA (qua skill `sa-2-architecture`, hoạt động `adr`) |
+| **Điểm radar** | **~6/10** |
+| **Supersedes** | — |
+| **Superseded by** | — |
+| **Liên quan** | `ASR-011` · `QAS-013` · `CMP-02`, `CMP-04`, `CMP-11` |
+
+> ⚠️ **ADR bất biến sau khi `Accepted`.** Muốn đổi quyết định thì viết ADR mới có
+> `Supersedes: ADR-010` và đổi trạng thái bản cũ thành `Superseded by`.
+
+---
+
+## 1. Bối cảnh
+
+Sự cố lỗi 5xx tăng đột biến ở Cart & Order, Payment, Identity & Access phải được cảnh báo tự
+động trong ≤1 phút; on-call phải acknowledge trong ≤15 phút (`ASR-011`, `QAS-013`). Cần chuẩn
+log/metric/trace thống nhất cho 3 service lõi và pipeline cảnh báo kết nối kênh on-call.
+`QAS-013` ghi rõ ngưỡng cảnh báo **kế thừa nguyên trạng** từ `SAD.md §9.4.1`, chưa từng diễn tập
+inject lỗi.
+
+**Ràng buộc đang chi phối:**
+
+| Nguồn | Nội dung |
+|---|---|
+| `ASR-011` | Chuẩn log/metric/trace thống nhất, pipeline cảnh báo ≤1 phút, on-call ack ≤15 phút |
+| `QAS-013` | Diễn tập inject lỗi đo thời gian từ inject tới cảnh báo — chưa từng diễn tập |
+| `CON-08` | Đội Ops trực theo ca + escalation 24/7 — giả định, chưa xác nhận số người thật (`OQ-008`) |
+
+**Cái đã biết chắc / cái còn là giả định:**
+
+| Điều | 🟢 Đã kiểm chứng / 🔴 Giả định | Bằng chứng |
+|---|---|---|
+| Cần cảnh báo tự động cho 3 service lõi trong ≤1 phút | 🟢 Đã kiểm chứng | `ASR-011`, yêu cầu doanh thu phụ thuộc trực tiếp |
+| CloudWatch Alarms/Synthetics đủ đáp ứng ngưỡng ≤1 phút trong ngữ cảnh này | 🔴 Giả định | Chưa diễn tập inject lỗi |
+| Đội Ops đủ người để acknowledge ≤15 phút 24/7 | 🔴 Giả định | `OQ-008` chưa xác nhận |
+
+## 2. Phương án đã cân nhắc
+
+### PA-1 — CloudWatch Logs/Metrics/Alarms native (AWS) + PagerDuty/OpsGenie cho on-call
+
+| | |
+|---|---|
+| **Mô tả** | Dùng CloudWatch Logs cho log tập trung, CloudWatch Metrics/Alarms cho ngưỡng cảnh báo, X-Ray cho trace, kết nối PagerDuty/OpsGenie cho on-call rotation |
+| **Ưu** | Managed hoàn toàn, tích hợp sẵn với ECS Fargate/RDS/SQS — không cần vận hành thêm cluster; chi phí theo mức dùng, dễ ước lượng |
+| **Nhược** | CloudWatch Logs Insights có giới hạn về khả năng truy vấn phức tạp so với ELK/Datadog; chi phí có thể tăng nhanh nếu log volume lớn không được kiểm soát retention |
+| **Chi phí đảo ngược** | Trung bình — chuyển sang stack khác (Datadog, ELK) sau này cần viết lại instrumentation code |
+
+### PA-2 — Self-hosted ELK/Grafana stack
+
+| | |
+|---|---|
+| **Mô tả** | Tự vận hành Elasticsearch/Logstash/Kibana + Prometheus/Grafana trên ECS/EKS riêng |
+| **Ưu** | Khả năng truy vấn/dashboard linh hoạt hơn, không phụ thuộc vendor lock-in AWS |
+| **Nhược** | Thêm cụm phải vận hành/patch/scale — vi phạm Conway với năng lực team hiện tại (cùng lý lẽ với việc loại Kafka/MSK ở `ADR-005`); tăng chi phí vận hành đáng kể |
+| **Chi phí đảo ngược** | Cao — đã đầu tư vận hành cụm riêng thì chuyển sang managed service sau là bỏ phí đầu tư ban đầu |
+
+### PA-3 — Datadog/New Relic (SaaS bên thứ ba)
+
+| | |
+|---|---|
+| **Mô tả** | Dùng nền tảng observability SaaS thương mại, tích hợp qua agent/SDK |
+| **Ưu** | Tính năng phong phú (APM, log correlation, dashboard sẵn), không cần vận hành hạ tầng riêng |
+| **Nhược** | Chi phí SaaS theo host/dữ liệu có thể cao hơn CloudWatch ở quy mô lớn (`DRV-04` hàng nghìn–chục nghìn concurrent); thêm một nhà cung cấp bên ngoài cần đánh giá hợp đồng/dữ liệu residency (log có thể chứa thông tin nhạy cảm) |
+| **Chi phí đảo ngược** | Trung bình — có thể chuyển sang CloudWatch/khác sau nhưng mất dashboard đã cấu hình |
+
+### Bảng so sánh
+
+| Tiêu chí | PA-1 (CloudWatch) | PA-2 (Self-hosted ELK) | PA-3 (Datadog/New Relic) |
+|---|---|---|---|
+| Khớp năng lực team (`CON-05`) | ✅ | ❌ Thêm cụm phải vận hành | ✅ |
+| Chi phí dự đoán được | ✅ | 🔶 Chi phí nhân sự vận hành ẩn | 🔶 Có thể tăng theo scale |
+| Tích hợp sẵn với AWS managed service đã chọn | ✅ | 🔶 Cần cấu hình thêm | 🔶 Cần agent riêng |
+| Đã có trong `TCO §3.2`/ngân sách hiện tại | ✅ | ❌ Chưa tính | ❌ Chưa tính |
+
+## 3. Quyết định
+
+> **Chọn PA-1 — CloudWatch Logs/Metrics/Alarms + X-Ray (trace) + PagerDuty/OpsGenie (on-call).**
+
+**Vì sao:** Khớp năng lực team hiện tại (không thêm cụm phải vận hành, nhất quán với hướng managed
+service đã chọn ở `ADR-001`/`ADR-005`) và đã có trong ước lượng ngân sách hiện tại.
+
+**Phạm vi áp dụng:** Toàn bộ 3 service lõi (Payment, Cart & Order, Identity & Access) ở giai đoạn
+đầu; mở rộng cho Nhóm Hỗ trợ khi cần.
+
+### Điều kiện chuyển `Proposed → Accepted`
+
+| Điều kiện | Ai xác nhận | Trạng thái hiện tại |
+|---|---|---|
+| Diễn tập inject lỗi đo thời gian từ inject tới cảnh báo ≤1 phút | Ops/SRE | Chưa từng diễn tập (`QAS-013`) |
+| Xác nhận công cụ on-call cụ thể (PagerDuty hay OpsGenie) và ngân sách | PO/Ops | Chưa chốt |
+| Không bắt buộc POC riêng (radar 6, dưới ngưỡng 8) nhưng khuyến nghị diễn tập trước `Accepted` | Ops/SRE | — |
+
+## 4. Phương án bị loại và lý do
+
+| Phương án | Loại vì | Gắn với | Điều kiện nào thì xét lại |
+|---|---|---|---|
+| PA-2 — Self-hosted ELK/Grafana | Thêm cụm phải vận hành, vi phạm Conway với năng lực team | `CON-05` | Nếu về sau team có SRE chuyên trách đủ lớn và cần khả năng truy vấn phức tạp hơn CloudWatch cung cấp — xét lại |
+| PA-3 — Datadog/New Relic | Chi phí SaaS chưa có trong ngân sách hiện tại; thêm nhà cung cấp bên ngoài cần đánh giá residency dữ liệu log | `TCO §3.2`, `CON-06` | Nếu CloudWatch không đáp ứng đủ nhu cầu (VD thiếu APM sâu) và PO chấp nhận chi phí thêm — trình bảng đánh đổi |
+
+## 5. Hệ quả
+
+**Hệ quả tích cực**
+
+- Không thêm thành phần hạ tầng phải vận hành riêng — khớp năng lực team
+- Chi phí dự đoán được, đã nằm trong ước lượng `TCO`
+
+**Hệ quả tiêu cực phải sống chung**
+
+- Khả năng truy vấn log phức tạp hạn chế hơn ELK/Datadog — có thể cần thêm công cụ bổ sung khi
+  hệ thống lớn hơn
+- Chưa diễn tập inject lỗi — ngưỡng ≤1 phút vẫn là con số trên giấy cho tới khi diễn tập
+
+**Cái quyết định này khoá lại**
+
+| Muốn đổi về sau thì | Tốn |
+|---|---|
+| Chuyển sang Datadog/ELK sau khi đã cấu hình CloudWatch dashboard | Viết lại instrumentation + dashboard, di chuyển alert đã cấu hình |
+
+**Việc phát sinh**
+
+| Việc | Chủ | Hạn | Ghi ở đâu |
+|---|---|---|---|
+| Diễn tập inject lỗi đo thời gian cảnh báo | Ops/SRE | Trước go-live | `ARISK`/`QAS-013` (kết quả mới) |
+| Chốt công cụ on-call cụ thể (PagerDuty/OpsGenie) | PO/Ops | GĐ2 tiếp theo (`inf`) | `INF_e-commerce` |
+| Chuẩn hoá định dạng log + correlation id cho 3 service lõi | Tech Lead | GĐ3 (`AGD`) | `AGD` |
+
+## 6. Cách kiểm chứng quyết định này được tuân thủ
+
+| Cách kiểm | Công cụ | Chạy ở đâu | `FIT` |
+|---|---|---|---|
+| Diễn tập inject lỗi (dừng task ECS) đo thời gian tới cảnh báo | Chaos thủ công | Staging trước go-live, định kỳ sau đó | — (kết quả ghi vào `ARISK`) |
+| Mọi service lõi ghi log theo định dạng chuẩn có `correlation_id` | Lint log format trong CI | CI | `FIT-13` (ứng viên) |
+| Alert có kết nối kênh on-call thật, test bằng cảnh báo giả lập | Kiểm tra cấu hình PagerDuty/OpsGenie | Định kỳ (đề xuất hàng tháng) | `⚠️ Khuyến nghị — cần kiểm thủ công định kỳ` |
+
+## 7. Điều kiện xét lại
+
+| Dấu hiệu | Ngưỡng | Ai theo dõi |
+|---|---|---|
+| Diễn tập inject lỗi cho thấy thời gian cảnh báo > 1 phút | Bất kỳ lần nào | Ops/SRE |
+| Chi phí CloudWatch vượt ngân sách dự kiến đáng kể | > 20% so với `TCO` | SRE/tài chính |
+
+## 8. Tham chiếu
+
+- POC: Diễn tập inject lỗi (chưa chạy)
+- Bài đo: `FIT-13` (ứng viên GĐ3)
+- Tài liệu ngoài: `QAS_e-commerce_v1.0.md §A3 QAS-013`
+- Thảo luận: `ASR_e-commerce_v1.0.md §B2 ASR-011`
+
+## 9. Review log (không đổi Status)
+
+| Ngày | Người review | Vai trò | Quyết định | Lý do chưa chuyển `Accepted` |
+|---|---|---|---|---|
+| 2026-09-15 | Điều phối dự án (thay mặt Tech Lead, chế độ chạy thử) | Tech Lead (ký thay, ngoại lệ `DEC-01`) | `Reviewed (Proposed giữ nguyên)` — nội dung đủ làm cơ sở thiết kế tiếp (`icd`/`dat`/`sec`/`inf`/`fail`) | Chưa có chữ ký thật Ops/SRE; khuyến nghị diễn tập alerting trước khi chốt |
+
+> Đây là ghi nhận **review nội dung**, không phải "sign" theo nghĩa gate: `Status` giữ nguyên
+> `Proposed`. Xem `00-index/ADL_e-commerce.md` (Change Log — Review 2026-09-15) và `ADL §8`
+> "Việc phải làm" cho điều kiện chuyển `Accepted`. Confidence tổng thể của lượt review: 🔴 —
+> `AG2` chưa ký.