Kiểm tra kết nối

"Không có lỗi" có thể là app khoẻ — hoặc là lỗi của app không bao giờ tới Belvador. Phép kiểm kết nối chứng minh, theo từng môi trường chạy, rằng lỗi từ app tới đúng project. Phép kiểm gửi một hoặc hai lỗi có đánh dấu, không bao giờ thành issue, và Belvador hiện kết quả ở tab Kết nối của project.

Vì sao issue đầu tiên chưa đủ#

Issue đầu tiên chỉ chứng minh một lỗi đã tới một lần. Nó không chứng minh rằng:

• phía máy chủ cũng báo lỗi, không chỉ trình duyệt;

• lỗi không bắt (lỗi không ai bọc trong try … catch) có được báo;

• code máy chủ chạy trong middleware của Belvador, nên lỗi được thấy trước khi trang lỗi nuốt mất;

• app vẫn dùng khoá DSN còn hiệu lực sau mỗi lần deploy.

Phép kiểm phủ từng ý trên và lưu kết quả, để cả nhóm thấy lần cuối được chứng minh là khi nào.

Tab Kết nối hiện gì#

Mở project và chọn Kết nối. Với mỗi môi trường nền tảng cần — Trình duyệt, Máy chủ, hoặc cả hai với TanStack Start — bạn thấy:

Sự cố đang mở hiện trên cùng kèm việc cần làm. Sự cố tự đóng khi nguyên nhân hết; quy tắc cảnh báo Sự cố kết nối SDK gửi một tin khi sự cố bắt đầu và một tin khi đã hết — xem Cảnh báo.

Kiểm bằng verifyIntegration()#

Từ @belvador/* 0.2.0, một lời gọi chạy mọi phép kiểm cho môi trường nơi nó được gọi và đọc lại kết quả từ Belvador. Hàm không bao giờ ném lỗi và không tự chạy — hãy chạy một lần sau khi cài và sau những lần deploy đụng tới xử lý lỗi, đừng chạy mỗi lần tải trang.

Trình duyệt#

import { verifyIntegration } from "@belvador/react";// Run once after setup or deploy (for example behind a debug flag), never on every page load.// The console shows one expected "Belvador verification (uncaught)" error — that is the test.const result = await verifyIntegration();// result.outcome: "verified" | "problem" | "unconfirmed"; the console prints one summary line.

Lời gọi tương tự có trong @belvador/browser và @belvador/tanstack-start/client. Console trình duyệt sẽ hiện một lỗi có chủ đích, "Belvador verification (uncaught, expected)": phép kiểm cố ý ném lỗi này để chứng minh lỗi không bắt được báo. Truyền { uncaught: false } để bỏ phần đó; khi ấy trình duyệt chỉ được kiểm đường gửi.

Máy chủ (TanStack Start)#

import { createFileRoute } from "@tanstack/react-router";import { verifyIntegration } from "@belvador/tanstack-start/server";// Temporary: open /api/verify-belvador once after deploying, then delete this file.// It must run inside belvadorRequestMiddleware (src/start.ts) — that is part of the check.export const Route = createFileRoute("/api/verify-belvador")({  server: {    handlers: {      GET: async () => Response.json(await verifyIntegration()),    },  },});

Mở /api/verify-belvador một lần sau khi deploy, đọc JSON trả về, rồi xoá tệp. Phép kiểm báo BLV_HOOK_MISSING nếu route không chạy trong belvadorRequestMiddleware.

Cloudflare Workers#

import { verifyIntegration } from "@belvador/cloudflare";// Inside the fetch handler wrapped by withBelvador. Temporary: remove after the check.if (new URL(request.url).pathname === "/__belvador/verify") {  return Response.json(await verifyIntegration());}

Đọc kết quả#

verifyIntegration() trả về một object và in một dòng, ví dụ:

[belvador] verify server: problem — hook missing (BLV_HOOK_MISSING), delivery confirmed — bv1_3f0c… — https://belvador.dev/en/docs/sdk/verify#blv-hook-missing

Tuỳ chọn: timeoutMs (mặc định 20000 ms, tối đa 30000), uncaught (trình duyệt, mặc định true), readback (mặc định true). Mỗi lời gọi gửi tối đa 2 event và hỏi Belvador tối đa 10 lần.

Mọi SDK: gửi một lỗi có gắn thẻ#

Mọi SDK tương thích Sentry đều chạy được phép kiểm — @belvador/* 0.6.1 cũng vậy. Gửi một lỗi có tag belvador.verification mang giá trị bv1_ và 32 ký tự hex chữ thường, rồi đọc lại.

Gói Belvador trước 0.2.0#

import { captureException, flush, withScope } from "@belvador/react";// One-time connection check: a marked error that never becomes an issue.const id = "bv1_" + crypto.randomUUID().replaceAll("-", "");withScope((scope) => {  scope.setTag("belvador.verification", id);  captureException(new Error("Belvador verification"));});await flush(5000);console.log("[belvador] verification id:", id);

Node.js#

import * as Sentry from "@sentry/node";// One-time connection check: a marked error that never becomes an issue.const id = "bv1_" + crypto.randomUUID().replaceAll("-", "");Sentry.withScope((scope) => {  scope.setTag("belvador.verification", id);  Sentry.captureException(new Error("Belvador verification"));});await Sentry.flush(5000);console.log("[belvador] verification id:", id);

Python#

import uuidimport sentry_sdk# One-time connection check: a marked error that never becomes an issue.verification_id = "bv1_" + uuid.uuid4().hexwith sentry_sdk.new_scope() as scope:    scope.set_tag("belvador.verification", verification_id)    sentry_sdk.capture_exception(Exception("Belvador verification"))sentry_sdk.flush(5)print("[belvador] verification id:", verification_id)

Đọc lại#

curl -s "https://ingest.belvador.dev/api/<project-id>/verification/bv1_<id printed by your app>/?sentry_key=<public-key>"

Dùng số project và khoá công khai trong DSN. Kết quả liệt kê các phép kiểm đã tới node:

{ "v": 1, "verification_id": "bv1_…", "node": "connected", "checks": [{ "surface": "server", "check": "delivery", "hook": "unknown" }] }

Lỗi gắn thẻ chỉ chứng minh đường gửi: SDK Sentry thông thường không cho biết móc lỗi của nó có chạy hay không, nên tab Kết nối hiện chỉ kiểm đường gửi cho môi trường đó.

Mã chẩn đoán của SDK#

SDK báo các mã này ngay trong app — ở console trình duyệt khi bật debug: true, hoặc qua callback onDiagnostic của bạn — tối đa một lần mỗi phút cho mỗi mã. Chúng không bao giờ được gửi về Belvador.

init({  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",  onDiagnostic: (d) => console.warn(d.code, d.count, d.status),});// getDiagnostics() trả về ảnh chụp: đang chạy, tên SDK, host + project + gợi ý khoá DSN, lần gửi cuối, số đếm.

BLV_DSN_MISSING#

init() không nhận được DSN nên SDK tắt. Chép DSN từ trang project.

BLV_DSN_INVALID#

DSN không đúng dạng DSN Belvador (https://<32 hex>@host/<project>). SDK tắt. Chép lại DSN, không thêm query string.

BLV_INIT_CONFLICT#

Trang đã có một client theo dõi lỗi khác nên Belvador không khởi động. Gỡ Sentry.init cũ để lỗi không bị báo hai lần.

BLV_NOT_INITIALIZED#

captureException chạy khi SDK đang tắt — trước init(), hoặc sau khi init() thất bại. Gọi init() càng sớm càng tốt.

BLV_SEND_UNAUTHORIZED#

Belvador từ chối khoá DSN (đã thu hồi, hết hạn hoặc của project khác). SDK ngừng gửi tới khi trang hoặc Worker tải lại. Dùng khoá còn hiệu lực trong Cài đặt project → Khoá DSN.

BLV_SEND_RATE_LIMITED#

Project chạm giới hạn tốc độ hoặc hết hạn mức tháng; event bị bỏ tới khi hết thời gian chờ (retryAfterS). Xem giới hạn nhận lỗi.

BLV_SEND_REJECTED#

Một event không được nhận — thường do quá lớn. Giữ dữ liệu phụ và tệp đính kèm nhỏ.

BLV_SEND_NETWORK#

Không tới được Belvador sau khi thử lại. Kiểm tra mạng, trình chặn quảng cáo và connect-src của Content-Security-Policy có cho phép https://ingest.belvador.dev.

BLV_SEND_SERVER#

Belvador trả lỗi máy chủ sau khi thử lại. Thường chỉ tạm thời; nếu kéo dài, xem trạng thái node.

BLV_QUEUE_FULL#

Quá nhiều event chờ gửi cùng lúc nên một event bị bỏ. Giảm lỗi lặp dồn dập bằng ignoreErrors hoặc sampleRate.

BLV_EVENT_TOO_LARGE#

Một event hoặc tệp đính kèm vượt giới hạn kích thước và bị bỏ trước khi gửi — xem Cấu hình SDK.

BLV_HOOK_MISSING#

Phép kiểm chạy trong code máy chủ không nằm trong middleware hay Worker wrapper của Belvador, nên lỗi ném ở đó không được báo tự động. Đăng ký belvadorRequestMiddleware và belvadorFunctionMiddleware ở cuối danh sách trong src/start.ts — xem TanStack Start — hoặc bọc Worker bằng withBelvador.

BLV_DROPPED_BY_APP#

Phép kiểm chưa rời khỏi app: beforeSend của bạn trả null, ignoreErrors khớp với nó, hoặc sampleRate dưới 1 đã bỏ nó. Hãy cho lỗi tên BelvadorVerificationError đi qua.

BLV_MONITOR_INVALID_SLUG#

Slug của monitor chỉ gồm chữ thường, số, - và _, tối đa 64 ký tự (ví dụ nightly-invoices). Công việc vẫn chạy; không có check-in nào được gửi cho nó — xem Monitor.

BLV_MONITOR_INVALID_REASON#

Lý do truyền vào run.skip(), run.unknown() hoặc captureCheckIn phải là mã ngắn như provider_timeout, không phải câu thông báo. Lý do đã bị bỏ khỏi check-in.

BLV_MONITOR_CONFIG_INVALID#

Lịch hoặc một cài đặt truyền vào withMonitor không hợp lệ (crontab không đúng 5 trường, múi giờ lạ, số ngoài khoảng cho phép). Check-in vẫn được gửi nhưng không kèm cấu hình, nên cài đặt của monitor không đổi.

BLV_CHECK_IN_DROPPED#

Một check-in không được gửi: quá nhiều check-in chờ cùng lúc (tối đa 10 trong 30 lượt gửi đang chờ), check-in bị giới hạn tốc độ, hoặc mạng lỗi. Lỗi (error) không bị ảnh hưởng. Nếu lặp lại, monitor có thể hiện "trễ" — xem lại tần suất công việc báo về.

BLV_TRACE_TARGET_INVALID#

Một mục trong tracePropagation.targets không phải chuỗi hay biểu thức chính quy nên bị bỏ qua; request tới đó không được gắn header trace.

BLV_OTEL_INVALID#

Tuỳ chọn otel.api không phải module @opentelemetry/api (truyền import * as api from "@opentelemetry/api", đúng bản mà OpenTelemetry SDK của app đang dùng). Cầu nối tắt; lỗi vẫn được ghi nhận nhưng không kèm id của span.

BLV_TRACE_OWNER_OTEL#

Đặt cả otel lẫn tracePropagation. OpenTelemetry đã tự truyền trace nên Belvador không gắn header trace riêng và bỏ qua tracePropagation. Xoá tracePropagation để hết thông báo này.

BLV_PRIVACY_POLICY_INVALID#

Từ SDK 0.6.0. privacyPolicy() nhận JSON không phải chính sách hợp lệ từ trang Quyền riêng tư của project (sai schema, pattern không an toàn, selector sai). App vẫn gửi nhưng không áp luật của project; node vẫn áp chính sách hiện tại của project trước khi lưu. Sao chép lại bằng "Sao chép dạng code".

BLV_PREVIEW_ONLY#

Từ SDK 0.6.0. Đang bật chế độ xem trước (preview: true hoặc BELVADOR_PREVIEW=1): mỗi envelope được in ra sau khi đã áp mọi luật và bộ che, và không gửi gì. Lần kiểm tra kết nối trong chế độ này không tới Belvador. Tắt xem trước để gửi.

BLV_OFFLINE_UNAVAILABLE#

Từ SDK 0.6.0. Đã đặt offline: true nhưng trình duyệt này không dùng được IndexedDB (một số cửa sổ ẩn danh, chính sách chặn lưu trữ) hoặc không tải được module offline (CSP chặn chunk của chính app). Lỗi vẫn được gửi nhưng không có hàng đợi offline: lỗi nào hỏng mạng khi gửi thì mất. Xem Offline và gửi bền.

Mã sự cố kết nối#

Belvador mở các sự cố này từ những gì edge thấy và từ phép kiểm. Mỗi sự cố ghi rõ project và, khi áp dụng, môi trường chạy.

INTEGRATION_KEY_INACTIVE#

App vẫn gửi bằng khoá DSN đã thu hồi hoặc hết hạn; các lỗi đó bị từ chối. Đặt DSN còn hiệu lực vào app rồi deploy lại.

INTEGRATION_ORIGIN_BLOCKED#

Lỗi tới từ website không có trong Tên miền cho phép của project. Thêm domain, hoặc để trống danh sách để nhận mọi domain.

INTEGRATION_RATE_LIMITED#

Nhiều lỗi bị bỏ vì giới hạn tốc độ của project. Nâng giới hạn trong Cài đặt project hoặc giảm lỗi lặp.

INTEGRATION_QUOTA_EXCEEDED#

Workspace đã dùng hết hạn mức tháng; lỗi bị bỏ tới đầu tháng sau.

INTEGRATION_TOO_LARGE#

Nhiều payload quá lớn. Tắt tệp đính kèm lớn và giữ dữ liệu phụ nhỏ.

INTEGRATION_INVALID_EVENTS#

Node không đọc được một số payload — thường do SDK không được hỗ trợ hoặc transport tự viết.

INTEGRATION_BUFFER_LOSS#

Node offline đủ lâu để lỗi đang chờ hết hạn hoặc phòng chờ đầy. Đưa node trở lại từ trang Node.

INTEGRATION_SDK_DROPS#

SDK trong app báo không gửi được lỗi (mạng, CSP hoặc hàng đợi đầy). Bật debug để thấy lý do trong console.

INTEGRATION_HOOK_MISSING#

Một phép kiểm máy chủ chạy ngoài middleware của Belvador — xem BLV_HOOK_MISSING ở trên.

INTEGRATION_UNCAUGHT_MISSING#

Một phép kiểm trình duyệt báo trước một lỗi không bắt nhưng lỗi đó không tới trong 2 phút: có thứ thay thế window.onerror hoặc init() chạy quá muộn.

Giới hạn#

• Một phép kiểm chứng minh đúng đường nó đã chạy, tại thời điểm đó. Những chỗ code tự bắt lỗi vẫn cần captureException.

• Lỗi không bắt ở trình duyệt được cố ý ném trong setTimeout; bạn có thể thấy nó trong console và trong tiện ích trình duyệt theo dõi lỗi.

• Phép kiểm bị giới hạn theo project (60 lần mỗi giờ) và theo khoá (30 lần đọc lại mỗi phút). Phép kiểm không bao giờ tính là issue và chỉ được giữ dạng metadata trong 30 ngày.

• Node cần phiên bản 0.1.17 trở lên để nhận biết phép kiểm; node cũ hơn hiện banner trên tab Kết nối.