Giám sát và cảnh báo
Trang này nói cái gì đáng giám sát, đọc nó ở đâu, và ngưỡng nào đáng dựng cảnh báo — kèm ba loại hỏng hóc chết lặng mà health check trả 200 vẫn không phát hiện ra.
Đối tượng: sysadmin và SRE dựng giám sát cho một triển khai đang chạy. Điều kiện: hệ thống đã go-live theo Nghiệm thu trước go-live. Không nằm ở đây: deploy, backup, rollback → Vận hành và backup; checklist hằng ngày → Vận hành hằng ngày.
Bốn tầng cần nhìn
Sai lầm hay gặp nhất là chỉ giám sát tầng 1. Board cố ý vẫn trả 200 khi Arkon vắng mặt (suy biến mềm) — nghĩa là tầng 1 xanh trong khi tính năng tri thức đã tắt hoàn toàn.
Endpoint để thăm dò
| Endpoint | Trả gì | Dùng làm gì |
|---|---|---|
GET /api/health (Board) | {"status":"ok","timestamp":<ms>} | Liveness. Công khai, không cần auth — dùng được cho probe bên ngoài |
GET /health (Arkon) | {"status":"healthy|degraded","services":{"database":…,"redis":…,"minio":…}} | Readiness thật: kiểm từng phụ thuộc |
GET /api/features (Board) | 12 cờ dạng boolean | Xác nhận cờ thực sự tới được container, không phải chỉ nằm trong file .env |
GET /api/agents (Board) | Danh sách agent CLI server nhìn thấy | Danh sách rỗng = mọi task sẽ tạo được nhưng không chạy |
/api/health của Board không kiểm phụ thuộcNó trả ok kể cả khi Arkon chết. Muốn biết hệ thống có làm việc được không thì phải
thăm dò cả /health của Arkon và đọc services bên trong — degraded là tín hiệu
đáng cảnh báo dù HTTP vẫn 200.
Cảnh báo nên dựng
Bốn cái đầu là tối thiểu; ba cái sau bắt đúng loại hỏng chết lặng.
| # | Cảnh báo | Điều kiện | Vì sao đáng đánh thức người |
|---|---|---|---|
| 1 | Board chết | GET /api/health không 200 trong 2 lần thăm dò liên tiếp | Không ai giao được việc |
| 2 | Container không healthy | Bất kỳ container nào rời trạng thái healthy quá 5 phút | Compose không tự chữa vô hạn |
| 3 | Arkon degraded | GET /health trả status != healthy | Wiki và tìm kiếm ngữ nghĩa đang tắt lặng |
| 4 | Đĩa đầy | Còn dưới 15% | Worktree agent và MinIO ăn đĩa đều đặn; đầy đĩa làm hỏng cả Postgres |
| 5 | Không có agent CLI | GET /api/agents trả danh sách rỗng | Chết lặng: task tạo được, bấm Run không có gì xảy ra |
| 6 | Cờ lệch với chủ ý | GET /api/features khác cấu hình mong đợi | Chết lặng: cờ nằm trong .env nhưng chưa tới container thì tính năng coi như không tồn tại |
| 7 | WebSocket không nối được | Tỉ lệ upgrade thất bại tăng, hoặc log có IDENTITY_PENDING / FORBIDDEN liên tục | Chết lặng: giao diện vẫn dùng được nhưng không có cập nhật realtime |
Ba loại hỏng chết lặng
1. Wiki tắt mà không ai biết
Arkon vắng mặt → Board vẫn 200, nhưng agent chạy với .board/wiki/** rỗng và chất lượng kết quả tụt mà không có lỗi nào. Cách phát hiện:
# Trong worktree của một task vừa chạy: phải liệt kê được trang,
# không phải "No wiki pages available"
ls .board/wiki/
Xem thêm: Suy biến mềm Arkon.
2. Cờ chưa tới container
Đặt cờ trong file .env không có nghĩa là tiến trình đọc được nó. Server là nguồn chân lý, client chỉ đọc lại:
docker exec agentjira_server printenv | grep AGENTBOARD_
curl -s http://127.0.0.1:8080/api/features
Hai kết quả này phải kể cùng một câu chuyện. Lệch nhau nghĩa là bạn đang tin vào một tính năng chưa bật.
3. "Live" hiện nhưng không có gì cập nhật
Badge Live chỉ nói socket đã mở, không nói event có tới. Nguyên nhân hay gặp: AGENT_BOARD_PUBLIC_URL không nằm trong ALLOWED_HOSTS, hoặc bật AGENTBOARD_WS_TOPICS mà socket chưa vào room nào. Server từ chối khởi động khi hai biến này lệch — đó là chốt phòng ngừa, nhưng chỉ ở lúc boot.
Đọc log
Log của server có tiền tố theo hệ thống con — grep theo tiền tố nhanh hơn đọc tuần tự:
| Tiền tố | Nói về |
|---|---|
[server] | Vòng đời tiến trình, preflight lúc khởi động |
[agent-manager] | Bắt đầu/kết thúc một lần chạy agent, provider được chọn |
[identity] · [auth] | Phân giải danh tính, từ chối xác thực |
[approve] | Đường đi của Human Gate |
[rbac] | Cấp quyền lúc bootstrap |
[board-contract] | Bơm .board/ vào worktree, persona |
[group] · [epic-retro] · [rework-service] · [reviewer-agent] | Các dịch vụ tương ứng |
# Preflight sau mỗi lần deploy — đọc trước khi tuyên bố deploy thành công
docker compose -f docker-compose.prod.yml logs --tail=80 agentjira_server | grep -i preflight
# Vì sao một lần chạy hỏng
docker compose -f docker-compose.prod.yml logs agentjira_server | grep '\[agent-manager\]'
Preflight cảnh báo những thứ không làm sập tiến trình nhưng làm hỏng tính năng — ví dụ AGENTBOARD_LLM_MODE=replay (mặc định) khiến AI Planner báo Cassette cache miss với mọi yêu cầu mới. Đọc preflight là bước cuối của deploy, không phải việc tuỳ hứng.
Chỉ số nghiệp vụ đáng theo dõi
Không có endpoint đóng gói sẵn cho những chỉ số này — truy vấn thẳng database của Board:
| Chỉ số | Bất thường khi | Ý nghĩa |
|---|---|---|
Số task agentStatus = executing | Cao bất thường và không giảm | Agent kẹt, hoặc maxConcurrency đặt quá lớn |
Tuổi của task cũ nhất trong cột review | Vượt SLA duyệt của team | Hàng đợi Human Gate đang ứ — vấn đề con người, không phải máy |
Số task needs-human | Tăng dần | Mô tả task viết chưa đủ tốt, agent lặp tới ngưỡng 3 vòng rework |
Số Activity system_recovery | Xuất hiện | Server đã sập giữa lúc agent chạy; lease hết hạn và hệ thống tự phục hồi |
Xác minh giám sát của bạn có thật sự chạy
# 1. Liveness
curl -fsS http://127.0.0.1:8080/api/health
# 2. Readiness của Arkon — đọc cả phần services, không chỉ mã HTTP
curl -s http://127.0.0.1:5055/health
# 3. Cờ tới được container
curl -s http://127.0.0.1:8080/api/features
# 4. Có agent CLI nào không
curl -s http://127.0.0.1:8080/api/agents
# 5. Container nào không healthy
docker compose -f docker-compose.prod.yml ps
Bài kiểm tra thật cho hệ giám sát: tắt arkon_api rồi xem cảnh báo số 3 có kêu không. Cảnh báo chưa từng được kích hoạt thử là cảnh báo chưa biết có chạy hay không.
Đi tiếp: Vận hành hằng ngày · Vận hành và backup · Nghiệm thu trước go-live · Xử lý sự cố