# Chuyển từ Sentry sang Belvador

> Thay SDK Sentry đang có bằng gói Belvador tương ứng mà không gửi lỗi trùng hai lần.

Belvador dùng cùng giao thức với Sentry, nên chuyển một ứng dụng sang chủ yếu là đổi gói và DSN. Quy tắc quan trọng nhất: **chỉ một SDK được báo lỗi** — chạy cả hai thì mọi lỗi về hai lần.

## Chọn gói thay thế

| Đang dùng | Thay bằng | Hướng dẫn |
|---|---|---|
| `@sentry/browser` | `@belvador/browser` | [Trình duyệt](https://belvador.dev/vi/docs/sdk/browser) |
| `@sentry/react` | `@belvador/react` | [React](https://belvador.dev/vi/docs/sdk/react) |
| `@sentry/tanstackstart-react`, hoặc Sentry tự nối trong TanStack Start | `@belvador/tanstack-start` | [TanStack Start](https://belvador.dev/vi/docs/sdk/tanstack-start) |
| `@sentry/cloudflare` | `@belvador/cloudflare` | [Cloudflare Workers](https://belvador.dev/vi/docs/sdk/cloudflare) |
| `@sentry/node` | giữ nguyên, đổi DSN và thêm hàm lọc | [Node.js](https://belvador.dev/vi/docs/sdk/node) |
| `sentry-sdk` (Python) | giữ nguyên, đổi DSN và thêm hàm lọc | [Python](https://belvador.dev/vi/docs/sdk/python) |
| SDK Sentry khác | giữ nguyên và đổi DSN — Belvador chưa kiểm chứng | — |

## Các bước cho ứng dụng JavaScript

1. **Tạo project** trong Belvador và sao chép DSN.
2. **Cài** gói Belvador, khoá ở phiên bản 0.6.1.
3. **Thay import.** Các hàm thường dùng giữ nguyên tên:

```ts
// Trước
import * as Sentry from "@sentry/react";
Sentry.captureException(error);

// Sau
import { captureException } from "@belvador/react";
captureException(error);
```

4. **Thay `Sentry.init`** bằng `init` của Belvador (hoặc `withBelvador` trên Workers), theo phần cài đặt trong hướng dẫn. Xoá lời gọi `Sentry.init` cũ — `init` của Belvador không chiếm quyền một client đang chạy.
5. **Gỡ** mọi gói SDK `@sentry/*` khỏi `package.json` (giữ `@sentry/cli` nếu CI dùng cho source map). Gói của Belvador đã mang theo engine được khoá phiên bản; không cần cài `@sentry/*` bên cạnh.
6. **Cập nhật CSP**: thay địa chỉ nhận lỗi của Sentry bằng `https://ingest.belvador.dev` trong `connect-src`.
7. **Trỏ CI về Belvador** cho source map: giữ `sentry-cli`, đổi `SENTRY_URL` và token — xem [Source map](https://belvador.dev/vi/docs/source-maps).
8. **Triển khai và kiểm**: chạy [phép kiểm kết nối](https://belvador.dev/vi/docs/sdk/verify) cho từng môi trường và xác nhận tab **Kết nối** báo **Đã xác minh**. Lỗi gắn thẻ chạy được với mọi SDK Sentry, nên bạn có thể kiểm trước khi đổi gói. Sau đó xác nhận một lỗi thật chỉ hiện một lần.

## Tuỳ chọn thay đổi

| Tuỳ chọn Sentry | Trong Belvador |
|---|---|
| `dsn`, `release`, `environment`, `dist`, `sampleRate`, `ignoreErrors`, `beforeSend`, `beforeBreadcrumb`, `maxBreadcrumbs`, `debug` | Giữ nguyên ý nghĩa |
| `allowUrls`, `denyUrls` (trình duyệt) | Giữ nguyên ý nghĩa |
| `enabled` | Dùng `disabled: true` |
| `integrations`, `defaultIntegrations` | Không nhận; Belvador tự thiết lập phần cần thiết. Breadcrumb bật bằng `instrument` |
| `tracesSampleRate`, `tracePropagationTargets`, `replaysSessionSampleRate`, `profilesSampleRate`, `enableLogs` | Không có — SDK chỉ gửi lỗi. Gửi traces và log bằng [OpenTelemetry](https://belvador.dev/vi/docs/otel/overview); nối lỗi giữa các tầng bằng [`tracePropagation`](https://belvador.dev/vi/docs/sdk/tracing) |
| `sendDefaultPii` | Luôn tắt |
| `tunnel`, `transport` | Không có — event chỉ đi tới DSN của bạn |
| `maxValueLength` | Cố định 8.192 ký tự |

TypeScript sẽ chỉ ra các tuỳ chọn không còn tồn tại.

## Hành vi thay đổi

- `setUser` chỉ giữ `id`. Email, tên đăng nhập và địa chỉ IP bị xoá trước khi gửi.
- Breadcrumb tự động (console, click, fetch, XHR, điều hướng) tắt cho tới khi bạn bật.
- Tệp đính kèm bị bỏ trừ khi đặt `attachments: true`.
- Không có `Sentry.showReportDialog` và `showDialog` của boundary.
- Body request, cookie và header xác thực bị SDK xoá, và node xoá thêm một lần.

## Giữ SDK Sentry đang có

SDK Sentry nào cũng gửi được tới DSN Belvador, nên bạn cũng có thể chỉ đổi DSN. Khi đó bạn giữ các mặc định của SDK đó: nó có thể gửi dữ liệu tracing (node bỏ và đếm vào **Chưa hỗ trợ**), dữ liệu cá nhân nếu bật `sendDefaultPii`, và breadcrumb tự động. Node vẫn lọc trước khi lưu. Với ứng dụng JavaScript, gói của Belvador là lựa chọn an toàn hơn.

## Issue đã có

Belvador bắt đầu với lịch sử trống: issue và event đang nằm trong Sentry không được nhập sang. Giữ Sentry ở chế độ chỉ đọc một thời gian nếu bạn cần tra cứu.