Hướng dẫn tích hợp Sentry vào ứng dụng React

Trong bài viết trước, chúng ta đã cùng nhau tìm hiểu tổng quan về Sentry - một công cụ giúp theo dõi và ghi nhận lỗi ứng dụng, từ đó hỗ trợ developer khắc phục và cải thiện chất lượng sản phẩm.

Ở bài viết này, mình sẽ hướng dẫn chi tiết cách tích hợp Sentry vào một dự án React, từ việc tạo tài khoản, thiết lập project, cấu hình Sentry trong codebase, cho đến cách gửi thêm thông tin về người dùng, breadcrumbs, cũng như tối ưu hóa quá trình gỡ lỗi thông qua việc tích hợp source maps.

1. Đăng ký tài khoản Sentry

Đầu tiên, bạn cần truy cập vào trang chủ của Sentry để đăng ký tài khoản, giao diện sẽ trông như hình bên dưới. Bạn có thể tạo mới tài khoản hoặc đăng ký bằng tài khoản Google, Github của bạn.

Sau khi đăng ký thành công, bạn sẽ thấy dashboard trông như thế này.

2. Tạo mới project tại dashboard Sentry

Sau khi bạn đã có tài khoản và dashboard của riêng cá nhân mình. Hãy chọn button create project để tạo mới nhé. Giao diện sẽ trông như thế này để bạn chọn platform, tần suất cảnh báo và tên của project.

Lưu ý là với tài khoản miễn phí thì chỉ nhận cảnh báo thông qua email được thôi nhé. Bạn nên chọn đúng platform giúp Sentry cung cấp hướng dẫn tích hợp chính xác hơn cho bạn.

3. Setup Sentry cho dự án React

Sau khi bạn Create Project thành công, Sentry sẽ hiển thị hướng dẫn bạn từng bước để tích hợp. Đầu tiên, sẽ cài đặt sentry package với câu lệnh sau:

npm install --save @sentry/react @sentry/tracing

Tiếp đến, bạn sẽ cần khởi tạo Sentry trong ứng dụng React (ví dụ trong file index.js hoặc main.js)

import * as Sentry from "@sentry/react";
import { createRoot } from "react-dom/client";
import App from "./App";

// ------------------------------------------------

Sentry.init({
  dsn: "YOUR_DSN",
  integrations: [],
});

const container = document.getElementById("app");
const root = createRoot(container);
root.render(<App />);

DSN (Data Source Name) là chuỗi kết nối để Sentry biết gửi dữ liệu lỗi từ ứng dụng của bạn tới tài khoản Sentry tương ứng.

Nhưng nếu bạn lỡ thoát ra khỏi nơi hướng dẫn và không biết sentry DSN của project vừa tạo là gì, đừng lo lắng hãy làm theo mình hướng dẫn nhé.

Đầu tiên, tại thanh sidebar Setting --> Projects --> chọn Project của bạn vừa tạo --> Client Keys (DSN). Tại đó bạn có thể lấy được DSN

4. Add Error Boundaries

Để catch error trong các components React của bạn và gửi chúng đến Sentry, bạn có thể sử dụng thành phần ErrorBoundary do @sentry/react cung cấp.
Trong trường hợp lỗi xảy ra, ErrorBoundary sẽ gửi dữ liệu lỗi tới Sentry và hiển thị UI fallback cho người dùng.

import { ErrorBoundary } from '@sentry/react';

// -------------------------------------------

function MyComponent() {
  // ...
}

export default function App() {
  return (
    <ErrorBoundary fallback={"An error has occurred"}>
      <MyComponent />
    </ErrorBoundary>
  );
}

• Error Boundaries giúp ứng dụng không bị "crash" toàn bộ, mà chỉ component bị lỗi sẽ được thay thế bằng UI fallback.
• Sentry sẽ tự động ghi nhận stack trace của lỗi, giúp bạn dễ dàng tìm ra nguyên nhân gốc rễ.

5. Customize Sentry

Bạn có thể cung cấp nhiều tuỳ chọn config khác nhau với Sentry. Ví dụ, bạn có thể config nó để thu thập dữ liệu bổ sung như: user context và breadcrumbs.

import { configureScope } from '@sentry/react';

// -------------------------------------------------

configureScope(scope => {
  scope.setUser({ email: 'john.doe@example.com' });
  scope.addBreadcrumb({
    message: 'User clicked a button',
    category: 'ui',
    data: {
      buttonId: 'my-button',
    },
  });
});

• User Context: giúp bạn xác định người dùng bị ảnh hưởng bởi lỗi, từ đó dễ dàng liên kết vấn đề với trường hợp sử dụng thực tế.

• Breadcrumbs: là một dạng log timeline các sự kiện dẫn đến lỗi, giúp bạn hiểu ngữ cảnh trước khi lỗi xảy ra.

Bây giờ, bất cứ khi nào xảy ra lỗi trong ứng dụng của bạn, lỗi đó sẽ automatically reflect và được thông báo trong dashboard Sentry trong Issues tab.

Nếu như bạn click vào title Error nào thì sẽ hiển thị stack trace.

6. Tối ưu việc gỡ lỗi với Source Maps

Ở môi trường production, code của bạn thường được minified and compressed. Điều này có thể gây khó khăn cho việc debug vì stack traces and error messages có thể không hợp lý.

Để tải source code lên Sentry, bạn thực hiện theo các bước như này nhé

B1: Cài đặt @sentry/webpack-plugin và @sentry/clipackages:

yarn add @sentry/webpack-plugin @sentry/cli

Việc implementation ứng dụng có thể sẽ khác nhau phụ thuộc vào công cụ build, ví dụ như: webpack, vite, turbopack. Ở hướng dẫn này, mình sử dụng vite nhé

B2: Import SentryWebpackPlugin vào tệp vite.config.js của bạn và thêm nó vào mảng plugin

import { defineConfig } from 'vite';
import { SentryWebpackPlugin } from '@sentry/webpack-plugin';

// ----------------------------------------------------------

export default defineConfig({
  plugins: [
    new SentryWebpackPlugin({
      // options go here
    })
  ]
});

B3: Setup SentryCLI

Tạo một file sentry.js

const SentryCli = require("@sentry/cli");

// -----------------------------------------

const createReleaseAndUpload = async () => {
  const release = require("child_process")
    .exec("git rev-parse --short HEAD") /* use execSync instead of exec */
    .toString()
    .trim();

  if (!release) {
    console.warn("release HEAD not found...");
    return;
  }

  const cli = new SentryCli();

  try {
    console.log("Creating sentry release " + release);
    await cli.releases.new(release);

    console.log("Uploading source maps");
    await cli.releases.uploadSourceMaps(release, {
      include: ["dist/assets"],
      urlPrefix: "~/assets",
      rewrite: false,
    });

    console.log("Finalizing release");
    await cli.releases.finalize(release);
  } catch (e) {
    console.error("Source maps uploading failed:", e);
  }
};

createReleaseAndUpload();

Ở đây, mình generated a git hash cho mỗi version release với execSync method và các param cần thiết.

Create file .sentryclirc để SentryCli có thể tìm thấy và cấu hình phù hợp

[defaults]
project=YOUR_PROJECT_NAME
org=YOUR_org

[auth]
token= YOUR_AUTH_TOKEN

Để authorise cho SentryCLI, bạn cần tạo auth token truy cập theo thứ tự sau: Settings --> Account --> API --> Auth Tokens and cấp quyền thích hợp ( Read & Write )

Bây giờ, bạn hãy cập nhật lệnh build và bao gồm cả đoạn mã sau. Ví dụ, lệnh build của mình trông như thế này:

"build" : "node src/sentry.js && vite build"

Bây giờ, mỗi khi bạn tạo một bản dựng mới, sourcemap sẽ được tự động chuyển sang SentryJS.

7. Kết luận

Qua các bước hướng dẫn ở trên, bạn đã setup thành công Sentry cho dự án React, từ việc khởi tạo project, tích hợp code, thêm Error Boundary, đến việc tùy chỉnh và đính kèm thông tin bổ sung giúp dễ dàng truy vết lỗi.

Với Sentry, mỗi khi phát sinh sự cố, bạn có thể nhanh chóng nắm bắt, phân tích, và xử lý vấn đề để ứng dụng luôn đảm bảo chất lượng, nâng cao trải nghiệm người dùng và tiết kiệm thời gian cho đội ngũ dev.

Hy vọng qua bài viết này, bạn có thể setup thành công Sentry cho riêng mình trong dự án.

Các bài viế liên quan:

• MUI (Material UI): Công cụ rút ngắn thời gian xây dựng Giao diện
• Hướng dẫn tích hợp Redux và React Query trong dự án React Vite
• React Toastify là gì? Hướng dẫn sử dụng Toast Notification với React Toastify
• Hướng dẫn sử dụng Zustand trong NextJS