Chuyển SDK Sentry: checklist thử từng giả định

Đổi DSN của Sentry chỉ mất một phút, nhưng vẫn có thể làm hỏng những thứ vài tuần sau mới có người để ý. Trước khi chuyển, hãy liệt kê các item SDK thật sự gửi và kiểm backend mới giữ lại loại nào. Sau đó thử dữ liệu cá nhân, check-in và source map, từng thứ một.

Checklist này đến từ một lần chạy ngày 26/10/2026 với SDK chính thức của Sentry cho Node.js. Backend mình đối chiếu là của Belvador vì mình đọc được mã nguồn của nó, nhưng các câu hỏi giống hệt với mọi dịch vụ tương thích Sentry.

Vì sao đổi DSN chưa phải là xong#

SDK của Sentry không gửi "lỗi". Nó gửi envelope, và mỗi envelope chứa các item có loại riêng: event, check_in, log, span, sessions, client_report và nhiều loại khác, như trong tài liệu về envelope item của Sentry. Một backend tương thích phải tự quyết làm gì với từng loại.

Hầu hết đều nhận lỗi. Ít bên hơn xử lý check-in, log hay sessions. Item nào backend không hỗ trợ thường bị bỏ đi mà ứng dụng không báo lỗi gì, nên chẳng có gì cho bạn biết một monitor hay một luồng log đã im lặng.

Lần chạy: một request, hai cấu hình#

Một server node:http nhỏ chạy @sentry/node 11.8.0 trên Node 22. Một request đi vào kèm Cookie, header Authorization và X-Forwarded-For: 203.0.113.7. Handler gọi Sentry.logger.info(), rồi bắt một lỗi và gọi captureException(). Sau request, một hàm bọc withMonitor() chạy một job ngắn.

Mình chạy với hai cấu hình, mỗi cấu hình ba lần:

• Kiểu Sentry: sendDefaultPii: true, tracesSampleRate: 1.0 và enableLogs: true, một tổ hợp hay gặp trong hướng dẫn cài đặt của Sentry.
• Cấu hình theo tài liệu Belvador: sendDefaultPii: false, tracesSampleRate: 0 và một hook beforeSend để lọc dữ liệu.

Một collector cục bộ ghi lại từng request, và cả ba lần chạy của mỗi cấu hình đều gửi cùng các item, cùng thứ tự.

SDK đã gửi những gì#

Cả hai cấu hình đều gửi sáu item cho một request và một job: hai check-in (bắt đầu và kết thúc), event lỗi, một log và một bản tóm tắt sessions. Cấu hình kiểu Sentry gửi thêm một span cho request. Cấu hình Belvador gửi client_report thay vào đó, đếm hai span bị bỏ vì tracing đang tắt.

Có hai kết quả làm mình bất ngờ:

• Log vẫn được gửi ở cả hai cấu hình. Mình không hề đặt enableLogs trong cấu hình Belvador, nhưng ở phiên bản 11.8.0, chính định nghĩa kiểu của SDK ghi tuỳ chọn này mặc định là bật, và ứng dụng có gọi Sentry.logger.info().
• sessions cũng được gửi ở cả hai cấu hình. Tuỳ chọn sessions của HTTP integration cũng mặc định là bật. Khi mình tắt nó trong lần chạy thứ ba, SDK lại gửi một item session đơn lẻ thay vào.

Trên node Belvador, event trở thành một issue, check-in cập nhật monitor, log vào kho log, còn client report được đếm. Hai item span và sessions được đếm là Chưa hỗ trợ rồi bỏ đi.

Dữ liệu cá nhân: kiểm event, đừng chỉ kiểm cấu hình#

Với sendDefaultPii: true, SDK đã tự lọc header cookie và authorization thành [Filtered]. Nó giữ x-forwarded-for: 203.0.113.7 và chép cùng địa chỉ đó vào user.ip_address. Với hook của Belvador, event không còn header nào trong ba header đó và không có user.

Vậy riêng sendDefaultPii: false chưa đủ. Hãy đọc một event thật từ backend mới và tìm header IP, cookie, token trong URL và email trong message. Bài thử bộ lọc PII cho thấy bộ lọc bắt được mẫu nào và bỏ sót mẫu nào.

Checklist#

1. Mỗi lúc chỉ chạy một SDK. Hai SDK cùng gắn vào bộ bắt lỗi toàn cục, nên mỗi lỗi tới hai lần.
2. Liệt kê các loại item bạn gửi. Trỏ DSN vào một collector cục bộ trong một lần chạy, hoặc đọc envelope trong tab Network của trình duyệt. So danh sách đó với những gì backend mới lưu.
3. Tắt thứ sẽ bị bỏ. Nếu dữ liệu tracing không được lưu, đặt tracesSampleRate: 0 để SDK khỏi làm việc thừa. Kiểm lại bằng collector, vì có item, như sessions, quay lại dưới dạng khác.
4. Đọc trọn một event đã lưu. Kiểm header, user, breadcrumb và URL xem có dữ liệu cá nhân không.
5. Chuyển check-in có chủ đích. Monitor ngừng nhận check-in trông y như một job bị lỡ. Tạo monitor trong backend mới trước, rồi mới đổi DSN.
6. Trỏ lại việc tải source map. Giữ sentry-cli, đổi URL và token, rồi kiểm một lỗi mới có hiện tên file gốc không. Bài về error boundary và lỗi async cho thấy lỗi frontend nào thật sự tới được công cụ.
7. Kiểm định dạng DSN. DSN có dạng {PROTOCOL}://{PUBLIC_KEY}@{HOST}/{PROJECT_ID}, và phần secret đã bị khai tử. Backend có thể khắt khe hơn Sentry: chính SDK của Belvador chỉ nhận key hex 32 ký tự.
8. Chứng minh lỗi tới từ production. Gửi một lỗi thử có tag từ mỗi runtime sau khi deploy, và chờ một lỗi thật trước khi tắt công cụ cũ.
9. Tính trước chuyện lịch sử. Issue cũ ở lại công cụ cũ. Giữ nó ở chế độ chỉ đọc vài tuần nếu bạn cần tra cứu.

Belvador nằm ở đâu#

Belvador nhận envelope của Sentry và lưu event, attachment, check-in cùng log của Sentry trên một node trong dự án Hetzner của bạn; dữ liệu tracing đi qua OpenTelemetry. Hướng dẫn chuyển đổi ghép từng gói và tuỳ chọn của Sentry. Phần cài đặt Node.js có hook lọc mình dùng ở đây, còn monitor với SDK Sentry nói về withMonitor(). Trang thay thế Sentry liệt kê những gì Belvador không làm.

Đọc tiếp#

• Thay thế Sentry cho ứng dụng do AI xây dựng: kiểm gì trước khi chuyển
• Lọc PII trong error monitoring mà không mất ngữ cảnh
• Error boundary của React và lỗi async: thí nghiệm bắt được gì