Sổ lỗi tự động

Tầng 1 của NFR "học từ lỗi": mọi lỗi CI và lỗi runtime trên Cloudflare tự vào sổ, không cần ai nhớ đi rà. Sổ là issue GitHub nhãn error-ledger, một issue cho một dấu vân tay lỗi.

Chạy ở đâu

Nguồn	Khi nào	Lệnh
Lượt CI đỏ	Ngay khi một workflow kết thúc failure (on: workflow_run)	node scripts/error-ledger.mjs ci --run-id <id>
Lượt CI đỏ bị sót, kể cả startup_failure	Hằng ngày 08:30 giờ VN	node scripts/error-ledger.mjs sweep
Lỗi runtime Cloudflare (5xx của người đọc + exception Worker)	Hằng ngày 08:30 giờ VN	node scripts/error-ledger.mjs cloudflare

Workflow: .github/workflows/error-ledger.yml. Thêm --dry-run để đọc và in mà không ghi issue.

Dấu vân tay

sha256(nguồn | phạm vi | thông điệp đã chuẩn hoá), lấy 10 ký tự. Chuẩn hoá bỏ số, hash, uuid, dấu thời gian và hash tên file build, nên any-cast @ www: 194 -> 196 và 201 -> 203 là MỘT lỗi. Mẫu tự kiểm (--self-test) chạy trong job guards: dấu sai theo hướng nào cũng hỏng im lặng, quá chặt thì mỗi lần lặp thành issue mới, quá lỏng thì hai lỗi khác nhau gộp làm một.

Vòng đời một issue

1. Lần đầu gặp: tạo issue, ghi thông điệp và lần gặp.
2. Gặp lại khi còn mở: thêm một bình luận một dòng.
3. Sửa xong và có chốt chặn (gác, kiểm type, hook): đóng issue.
4. Gặp lại sau khi đã đóng: tự mở lại và gắn error-ledger-repeat. Nhãn này là thước đo của "cấm lặp lại": mỗi issue mang nó là một chốt chặn chưa đủ.

Báo động khi nguồn trống

Lệnh cloudflare thoát đỏ khi token thiếu quyền hoặc zone không có lượt truy cập nào trong 24 giờ. Trang Observability trống từng trông y như "không có lỗi" trong khi thật ra không Worker nào ghi log (sổ lỗi Cloudflare, C12). Nguồn trống phải là đỏ.

Token CLOUDFLARE_API_TOKEN của CI cần thêm hai quyền chỉ đọc: Account Analytics Read và Zone Analytics Read. Thiếu thì bước Cloudflare đỏ mỗi ngày, đúng như thiết kế.

Hai bẫy đã gặp khi dựng

• Search của GitHub nhất quán cuối. Issue vừa tạo chưa ra trong /search vài giây, nên một lượt quét gặp sáu startup_failure cùng dấu từng định tạo sáu issue. Script nhớ issue vừa tạo trong tiến trình.
• Dòng lỗi đầu tiên trong log thường là tiếng ồn (git fetch in -> origin/..., chữ "error" trong tên file). Dòng có nghĩa nằm ngay trước ##[error]Process completed with exit code.

Chưa làm

Thông điệp exception của Worker (stack) chưa vào sổ: GraphQL chỉ cho số lượng. Bước sau là đọc Workers Logs (đã bật cho mọi Worker từ 13.10.2026) qua API telemetry, hoặc một Tail Worker.

Xem thêm: sổ lỗi CI, sổ lỗi Cloudflare.