Khắc phục sự cố

Làm theo mục khớp với điều bạn đang thấy. Phần lớn vấn đề được tìm ra trong ba bước kiểm tra đầu tiên.

Không thấy lỗi nào về#

1. SDK có đang chạy không?#

• init trả về true khi đang chạy. Tạm thêm debug: true: SDK sẽ ghi các quyết định của nó ra console, kể cả khi DSN sai.

• DSN phải là DSN của đúng project này, sao chép nguyên vẹn: https://<public-key>@ingest.belvador.dev/<project-id>. Không có dấu nháy bên trong, không có dấu / ở cuối.

• disabled: true, BELVADOR_DISABLED=1 hoặc sampleRate: 0 sẽ tắt việc gửi.

2. Request có rời khỏi ứng dụng không?#

Trên trình duyệt, mở tab Network và tạo một lỗi thử. Tìm request POST tới https://ingest.belvador.dev/api/<project-id>/envelope/.

• Không có request nào — lỗi đã bị bắt trước khi SDK thấy (xem Lỗi do framework xử lý), hoặc init chưa chạy.

• Bị CSP chặn — console báo vi phạm Content-Security-Policy. Thêm https://ingest.belvador.dev vào connect-src.

• Bị trình chặn quảng cáo hoặc chặn theo dõi chặn — request thất bại, không có mã trạng thái. Thử bằng một hồ sơ trình duyệt sạch.

3. Edge trả lời gì?#

Sau 401 hoặc 403, SDK của Belvador ngừng gửi trong suốt vòng đời của trang hoặc isolate Worker đó — tải lại trang sau khi sửa.

4. Đã nhận nhưng không thấy?#

• Xem Cài đặt project → Lượng lỗi nhận 24 giờ qua: nếu Đã nhận tăng, lỗi đã tới Belvador.

• Node có Khoẻ không? Nếu Mất kết nối, lỗi được giữ ở edge và sẽ hiện khi node kết nối lại — xem Sức khoẻ node.

• Kiểm tra bộ lọc issue: mặc định là trạng thái Chưa xử lý và khoảng 24 giờ, và bộ lọc môi trường có thể đang ẩn môi trường của bạn.

• Đó có phải dữ liệu tracing hay session chứ không phải lỗi? Những thứ đó được đếm vào Chưa hỗ trợ và không được lưu.

Tab Kết nối báo Chưa kiểm hoặc Đang có vấn đề#

Chưa kiểm nghĩa là chưa có phép kiểm kết nối nào tới — chạy phép kiểm cho nền tảng của bạn trong Kiểm tra kết nối. Đang có vấn đề liệt kê điều gì sai và cần làm gì; mọi mã đều được giải thích ở trang đó. Khi bật debug: true, SDK cũng in mã chẩn đoán trong console.

Kiểm đường nhận không bao giờ tới#

Kiểm đường nhận ở tab Kết nối gửi một event từ node qua đường nhận lỗi công khai; nó không kiểm app. Nếu sau khoảng 10 giây vẫn chưa tới, thường là node chưa kết nối: mở Node và xem trạng thái.

Lỗi do framework xử lý không bao giờ về#

Framework thường bắt lỗi để hiện màn hình lỗi đẹp — khi đó SDK không bao giờ thấy lỗi.

TanStack Start: chỉ thấy lỗi trình duyệt#

• belvadorRequestMiddleware và belvadorFunctionMiddleware phải nằm cuối requestMiddleware và functionMiddleware.

• src/server.ts phải bọc đúng entry đang phục vụ request, và vite.config.ts phải trỏ tanstackStart.server.entry tới đó.

• Worker cần nodejs_compat.

• Không báo theo thiết kế: redirect(), notFound(), lỗi có mã dưới 500, và response 500 bạn tự trả về mà không ném lỗi.

• Lỗi trong loader của route khi render trên máy chủ thường chỉ được báo từ trình duyệt — đây là giới hạn đã biết.

Mỗi lỗi về hai lần#

• Cài đặt @sentry/* cũ hoặc lời gọi Sentry.init vẫn chạy song song với Belvador. Hãy gỡ đi.

• Cùng một lỗi được hai hook của bạn báo, ví dụ một try … catch gọi captureException rồi ném lại lỗi lên một boundary cũng báo. Chỉ báo ở một chỗ.

• Hai project cùng nhận một ứng dụng vì có hai DSN được cấu hình ở hai file khác nhau.

Lỗi bị gom nhóm sai#

• Quá nhiều issue riêng cho một bug: message chứa giá trị mà Belvador không chuẩn hoá — đặt fingerprint.

• Nhiều bug khác nhau trong một issue: chúng dùng chung một stack, ví dụ một hàm xử lý lỗi chung. Báo với fingerprint hoặc loại exception cụ thể hơn.

Stack trace hiện code thu nhỏ#

Xem Source map: release phải khớp, file đã triển khai phải là bản đã ghi Debug ID, và việc tải lên phải thành công.

Dữ liệu nhạy cảm xuất hiện trong event#

1. Đổi bí mật bị lộ trước tiên. Xoá khỏi Belvador không làm mất việc nó đã bị lộ.

2. Kiểm tra Project → Quyền riêng tư → Bộ dò có sẵn: mọi nhóm nên được bật.

3. Tìm xem nó đến từ đâu — tag, ngữ cảnh, message hay tệp đính kèm — rồi ngừng gửi, hoặc bỏ đi trong beforeSend.

4. Đọc những gì bộ lọc không đảm bảo.

429: quá nhiều request#

Monitor không có lượt chạy nào#

1. Chạy job một lần và xem output: với debug: true SDK ghi BLV_MONITOR_INVALID_SLUG, BLV_MONITOR_INVALID_REASON hoặc BLV_MONITOR_CONFIG_INVALID khi từ chối gửi.

2. Kiểm slug trên trang Monitor khớp từng ký tự với slug trong code, và cùng project.

3. Check-in từ trình duyệt bị từ chối có chủ đích. Hãy gửi từ máy chủ hoặc bằng curl — xem Check-in qua HTTP.

4. Với curl, đọc mã trả về: 401 là sai khoá hoặc sai project, 429 là bị giới hạn tốc độ.

5. Slug chưa thành monitor sẽ hiện ở Phát hiện từ code khi project không cho tạo monitor từ code.

Monitor ghi Không quan sát được#

Belvador không theo dõi được khoảng thời gian đó: node mất kết nối hoặc đang bắt kịp, hoặc check-in bị giới hạn tốc độ hay vượt hạn mức tháng. Các lượt trong khoảng đó không bị tính là lỡ. Khi node trở lại, nó chờ tối đa 10 phút để nhận check-in còn đợi, rồi đánh giá lại. Xem Khi Belvador không nhìn thấy.

Monitor ghi Bị lỡ nhưng job đã chạy#

• Job có thể báo về môi trường khác với môi trường monitor theo dõi: xem các tab môi trường trên monitor.

• Múi giờ của lịch có thể khác múi giờ của trình lập lịch. Form tạo monitor hiện các hạn kế tiếp theo cả múi giờ của monitor và của bạn.

• Biên độ có thể quá ngắn so với độ trễ khởi động của job; hãy tăng Biên độ.

429 với check-in#

Check-in có giới hạn riêng, tách khỏi lỗi: 60 mỗi monitor và môi trường mỗi phút, cộng hạn mức tháng theo gói. Vòng lặp gửi một check-in cho mỗi phần tử nên chuyển sang một heartbeat mỗi lô — xem Theo dõi việc chạy ngầm.

Lỗi CORS sau khi bật trace#

API ở origin khác phải cho phép traceparent và sentry-trace trong Access-Control-Allow-Headers. Thu hẹp tracePropagation.targets về API của chính bạn, hoặc cho phép các header — xem Liên kết lỗi qua nhiều tầng.

Node không khoẻ#

Xem Sức khoẻ node cho mọi trạng thái và lý do. Nếu máy đã mất, dùng Thay máy & khôi phục — Cập nhật và dựng lại.

Đăng nhập và xác thực 2 lớp#

• “Phiên đăng nhập đã hết. Hãy đăng nhập lại.” — đăng nhập lại; phiên có thời hạn.

• Mất ứng dụng xác thực — dùng mã khôi phục trên màn hình nhập mã: Bảo mật tài khoản.

• “Mã không đúng hoặc đã hết hạn.” — kiểm tra đồng hồ điện thoại đang đặt tự động; mã phụ thuộc vào thời gian.

• “Thao tác này cần xác thực 2 lớp.” — bật xác thực 2 lớp trong Bảo mật tài khoản, rồi thử lại.

Thông báo có thể gặp#

Lỗi trong ứng dụng có kèm mã tham chiếu. Nếu liên hệ hỗ trợ qua hello@belvador.dev, hãy gửi kèm mã đó — không bao giờ gửi token, mật khẩu hay mã khôi phục.