Add read-only production runtime audit

2026-08-17 11:17:40 +07:00
parent 057d4ed9dc
commit a1de4715a4
106 changed files with 6869 additions and 1782 deletions
@@ -0,0 +1,62 @@
+# Vận hành, triển khai và xử lý sự cố
+
+> Loại chính: How-to  
+> Phạm vi: EC2 + Docker Compose hiện hành
+
+## Deploy
+
+Trước deploy, ghi commit SHA, yêu cầu CI AI/ingestion/web xanh, kiểm tra secret và
+Qdrant manifest tương thích, đồng thời đánh giá migration. Chạy `deploy.yml` theo
+path/branch filter hoặc manual dispatch và theo dõi đến khi reconcile xong.
+
+Sau deploy:
+
+1. xác nhận SHA/image đang chạy đúng bản;
+2. kiểm tra `/health` và `/ready`;
+3. gửi smoke case qua web, gồm answerable có citation và abstain;
+4. quan sát error rate, latency, provider failure và decision distribution;
+5. ghi lại thời điểm, SHA và kết quả.
+
+CI và deploy độc lập về kỹ thuật; trạng thái CI đỏ không tự động chặn deploy.
+
+## Rollback
+
+Workflow `rollback.yml` nhận `target_sha`. Chọn SHA từng deploy thành công và còn
+tương thích với database/corpus. Sau rollback phải xác nhận SHA, health/readiness,
+smoke cases và metric qua đủ cửa sổ để thấy lỗi ban đầu biến mất.
+
+Rollback code không tự rollback Qdrant corpus hoặc database migration. Với corpus,
+dùng snapshot/migration riêng; không rollback dữ liệu phá huỷ khi chưa có backup.
+
+## Theo dấu request
+
+1. Lấy `trace_id`, `correlation_id`, `otel_trace_id` từ response.
+2. Tra `rag_retrieval_trace` để xem query, scope, intent, decision, reason, drug và citations.
+3. Kiểm tra Prometheus request/stage duration, decision, provider failure và generation rejection.
+4. Nếu OTel bật, tìm trace trong Tempo/Grafana để xác định stage chậm/lỗi.
+5. Phân loại nguyên nhân: input/scope, corpus/retrieval, provider/model hoặc grounding.
+
+`/metrics` có thể yêu cầu `Authorization: Bearer <token>` khi `METRICS_TOKEN` được đặt.
+
+## Observability stack
+
+Local stack là Prometheus, OpenTelemetry Collector, Tempo và Grafana. OTel mặc định
+tắt. Observability failure không được làm service dừng trả lời; trace write failure
+phải xuất hiện trong metric/log. Production monitoring cần readiness và synthetic
+query vì health không chứng minh citation pipeline hoạt động end-to-end.
+
+## Troubleshooting
+
+| Triệu chứng | Kiểm tra đầu tiên | Không nên làm |
+|---|---|---|
+| service không ready | datastore, startup log, manifest/model/dimensions | bỏ qua manifest gate |
+| `provider_unavailable` tăng | region, credential, quota, network, stage trace | báo “Dược thư không có dữ liệu” |
+| retrieval score thấp | drug/section route, collection và manifest | hạ threshold không qua eval |
+| grounding rejection tăng | evidence packet, model output, validator | hiển thị raw output |
+| clarify lặp | history, field thiếu, circuit breaker | tăng loop vô hạn |
+| citation sai trang | printed-page map, chunk payload, quarantine | thay printed page bằng physical page |
+
+Các reason grounding quan trọng gồm `ungrounded_number`, `invalid_citation`,
+`uncited_claim`, `unsupported_claim` và `incomplete_answer`. Giữ fail-closed và
+thêm regression test trước khi sửa prompt/parser/validator.
+