# 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)