Sentry hỗ trợ khôi phục mã nguồn gốc từ các file JavaScript đã được nén hoặc biên dịch (ví dụ: TypeScript, ES2015+) thông qua cơ chế source maps. Khi xảy ra lỗi, Sentry sử dụng source map để ánh xạ lại vị trí dòng/cột trong file đã nén về đúng tệp và dòng mã ban đầu — giúp việc debug trở nên trực quan và chính xác hơn.

Cách Sentry tải và áp dụng source maps

Theo mặc định, Sentry tự động phân tích phần cuối của mỗi file JavaScript để tìm chỉ thị sourceMappingURL, ví dụ:

//# sourceMappingURL=app.min.js.map

Nếu file được lưu tại https://cdn.example.com/assets/app.min.js, Sentry sẽ cố gắng truy cập https://cdn.example.com/assets/app.min.js.map để tải bản đồ nguồn. Tuy nhiên, phương pháp này có hạn chế:

• Kết nối bị chặn bởi tường lửa hoặc mạng nội bộ;
• Không kiểm soát được phiên bản (nếu URL không chứa hash hoặc version);
• Trễ mạng làm chậm hoặc thất bại việc giải mã stack trace.

Vì vậy, cách tiếp cận tối ưu là tải trước source maps lên Sentry trong quá trình build — đảm bảo tính nhất quán, bảo mật và hiệu năng.

Tích hợp với Webpack (khuyến nghị)

Sử dụng plugin chính thức @sentry/webpack-plugin để tự động tạo và upload source maps:

npm install --save-dev @sentry/webpack-plugin

Thêm cấu hình vào webpack.config.js (hoặc vue.config.js với Vue 2):

const SentryWebpackPlugin = require("@sentry/webpack-plugin");

module.exports = {
  plugins: [
    new SentryWebpackPlugin({
      authToken: process.env.SENTRY_AUTH_TOKEN,
      org: "your-org-slug",
      project: "your-project-slug",
      include: "./dist",
      ignore: ["node_modules", "webpack.config.js"],
      urlPrefix: "~/dist"
    })
  ]
};

Lưu ý:

• Đặt plugin ở vị trí cuối cùng trong mảng plugins để đảm bảo nó xử lý file sau khi mọi loader và optimization đã hoàn tất;
• Tham số urlPrefix: "~/dist" giúp Sentry khớp artifact với bất kỳ miền nào (ví dụ: https://static-a.example.com/dist/ hoặc https://static-b.example.com/dist/).

Tạo release và upload thủ công bằng sentry-cli

Nếu không dùng plugin, bạn có thể upload thủ công qua CLI:

1. Tạo release mới:
   sentry-cli releases new v2.4.1
2. Upload source maps:
   sentry-cli releases files v2.4.1 upload-sourcemaps ./dist --url-prefix "~/dist"
3. Hoàn tất release:
   sentry-cli releases finalize v2.4.1

Đảm bảo tên file artifact khớp chính xác với giá trị trong sourceMappingURL. Ví dụ:

Cấu hình TypeScript

Để source map hoạt động chính xác với TypeScript, thiết lập tsconfig.json như sau:

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,
    "sourceRoot": "/"
  }
}

Thiết lập sourceRoot: "/" loại bỏ đường dẫn build dư thừa, giúp Sentry xác định đúng tệp nguồn tương đối với gốc dự án.

Xử lý nhiều CDN hoặc miền

Khi ứng dụng được phục vụ từ nhiều miền (ví dụ: https://eu.cdn.example.com, https://us.cdn.example.com), hãy sử dụng tiền tố ~ trong tên artifact:

• Upload file với tên ~/js/app.js → áp dụng cho mọi miền có đường dẫn /js/app.js.
• Sentry ưu tiên khớp đầy đủ URL trước; nếu không tìm thấy, mới xét đến pattern có ~.

Kiểm tra và gỡ lỗi

Một số bước kiểm tra thiết yếu khi source map không hoạt động:

• Xác minh release đã được gắn vào SDK: Trong `Sentry.init()`, đảm bảo có tham số release: "v2.4.1" trùng với tên release đã upload.
• Kiểm tra presence của sourceMappingURL: Mở file JavaScript đã deploy và xác nhận dòng cuối chứa chỉ thị hợp lệ (một số CDN như Cloudflare có thể xóa comment tự động).
• So sánh abs_path trong stack trace: Trong JSON sự kiện trên Sentry UI, kiểm tra trường abs_path (ví dụ: https://example.com/js/app.js) và đảm bảo artifact được upload với tên khớp hoàn toàn hoặc có tiền tố ~ phù hợp.
• Giới hạn kích thước: Mỗi artifact tối đa 40 MB; tránh upload file chưa nén hoặc bundle chưa chia nhỏ.
• Không nén khi upload: Sentry yêu cầu file source map và source code được upload dưới dạng văn bản thuần (UTF-8), không nén (gzip, brotli…).

Để kiểm tra tính đúng đắn của source map cục bộ, bạn có thể dùng thư viện source-map của Mozilla:

const { SourceMapConsumer } = require("source-map");
const fs = require("fs");

const smc = await new SourceMapConsumer(fs.readFileSync("./dist/app.min.js.map", "utf8"));
const orig = smc.originalPositionFor({ line: 123, column: 45 });
console.log(orig); // { source: "src/index.ts", line: 42, column: 8 }