Node.js (SDK tương thích Sentry)
Dùng SDK Sentry chính thức cho Node.js với DSN Belvador và hàm lọc dữ liệu nhạy cảm do Belvador cung cấp.
Trong bài này
Với máy chủ Node.js, Belvador dùng SDK Sentry chính thức cho Node.js với DSN Belvador của bạn. Belvador bổ sung các tuỳ chọn khởi tạo ở dưới và bộ lọc dữ liệu của chính Belvador từ @belvador/core/sentry — đúng đoạn mã SDK của Belvador chạy — để xoá body request, cookie và thông tin đăng nhập trước khi bất cứ thứ gì rời máy chủ của bạn.
Trước khi bắt đầu#
Một project có nền tảng Node.js và DSN của nó.
Phiên bản Node.js được bản
@sentry/nodehiện tại hỗ trợ (xem hướng dẫn Node.js của Sentry).
1. Cài đặt#
npm install @sentry/node@11.9.0 @belvador/core@0.6.1@belvador/core chỉ được cài để dùng lối vào ổn định @belvador/core/sentry: bộ lọc của Belvador và captureResult cho SDK Sentry chính thức. Nó không tải mã Sentry riêng nào.
2. Tạo instrument.mjs#
import * as Sentry from "@sentry/node";import { scrubBreadcrumb, scrubEvent } from "@belvador/core/sentry";Sentry.init({ dsn: process.env.BELVADOR_DSN ?? "https://<public-key>@ingest.belvador.dev/<project-id>", release: process.env.APP_VERSION, environment: process.env.NODE_ENV, sendDefaultPii: false, tracesSampleRate: 0, maxBreadcrumbs: 50, maxValueLength: 8192, // Belvador's scrubbing: request bodies, cookies and credentials never leave the app. beforeSend: scrubEvent, beforeBreadcrumb: scrubBreadcrumb,});Ý nghĩa các tuỳ chọn:
| Tuỳ chọn | Vì sao |
|---|---|
dsn | Đọc BELVADOR_DSN từ biến môi trường, nếu không có thì dùng DSN của project |
release, environment | Phiên bản và môi trường của ứng dụng, lấy từ APP_VERSION và NODE_ENV |
sendDefaultPii: false | SDK không tự thêm địa chỉ IP, cookie hay thông tin người dùng |
tracesSampleRate: 0 | SDK Sentry không gửi span; muốn có traces thì dùng OpenTelemetry |
maxBreadcrumbs: 50, maxValueLength: 8192 | Cùng giới hạn với SDK của Belvador |
beforeSend: scrubEvent | Xoá body request, cookie, header xác thực và header IP người dùng; che giá trị nằm dưới tên nhạy cảm và thông tin đăng nhập trong văn bản |
beforeBreadcrumb: scrubBreadcrumb | Cùng bộ lọc cho breadcrumb (URL chứa token, giá trị được ghi log) |
3. Nạp trước ứng dụng#
node --import ./instrument.mjs server.jsCờ --import nạp phần theo dõi lỗi trước tiên trong ứng dụng ES module. Với ứng dụng CommonJS, thay vào đó gọi require("./instrument") ở dòng đầu tiên của file entry (đổi tên file thành instrument.js và dùng require trong đó).
Framework web#
@sentry/node tự theo dõi các framework phổ biến. Express, Fastify, Koa và các framework khác cần thêm một dòng để báo lỗi từ error handler của chúng — làm theo phần framework trong hướng dẫn Node.js của Sentry và giữ nguyên các tuỳ chọn init ở trên. Belvador chưa kiểm chứng từng framework.
Báo những lỗi bạn đã xử lý#
import * as Sentry from "@sentry/node";try { await chargeCard(order);} catch (error) { Sentry.captureException(error); throw new PaymentFailed(order.id);}Lỗi cơ sở dữ liệu không ném#
Supabase và PostgREST trả { data, error } thay vì ném lỗi. Gắn captureResult vào SDK Sentry của bạn một lần:
// captureResult on the app's own Sentry SDK (@sentry/node, @sentry/bun or @sentry/deno).import * as Sentry from "@sentry/node";import { captureResultWith } from "@belvador/core/sentry";export const captureResult = captureResultWith(Sentry);Rồi bọc từng lời gọi; kết quả trả về nguyên vẹn và lỗi được báo với kiểu theo mã Postgres. Các kiểu và tuỳ chọn: Lỗi cơ sở dữ liệu.
Trên VPS: giữ lỗi qua các lần sập#
Mặc định @sentry/node giữ lỗi chưa gửi trong bộ nhớ: một lần sập, khởi động lại hay deploy đúng lúc node không liên lạc được sẽ làm mất chúng. Thêm @belvador/spool và dùng instrument.mjs này thay thế:
import * as Sentry from "@sentry/node";import { scrubBreadcrumb, scrubEvent } from "@belvador/core/sentry";import { withSpool } from "@belvador/spool";Sentry.init({ dsn: process.env.BELVADOR_DSN ?? "https://<public-key>@ingest.belvador.dev/<project-id>", release: process.env.APP_VERSION, environment: process.env.NODE_ENV, sendDefaultPii: false, tracesSampleRate: 0, maxBreadcrumbs: 50, maxValueLength: 8192, // Belvador's scrubbing: request bodies, cookies and credentials never leave the app. beforeSend: scrubEvent, beforeBreadcrumb: scrubBreadcrumb, // Errors that cannot be sent wait on disk and go out after a restart. transport: withSpool(Sentry.makeNodeTransport, { dir: process.env.BELVADOR_SPOOL_DIR ?? "/var/lib/my-app/belvador", }),});Trỏ
BELVADOR_SPOOL_DIRtới một thư mục còn nguyên sau khi khởi động lại và chỉ user của app đọc được — với systemd,StateDirectory=my-appcho bạn/var/lib/my-app.Lỗi chờ ở đó (tối đa 64 MiB, 72 giờ) và được tiến trình sau gửi khi node trả lời. Đã kiểm: các lỗi xảy ra khi node không liên lạc được đều tới sau khi tiến trình bị kill bằng
SIGKILL, và sau khi nó chết vì hết bộ nhớ.Bản thân lần sập vì hết bộ nhớ không được báo — tiến trình chết trước khi bất kỳ code nào kịp chạy — nhưng mọi lỗi nó đã giữ trước đó thì có.
Chi tiết: Offline và gửi bền.
Cài bằng AI agent#
Dán đoạn này vào Claude Code, Cursor hay một coding agent khác. Nó chứa các tệp ở trên cho máy chủ giữ lỗi qua các lần sập, cùng các quy tắc agent phải theo:
Belvador errors: Node.js (@sentry/node)Tested with: @sentry/* 11.9.0Guide: https://belvador.dev/vi/docs/sdk/nodeMục tiêuBáo lỗi của máy chủ này về Belvador bằng SDK Sentry chính thức và bộ lọc của Belvador, đúng như các tệp dưới đây. Không thêm SDK lỗi nào khác: mỗi tiến trình một Sentry.init.Quy tắcChép nguyên các tệp và giữ mọi tuỳ chọn của Sentry.init: sendDefaultPii: false, tracesSampleRate: 0, maxBreadcrumbs: 50, beforeSend: scrubEvent, beforeBreadcrumb: scrubBreadcrumb. Đọc DSN từ BELVADOR_DSN; không tự đặt thêm biến môi trường khác. Không đổi xác thực, định tuyến hay logic nghiệp vụ. Báo những lỗi code đã tự xử lý bằng captureException (report() trên Supabase Edge Functions) và bọc bằng captureResult các kết quả Supabase hay PostgREST trả lỗi thay vì ném, không đổi cách code dùng kết quả đó.```bashnpm install @sentry/node@11.9.0 @belvador/core@0.6.1``````bashnpm install @belvador/spool@0.6.1```instrument.mjs```javascriptimport * as Sentry from "@sentry/node";import { scrubBreadcrumb, scrubEvent } from "@belvador/core/sentry";import { withSpool } from "@belvador/spool";Sentry.init({ dsn: process.env.BELVADOR_DSN ?? "https://<public-key>@ingest.belvador.dev/<project-id>", release: process.env.APP_VERSION, environment: process.env.NODE_ENV, sendDefaultPii: false, tracesSampleRate: 0, maxBreadcrumbs: 50, maxValueLength: 8192, // Belvador's scrubbing: request bodies, cookies and credentials never leave the app. beforeSend: scrubEvent, beforeBreadcrumb: scrubBreadcrumb, // Errors that cannot be sent wait on disk and go out after a restart. transport: withSpool(Sentry.makeNodeTransport, { dir: process.env.BELVADOR_SPOOL_DIR ?? "/var/lib/my-app/belvador", }),});```db.mjs```javascript// captureResult on the app's own Sentry SDK (@sentry/node, @sentry/bun or @sentry/deno).import * as Sentry from "@sentry/node";import { captureResultWith } from "@belvador/core/sentry";export const captureResult = captureResultWith(Sentry);```Kiểm traChạy app trên máy với BELVADOR_DSN đã đặt và gây một lỗi thử (một route hay script ngắn ném lỗi). Xác nhận nó hiện thành issue trong project Belvador. Không gửi lỗi thử lên production nếu người dùng chưa đồng ý.Báo cáoLiệt kê các tệp đã đổi, gói đã thêm kèm đúng phiên bản, biến môi trường app giờ cần, lỗi thử bạn thấy đã tới, và những gì chưa kiểm được.Kiểm tra#
Chạy một script ngắn với cùng phần theo dõi:
import * as Sentry from "@sentry/node";Sentry.captureException(new Error("Belvador Node.js test"));await Sentry.flush(2000);Issue hiện trong project sau vài giây.
Giới hạn cần biết#
Bộ lọc của Belvador dựa trên mẫu ký tự. Bí mật nằm dưới tên lạ, hoặc nằm trong một câu thông báo tự do, có thể lọt qua.
Node lưu event lỗi, tệp đính kèm, check-in và log của Sentry, và đếm báo cáo gửi. Giữ
tracesSampleRate: 0; dữ liệu tracing và session theo dõi release sẽ bị đếm vào Chưa hỗ trợ trong số liệu nhận của project và bị bỏ.@sentry/node11 mặc định gửi session cho từng request và các lệnhSentry.logger, nên bạn sẽ thấy một số nhỏ ở mục Chưa hỗ trợ.Job định kỳ và worker báo được lượt chạy bằng
Sentry.withMonitor— xem Monitor bằng SDK Sentry chính thức.Windows service: dùng cùng công thức, nhưng Belvador chưa chạy nó trên Windows.
Bài viết về chủ đề này
Tất cả bài viết- Chuyển SDK Sentry: checklist thử từng giả địnhRời Sentry sang backend tương thích? Checklist từ một lần chạy thật: SDK Node.js gửi những item nào, item nào bị bỏ, và cần kiểm tra gì ở từng bước.
- Token lộ trong thông báo lỗi: SDK Node mặc định gửi đi những gìAPI key, token, URL webhook hay lọt vào message của lỗi. Thử 15 ca thật với @sentry/node mặc định và hai lớp lọc: cái nào lộ, vì sao lộ.
- Xử lý lỗi JavaScript trong ứng dụng do AI viết: lỗi thoát ra từ đâuLỗi JavaScript thoát ra ở đâu trong React và Node.js: thí nghiệm 13 kiểu lỗi, mỗi kiểu ba lần, và vài dòng code giúp từng lỗi hiện ra.
Thấy chỗ sai hoặc thiếu? Gửi cho chúng tôi: hello@belvador.dev