Khách hàng bấm nút “Thanh toán”, màn hình xoay vòng 30 giây rồi đứng im. Khách bực mình rời web, còn bạn thì chẳng hay biết gì vì server không log lại. Đây là cơn ác mộng kinh điển của mọi web thương mại điện tử. Sentry sinh ra để giải quyết đúng bài toán này. Nó hoạt động như một hệ thống radar giám sát 24/7. Hễ có dòng code nào gãy, Sentry lập tức bắt trọn lỗi, ghi nhận thiết bị và gửi cảnh báo về cho bạn trong vài giây.
Quick start (Thiết lập xong trong 5 phút)
Next.js và Sentry phối hợp rất ăn ý. Bạn không cần tự viết cấu hình từ đầu vì đã có công cụ tự động từ đội ngũ phát triển.
Bước 1: Chạy Sentry Wizard
Mở terminal tại thư mục gốc của project và chạy lệnh:
npx @sentry/wizard@latest -i nextjsLệnh này sẽ bật trình duyệt để bạn đăng nhập tài khoản Sentry. Tiếp theo, bạn chỉ cần chọn Organization và Project cần gắn. Wizard sẽ tự động cài các package npm và tạo sẵn file cấu hình.
Bước 2: Kiểm tra 3 file cấu hình tự sinh
Sentry sẽ tạo sẵn các file ứng với từng môi trường thực thi của Next.js:
sentry.client.config.ts: Bắt lỗi JS crash phía trình duyệt người dùng.sentry.server.config.ts: Bắt lỗi ở Node.js runtime (Server Components, Route Handlers, Server Actions).sentry.edge.config.ts: Giám sát Middleware và các hàm chạy trên Edge Runtime.
Bước 3: Test thử một lỗi runtime
Hãy tạo một nút bấm đơn giản trong Client Component để kích hoạt lỗi thử nghiệm:
"use client";
export default function TestErrorButton() {
return (
<button
onClick={() => {
throw new Error("Sentry Test: Bắn thử lỗi từ client-side!");
}}
className="px-4 py-2 bg-red-600 text-white rounded font-medium"
>
Bắn lỗi thử nghiệm
</button>
);
}Bấm nút trên trình duyệt. Mở ngay tab Issues trên Sentry Dashboard. Bạn sẽ thấy sự cố xuất hiện kèm stack trace chi tiết, phiên bản trình duyệt, OS và URL người dùng đang đứng.
Sentry vận hành ra sao trong Full-stack Next.js?
Kiến trúc Next.js App Router pha trộn giữa Client và Server. Một request từ user có thể lướt qua Middleware, render HTML trên Server Node.js, rồi mới hydrate về React client. Sự cố có thể nổ ra ở bất kỳ mắt xích nào.
1. Bọc cấu hình build với next.config
Sentry can thiệp trực tiếp vào quá trình build webpack/turbopack qua wrapper withSentryConfig trong next.config.mjs:
import { withSentryConfig } from "@sentry/nextjs";
const nextConfig = {
// Config Next.js hiện tại của bạn
};
export default withSentryConfig(nextConfig, {
silent: true, // Tắt bớt log thừa khi build trên CI
org: "my-company",
project: "ecommerce-nextjs",
widenClientFileUpload: true,
hideSourceMaps: true,
});2. Chủ động bắt ngoại lệ (Manual Capture)
Đừng chỉ trông chờ vào unhandled exception. Ở các đoạn code nhạy cảm như gọi API ngân hàng hoặc query DB, bạn nên bọc try...catch và gửi kèm metadata để dễ debug:
import * as Sentry from "@sentry/nextjs";
export async function fetchUserOrders(userId: string) {
try {
const res = await db.query("SELECT * FROM orders WHERE user_id = $1", [userId]);
return res.rows;
} catch (error) {
Sentry.captureException(error, {
extra: {
userId,
query: "SELECT * FROM orders WHERE user_id = $1",
timestamp: new Date().toISOString()
},
});
return null;
}
}3. Gắn danh tính người dùng (User Context)
Khi khách VIP gửi ticket báo lỗi, bạn cần tra cứu ngay lịch sử request của họ. Ngay sau khi user đăng nhập, hãy set context cho Sentry:
Sentry.setUser({
id: user.id,
email: user.email,
username: user.username,
});Distributed Tracing và Giám sát Performance
Đôi khi hệ thống không crash, nhưng API thanh toán mất tới 8 giây để phản hồi. Tỷ lệ rớt đơn sẽ tăng vọt. Đây là lúc tính năng Performance Monitoring và Distributed Tracing phát huy giá trị.
Distributed Tracing là gì?
Một chuỗi thanh toán gồm nhiều chặng: Browser gửi request -> Next.js Server tiếp nhận -> Gọi cổng Stripe -> Ghi dữ liệu vào Postgres. Distributed Tracing gom toàn bộ hành trình này vào một biểu đồ Gantt duy nhất (Trace). Nhờ đó, bạn thấy ngay bước gọi Stripe tốn 5.2s hay câu lệnh SQL đang bị nghẽn index.
Cấu hình mẫu trong sentry.client.config.ts và sentry.server.config.ts:
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
// Dev lấy 100% trace, production chỉ lấy 10% (0.1) để tiết kiệm hạn ngạch
tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
// Ghi lại video thao tác chuột trước khi xảy ra crash (Session Replay)
replaysOnErrorSampleRate: 1.0,
replaysSessionSampleRate: 0.05,
});Lọc dữ liệu nhạy cảm trước khi gửi đi
Tuân thủ bảo mật là nguyên tắc bắt buộc. Bạn không được để lộ token JWT, cookie session hay mã thẻ tín dụng lên dashboard Sentry. Hãy dùng hook beforeSend để làm sạch dữ liệu:
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
beforeSend(event) {
if (event.request?.headers) {
delete event.request.headers["authorization"];
delete event.request.headers["cookie"];
}
return event;
},
});Kinh nghiệm thực chiến khi vận hành Production
Sau khi triển khai Sentry cho nhiều hệ thống thực tế, mình rút ra 4 bài học quan trọng:
- Đẩy Source Maps chuẩn xác: Thêm
SENTRY_AUTH_TOKENvào biến môi trường CI/CD (GitHub Actions hoặc Vercel). Không có source maps, stack trace chỉ hiện code thu gọn vô nghĩa dạnga.b(c) at 412-df89.js:1:182. - Kiểm tra payload dữ liệu: Khi debug event context hoặc format chuỗi JSON gửi kèm lỗi, bạn có thể dùng các tool online như
toolcraft.app(mục JSON Formatter / Regex Tester) để xử lý nhanh dữ liệu thô. - Đặt ngưỡng Alert hợp lý: Tránh spam email cho từng warning nhỏ. Hãy tạo rule gửi tin nhắn Slack/Discord khi có lỗi mới (New Issue) hoặc khi một lỗi cũ nhảy vọt trên 50 lần/phút.
- Tối ưu hạn ngạch Sampling: Gói miễn phí của Sentry cho 5.000 error và 10.000 transaction/tháng. Với website có 500.000 pageviews, bạn nên hạ
tracesSampleRatevề0.01hoặc0.02ở trang tin tức và tăng mẫu ở trang Checkout.
