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,110 @@
+# Cách lần một request từ người dùng đến evidence
+
+## Phân loại
+
+**Loại tài liệu:** How-to.
+
+**Reader job:** điều tra một câu trả lời chậm, abstain hoặc có citation đáng ngờ
+bằng correlation ID, PostgreSQL, Tempo và Prometheus.
+
+## Điều kiện tiên quyết
+
+- Có ít nhất một trong ba giá trị: `trace_id`, `correlation_id`, `otel_trace_id`.
+- Có quyền đọc PostgreSQL và Grafana/Tempo production.
+- Biết khoảng thời gian request.
+
+Không đưa nội dung query hoặc dữ liệu người dùng vào ticket công khai.
+
+## Bước 1 — Thu ID từ response
+
+API body trả:
+
+```text
+trace_id
+correlation_id
+otel_trace_id
+decision
+reason
+```
+
+Headers cũng có `X-Correlation-ID` và `X-Trace-ID`. Ưu tiên giữ cả body lẫn
+headers để phát hiện proxy/version mismatch.
+
+## Bước 2 — Tìm business trace trong PostgreSQL
+
+```sql
+SELECT created_at, query_text, subject_scope, query_intent, decision, reason,
+       resolved_drug_id, citations, correlation_id, otel_trace_id
+FROM rag_retrieval_trace
+WHERE trace_id = '<trace_id>'
+   OR correlation_id = '<correlation_id>'
+   OR otel_trace_id = '<otel_trace_id>'
+ORDER BY created_at DESC;
+```
+
+Xác nhận server đã resolve thuốc nào, decision/reason nào và citation nào thực sự
+được lưu. Không dựa riêng vào UI text.
+
+## Bước 3 — Mở distributed trace
+
+Trong Grafana → Explore → Tempo, tìm `otel_trace_id`. Đọc các span:
+
+- receive;
+- understanding;
+- routing/retrieval;
+- generation;
+- grounding/entailment;
+- persistence;
+- response.
+
+Xác định stage chiếm thời gian hoặc stage không xuất hiện. Provider call đang
+chạy không bị RequestBudget hủy giữa chừng; tổng latency có thể vượt budget bởi
+một call đã in-flight.
+
+## Bước 4 — Đối chiếu metrics
+
+Trong cùng time window, kiểm tra:
+
+```promql
+duocthu_requests_total
+duocthu_abstention_total
+duocthu_generation_rejected_total
+duocthu_stage_duration_seconds
+```
+
+Reason label giúp phân biệt availability failure (`provider_unavailable`,
+`request_budget_exhausted`) với content/grounding failure
+(`unsupported_claim`, `ungrounded_number`).
+
+## Bước 5 — Kiểm tra citation về source
+
+Với từng citation:
+
+1. lấy `chunk_id`, `drug_id`, `section_key` và `evidence_text`;
+2. xác nhận claim trỏ đúng thuốc và đúng section;
+3. mở `printed_page_start` trong PDF;
+4. nếu có attachment/bbox/crop, review ảnh gốc;
+5. nếu block quarantine, không cố suy số từ text flatten.
+
+## Bước 6 — Phân loại kết luận
+
+| Kết luận | Bằng chứng cần có |
+|---|---|
+| Retrieval sai | Resolved frame đúng nhưng evidence sai section/drug |
+| Understanding sai | QueryFrame/route chọn sai thuốc, relation hoặc population |
+| Provider outage | Span/provider error và metric availability tương ứng |
+| Grounding reject đúng | Generated claim vi phạm citation/number/entailment |
+| UI mapping sai | Backend response đúng nhưng message/citation render sai |
+| Trace persistence lỗi | Answer trả được nhưng không có PostgreSQL record |
+
+## Verify
+
+Một incident note hoàn chỉnh phải ghi ID, commit/deployment version, decision,
+reason, stage gây lỗi, evidence/citation liên quan và recovery đã thực hiện.
+
+## Liên quan
+
+- [Observability reference](../17-observability.md)
+- [Production operations](../24-production-operations.md)
+- [Generation and grounding](../11-generation-and-grounding.md)
+- [Troubleshooting](../25-troubleshooting.md)