Bài 3 — Observability: log, trace và metric cho agent

Bạn không thể vận hành thứ mình không nhìn thấy. Với agent, "nhìn thấy" khó hơn dịch vụ thường vì mỗi request có thể gồm nhiều bước LLM, nhiều tool call, và kết quả không xác định (non-deterministic). Bài này dạy bạn thiết lập ba lớp quan sát: logs, traces, metrics.

Ba lớp quan sát

• Logs: bản ghi chi tiết từng sự kiện (prompt, tool input/output, lỗi). Dùng để điều tra một ca cụ thể.
• Traces: nối các bước của một request thành chuỗi có quan hệ cha–con, kèm thời gian mỗi bước. Dùng để hiểu "agent đã suy nghĩ và gọi gì".
• Metrics: số tổng hợp theo thời gian (latency p95, tỷ lệ lỗi, token/request, chi phí). Dùng để cảnh báo và theo dõi xu hướng.

Ví dụ một trace của agent

trace_id=req-8f2a  user=carol
├─ plan            120ms   tokens=380
├─ tool: search_kb  40ms   hits=3
├─ tool: get_order 210ms   status=200
├─ generate        900ms   tokens=610
└─ guardrail_check  15ms   verdict=pass
total=1285ms  cost=$0.014  outcome=answered

Nhìn trace này bạn biết ngay bước generate chiếm phần lớn thời gian và token — nơi cần tối ưu. Không có trace, bạn chỉ thấy "request mất 1,3s" mà không biết vì sao.

Những trường tối thiểu phải log cho mỗi request

{
  "trace_id": "req-8f2a",
  "user_id": "hash(carol)",
  "model": "claude-x",
  "input_tokens": 990,
  "output_tokens": 610,
  "cost_usd": 0.014,
  "latency_ms": 1285,
  "tools_called": ["search_kb", "get_order"],
  "guardrail_verdict": "pass",
  "outcome": "answered",
  "error": null
}

Quy tắc vàng: luôn có trace_id xuyên suốt để nối log ↔ trace ↔ ticket hỗ trợ, và không log PII/secret thô (hãy hash hoặc che).

Khung tư duy: bốn tín hiệu vàng cho agent

• Latency — nhanh hay chậm (theo p50/p95, không chỉ trung bình).
• Errors — tỷ lệ lỗi tool, lỗi model, lỗi guardrail.
• Cost — token và chi phí mỗi request và tổng theo giờ.
• Quality — tỷ lệ kết quả bị guardrail chặn, tỷ lệ user hài lòng/leo thang.

Các bước làm

• Gắn trace_id ngay đầu mỗi request và truyền qua mọi bước/tool.
• Bọc mỗi lời gọi LLM và tool bằng một span ghi thời gian, token, kết quả.
• Chuẩn hóa schema log như JSON ở trên; xuất về một nơi tập trung (không rải rác print).
• Dựng dashboard cho bốn tín hiệu vàng, chia theo p50/p95.
• Che PII trước khi ghi; giữ log đủ dài để điều tra nhưng tôn trọng quyền riêng tư.

Checklist observability

• [ ] Mọi request có trace_id duy nhất, xuyên suốt các bước.
• [ ] Mỗi tool/LLM call là một span có thời gian và token.
• [ ] Dashboard hiển thị latency p95, error rate, cost, quality.
• [ ] Không có PII/secret thô trong log.
• [ ] Từ một ticket lỗi, tôi tìm được trace tương ứng trong < 1 phút.

Sai lầm thường gặp

• Chỉ log trung bình. p95 mới lộ ra đuôi chậm mà user thật cảm nhận.
• Log rời rạc bằng print. Không nối được các bước, điều tra như mò kim.
• Quên log token/chi phí. Đến khi hết ngân sách mới biết thì đã muộn.
• Ghi cả prompt chứa PII. Vi phạm quyền riêng tư và tạo rủi ro rò rỉ.

Có mắt nhìn rồi, bài sau ta biến quan sát thành hành động: đặt SLO và alert đúng chỗ.