adding-error-tracking

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add Error Tracking (Sentry)

添加错误追踪(Sentry)

Use this skill when the user asks to add error tracking, crash reporting, exception monitoring, or performance tracing.
当用户要求添加错误追踪、崩溃报告、异常监控或性能追踪时,使用此技能。

Steps

步骤

  1. Detect the framework — check
    package.json
    , config files, and directory structure to determine the stack (Next.js, React, Node.js, Python/Django/Flask, etc.).
  2. Install the SDK
    • Next.js:
      npx @sentry/wizard@latest -i nextjs
    • React (Vite):
      npm install @sentry/react
    • Node.js:
      npm install @sentry/node
    • Python:
      pip install sentry-sdk
  3. Initialize Sentry
    • For Next.js, the wizard creates
      sentry.client.config.ts
      ,
      sentry.server.config.ts
      , and
      sentry.edge.config.ts
      . Verify they exist and contain the DSN.
    • For React (Vite), init in
      main.tsx
      :
      tsx
      import * as Sentry from "@sentry/react";
      
      Sentry.init({
        dsn: import.meta.env.VITE_SENTRY_DSN,
        integrations: [Sentry.browserTracingIntegration()],
        tracesSampleRate: 1.0,
      });
    • For Node.js, init at the very top of the entry file before any other imports.
  4. Add environment variables
    NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...
    SENTRY_AUTH_TOKEN=sntrys_...
    SENTRY_ORG=your-org
    SENTRY_PROJECT=your-project
  5. Add error boundary — wrap the app (or critical subtrees) with
    Sentry.ErrorBoundary
    and a fallback UI.
  6. Source maps — for production builds, configure the Sentry webpack/vite plugin to upload source maps. For Next.js, this is handled by
    withSentryConfig
    in
    next.config.js
    .
  7. Test the integration — add a temporary button that throws an error to verify events appear in the Sentry dashboard.
  1. 检测框架 —— 检查
    package.json
    、配置文件和目录结构以确定技术栈(Next.js、React、Node.js、Python/Django/Flask等)。
  2. 安装SDK
    • Next.js:
      npx @sentry/wizard@latest -i nextjs
    • React (Vite):
      npm install @sentry/react
    • Node.js:
      npm install @sentry/node
    • Python:
      pip install sentry-sdk
  3. 初始化Sentry
    • 对于Next.js,向导会创建
      sentry.client.config.ts
      、
      sentry.server.config.ts
      和
      sentry.edge.config.ts
      。验证这些文件是否存在并包含DSN。
    • 对于React (Vite),在
      main.tsx
      中初始化:
      tsx
      import * as Sentry from "@sentry/react";
      
      Sentry.init({
        dsn: import.meta.env.VITE_SENTRY_DSN,
        integrations: [Sentry.browserTracingIntegration()],
        tracesSampleRate: 1.0,
      });
    • 对于Node.js,在入口文件的最顶部、任何其他导入之前进行初始化。
  4. 添加环境变量
    NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...
    SENTRY_AUTH_TOKEN=sntrys_...
    SENTRY_ORG=your-org
    SENTRY_PROJECT=your-project
  5. 添加错误边界 —— 使用
    Sentry.ErrorBoundary
    包裹应用(或关键子树)并设置回退UI。
  6. 源映射 —— 对于生产构建,配置Sentry webpack/vite插件以上传源映射。对于Next.js,此操作由
    next.config.js
    中的
    withSentryConfig
    处理。
  7. 测试集成 —— 添加一个临时按钮来抛出错误,验证事件是否出现在Sentry仪表盘中。

Notes

注意事项

  • Set
    tracesSampleRate
    to a lower value (e.g.
    0.1
    ) in production to control costs.
  • Add
    sentry.properties
    and
    .sentryclirc
    to
    .gitignore
    .
  • Never commit
    SENTRY_AUTH_TOKEN
    .
  • 在生产环境中将
    tracesSampleRate
    设置为较低的值(例如
    0.1
    )以控制成本。
  • 将
    sentry.properties
    和
    .sentryclirc
    添加到
    .gitignore
    中。
  • 切勿提交
    SENTRY_AUTH_TOKEN
    。