Độ phủ: từng phần của app có đang được theo dõi thật không

Khai báo mỗi phần của app phải gửi gì, Belvador đối chiếu với thứ thật sự nhận được: đã xác minh, cũ, có vấn đề hay chưa biết; quản lý bằng code từ CI.

Bản Markdown

Trong bài này

Trạng thái
Mỗi phần gửi được gì
Belvador biết phần nào đã gửi bằng cách nào
Khai báo kỳ vọng
Thấy nhưng chưa khai báo
Quản lý bằng code
Từ AI agent
Những gì rời khỏi node

Độ phủ trả lời trung thực một câu hỏi: từng phần của app có thật sự đang được theo dõi không? Bạn khai báo app cần gửi gì — ví dụ lỗi trình duyệt và server ở production, check-in của job chạy mỗi đêm — và Belvador đối chiếu từng khai báo với những gì thật sự tới. Không có lỗi không bao giờ được tính là đã kết nối: tín hiệu chưa từng tới là chưa biết, không phải ổn.

Mở Độ phủ trong workspace để xem mọi project cùng lúc, hoặc Project → Độ phủ để sửa kỳ vọng của một project. Viewer xem được; thành viên trở lên sửa được.

Trạng thái#

Mỗi tín hiệu đã khai báo có một trạng thái, tính ở một nơi duy nhất phía Belvador — trang, API và công cụ MCP get_coverage cho ra cùng con số.

Trạng thái	Nghĩa là
Đã xác minh	Dữ liệu thật hoặc biên nhận xác minh đã tới từ đúng phần đó của app, đúng môi trường, trong cửa sổ coi là cũ sau (mặc định 168 giờ)
Cũ	Từng tới, nhưng không trong cửa sổ — có thể có gì đó đã ngừng gửi
Có vấn đề	Đang có sự cố kết nối liên quan, ví dụ SDK báo bị bỏ event; trạng thái này thắng dữ liệu mới cho tới khi sự cố được xử lý
Chưa biết	Chưa từng có gì tới

Tỷ lệ ở đầu trang — 34/41 kỳ vọng đã xác minh — chỉ đếm tín hiệu đã xác minh. Cũ, có vấn đề và chưa biết không bao giờ được tính là đã phủ.

Mỗi phần gửi được gì#

Một kỳ vọng là một môi trường × một phần (surface) của app × các tín hiệu phần đó cần gửi:

Phần của app	Lỗi (`errors`)	Traces (`traces`)	Logs (`logs`)	Metrics (`metrics`)	Check-in (`check_ins`)	Web vitals (`web_vitals`)	Kiểm uptime (`probes`)
Trình duyệt (`browser`)	có	có	có	—	—	sau (chưa thu)	—
Server (`server`)	có	có	có	có	—	—	—
Worker (`worker`)	có	có	có	có	—	—	—
Job (`job`)	có	có	có	—	có	—	—
Edge function (`edge_function`)	có	có	có	có	—	—	—
Database (`database`)	—	có	—	có	—	—	—
Uptime (`uptime`)	—	—	—	—	—	—	có

Metrics được tính khi node chạy agent 0.1.37 trở lên (Metrics); trên node cũ hơn, ô metrics giữ Chưa biết. Web vitals có trong từ vựng nhưng Belvador chưa thu thập, nên chưa khai báo được — độ phủ không hứa điều chưa đo được.

Belvador biết phần nào đã gửi bằng cách nào#

Node của bạn xác định phần (surface) của từng lỗi, span, log và check-in nó lưu, dựa trên thông tin các SDK chuẩn vốn đã gửi:

Lỗi (Sentry SDK): lỗi trong một job có monitor (contexts.monitor) → job; SDK trình duyệt → trình duyệt; task hàng đợi (contexts.trace.op bắt đầu bằng queue.) → worker; hàm serverless (SDK Cloudflare, Vercel Edge, AWS Lambda, Google Cloud Functions, hoặc cloud.platform / faas.trigger theo quy ước FaaS của OpenTelemetry) → edge function — trigger timer tính là job, pubsub là worker; còn lại → server.
Trace và log (OpenTelemetry): SDK trình duyệt (telemetry.sdk.language = webjs) → trình duyệt; thuộc tính FaaS như trên → edge function; span consumer có messaging.system → worker; span có db.system.name được tính thêm là trace của database. Dữ liệu thiếu deployment.environment.name được tính là production, giống Sentry SDK.
Check-in → job. Uptime lấy từ các kiểm tra uptime của bạn.

Khai báo kỳ vọng#

Mở Project → Độ phủ.
Project chưa khai báo gì sẽ có bộ gợi ý theo framework — với TanStack Start là lỗi trình duyệt và server ở môi trường chính. Chọn Dùng gợi ý, hoặc Thêm kỳ vọng.
Chọn môi trường đúng như SDK gửi, chọn phần và tín hiệu. Coi là cũ sau là bao lâu không có bằng chứng thì chuyển sang cũ (1–720 giờ): chọn dài hơn khoảng cách thường gặp giữa hai lần có dữ liệu thật — job chạy mỗi đêm cần khoảng 26.

Xác minh ngay trên một tín hiệu mở bước kiểm tra kết nối của project cho môi trường đó: chạy xong, biên nhận tới là tín hiệu chuyển sang đã xác minh.

Thấy nhưng chưa khai báo#

Tín hiệu Belvador thấy trong 30 ngày qua mà chưa có kỳ vọng nào được liệt kê ở Thấy nhưng chưa khai báo, kèm nút Thêm vào kỳ vọng. Chúng không làm đổi tỷ lệ cho tới khi bạn khai báo.

Quản lý bằng code#

Giữ kỳ vọng cạnh code và áp dụng từ CI. Bộ kỳ vọng ghi theo cách này là quản lý bằng code: app chỉ hiển thị, không cho sửa, để một cú bấm không ghi đè được file.

belvador-coverage.yaml

config_source: codeexpectations:  - environment: production    surface: browser    signals: [errors]  - environment: production    surface: server    signals: [errors, traces]  - environment: production    surface: job    signals: [check_ins]    stale_after_hours: 26    note: nightly billing

Bước CI

yq -o=json belvador-coverage.yaml | curl --fail-with-body -X PUT \  "https://api.belvador.dev/v1/projects/$BELVADOR_PROJECT_ID/coverage-expectations" \  -H "Authorization: Bearer $BELVADOR_TOKEN" \  -H "Content-Type: application/json" \  --data-binary @-

Token cần quyền coverage:write (token dịch vụ ở Cài đặt workspace → Service accounts hợp với CI). Mỗi lần gọi thay cả bộ kỳ vọng của project; gửi lại đúng file đó không đổi gì. Muốn trả quyền sửa về app, gửi bộ đó một lần với config_source: ui.

Từ AI agent#

Công cụ MCP get_coverage trả về đúng báo cáo của trang — trạng thái, tỷ lệ và những gì thấy nhưng chưa khai báo — để coding agent kiểm tra tính năng vừa làm có thật sự đang gửi dữ liệu. Xem MCP.

Những gì rời khỏi node#

Cho độ phủ, node chỉ gửi khoá và thời điểm: môi trường, phần, tín hiệu, lần cuối thấy và lần cuối xác minh — không bao giờ gửi nội dung, tên, thuộc tính hay số lượng dữ liệu của bạn. Mỗi project giữ tối đa 256 khoá. Lần đầu một node có báo độ phủ khởi động, nó đọc lại một lần 30 ngày lỗi và check-in, 7 ngày trace và log, để app đang chạy không bắt đầu ở trạng thái chưa biết.

Độ phủ cần node 0.1.35 trở lên. Node cũ hơn không báo gì, và trang sẽ nói rõ điều đó thay vì đoán.

Thấy chỗ sai hoặc thiếu? Gửi cho chúng tôi: hello@belvador.dev