Building observability into Notion's dead-letter queue

Notion · 2026 · 3. Quy mô lớn · Độ khó: Cơ bản — bài gốc

Bối cảnh

Gần như mọi thao tác ở Notion có một task nền chạy qua job queue: thông báo khi bị @-mention, index trang cho search, sinh embedding, đồng bộ lịch, export workspace. Queue phân phối việc sao cho không workspace hay team nào chiếm hết worker.
Task thử hết số lần retry thì vào dead-letter queue (DLQ): một bản ghi DeadTask ghi vào bucket S3 riêng của mỗi cell, chứa tên event, task group, workspace ID, actor, toàn bộ payload JSON, cell đích, loại lỗi, stack trace, thời điểm enqueue, số lần thử, thời điểm vào DLQ.
Trước đây cách duy nhất để xem DLQ là AWS CLI với quyền đọc S3 trực tiếp: cần đúng credentials, biết bucket nào, tự viết query. Theo Notion, nhiều lỗi không được điều tra kỹ vì quá phiền; quyền S3 rộng lại là thứ họ đang muốn thu hẹp.

DLQ Explorer, mục tiêu là xem và cứu task chết dễ như mọi bề mặt production khác, không thêm pipeline dữ liệu mới.
Tầng dữ liệu: Athena với partition projection ngay trên bucket S3 có sẵn; mỗi cell một external table (dead_tasks_{cellId}) trong Glue database theo region, partition theo ngày và giờ để cắt bớt dữ liệu trước khi quét. Không dựng index phụ hay ETL. Mỗi region một Athena workgroup và bucket kết quả riêng. Phần khó nhất là IAM/KMS chạy nhất quán giữa môi trường và region, không thiếu quyền mà cũng không thừa.
Tầng query: bắt buộc chọn cell, môi trường, khoảng thời gian; lọc tuỳ chọn theo tên event (prefix), workspace ID, text tự do. Áp partition pruning trước mọi bộ lọc để query luôn có giới hạn. Có tổng hợp theo mẫu lỗi và số dòng chính xác, theo đúng cách debug: nhìn rộng, tìm mẫu, rồi thu hẹp.
Tầng phục hồi: chọn task rồi Re-enqueue, bắt buộc nhập lý do; handler dùng lại helper retryDeadTasks() có sẵn, stream task từ S3 và gửi theo batch vào overflow SQS queue của cell. Mọi lần re-enqueue được ghi lại (ai, cell nào, loại event, lý do) để biết task đã thử lại chưa và làm vết kiểm toán cho task có side effect.

Điều tra một đợt tăng task chết từ khoảng 20 phút xuống dưới 1 phút; nhiều team đã dùng đều.

DLQ chỉ có giá trị khi có người xem và replay được; công cụ xem khó dùng thì lỗi bị bỏ qua (Event-driven, message queue và Kafka).
Bản ghi dead task nên mang đủ ngữ cảnh (payload, lỗi, số lần thử, cell) để không cần đi tìm ở chỗ khác.
Query thẳng trên dữ liệu đang có (Athena trên S3) thay vì dựng pipeline mới; ép điều kiện partition để chi phí có giới hạn.
Replay là thao tác có side effect: cần lý do, lịch sử và vết kiểm toán (Nền tảng nội bộ cho service (đường ray chung)).