# 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ý.