WHAT - 前端性能监控和错误追踪（Sentry 篇）

前言

Sentry 是一个流行的应用性能监控（APM）和错误追踪平台，能够帮助开发者实时识别、诊断并解决问题。它提供详细的错误、崩溃和性能瓶颈分析，广泛应用于前端、后端和移动端项目中。

Sentry 的核心功能

• 错误追踪： 捕获错误堆栈、日志及上下文信息，帮助快速定位问题根源。
• 性能监控： 跟踪应用的响应时间、吞吐量、事务数据等性能指标。
• 用户影响分析： 识别影响用户最多的问题，帮助团队更高效地确定修复优先级。
• Source Map 支持： 在前端应用中，帮助解析压缩和混淆后的代码，方便调试。
• 丰富的集成： 支持 React、Vue.js、Angular、Node.js、Python 等多种主流框架和库。
• 告警与通知： 可通过 Slack、邮件等方式及时通知团队成员，确保快速响应。

常见应用场景

• 前端监控： 追踪 JavaScript 错误，提升 Web 应用的稳定性。
• 后端监控： 监控 API 性能，快速发现服务端异常。
• 移动端监控： 捕获移动应用中的崩溃及错误。
• 版本发布监控： 帮助定位新版本中的问题，避免回归 bug。

集成（React 项目）

在 React 项目中集成 Sentry 可以帮助你快速发现和解决应用中的错误及性能问题。以下是详细的集成步骤：

第一步：安装 Sentry SDK

在项目根目录下执行以下命令：

npm install @sentry/react @sentry/tracing

第二步：初始化 Sentry

在项目的入口文件（如 main.tsx 或 index.tsx）中添加以下代码：

import * as Sentry from '@sentry/react';
import { BrowserTracing } from '@sentry/tracing';

Sentry.init({
  dsn: 'https://<YOUR_DSN>@o<ORG_ID>.ingest.sentry.io/<PROJECT_ID>',
  integrations: [new BrowserTracing()],
  
  // 设置性能监控的采样率（0.0 - 1.0）
  tracesSampleRate: 1.0,

  // 捕获未处理的 Promise 异常
  ignoreErrors: ['ResizeObserver loop limit exceeded'], // 可忽略已知的非关键性错误
});

• dsn 是你在 Sentry 项目中生成的唯一标识。
• 登录 Sentry 创建项目后，即可找到 dsn。

第三步：在应用中捕获错误

Sentry.ErrorBoundary: 自动捕获组件错误

Sentry 提供了 Sentry.ErrorBoundary 组件，可用于捕获组件中的错误。

在 App.tsx 中添加以下代码：

import React from 'react';
import * as Sentry from '@sentry/react';

const App = () => {
  return (
    <Sentry.ErrorBoundary fallback={<p>出错了，请稍后再试！</p>}>
      <YourComponent />
    </Sentry.ErrorBoundary>
  );
};

Sentry.wrap: 自动捕获 API 请求异常

Sentry 提供了 Sentry.wrap 来自动捕获 fetch、axios 等网络请求中的异常。

通过封装 API 请求逻辑，Sentry 能更方便地追踪请求失败的具体原因，并自动上报相关错误信息。

API 请求异常处理示例

使用 fetch + Sentry.wrap

import * as Sentry from '@sentry/react';

const fetchData = Sentry.wrap(async (url: string) => {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`请求失败: ${response.status} ${response.statusText}`);
  }
  return await response.json();
});

// 示例调用
const handleFetch = async () => {
  try {
    const data = await fetchData('/api/data');
    console.log('数据获取成功:', data);
  } catch (error) {
    console.error('API 请求失败:', error);
  }
};

使用 axios + Sentry.wrap（结合 Sentry.captureException）

axios 的错误对象结构与 fetch 略有不同，推荐使用 Sentry.captureException 捕获详细的响应数据。

import axios from 'axios';
import * as Sentry from '@sentry/react';

const axiosInstance = axios.create({
  baseURL: '/api',
  timeout: 5000,
});

// 封装请求
const fetchData = Sentry.wrap(async (url: string) => {
  try {
    const response = await axiosInstance.get(url);
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      Sentry.captureException(new Error(`API 请求错误: ${error.message}`), {
        extra: {
          url,
          status: error.response?.status,
          data: error.response?.data,
        },
      });
    }
    throw error;
  }
});

// 示例调用
const handleFetch = async () => {
  try {
    const data = await fetchData('/data');
    console.log('数据获取成功:', data);
  } catch (error) {
    console.error('API 请求失败:', error);
  }
};

推荐的最佳实践

• 将 Sentry.wrap 封装在统一的请求模块中，便于集中管理。
• 使用 Sentry.captureException 时，可以传入 extra 字段，携带额外信息（如 url、params 等），便于调试。
• 在 axios 拦截器中添加 Sentry.captureException，可统一捕获所有请求错误。具体如下

axios 拦截器示例（推荐）

更优雅的方式是直接在 axios 拦截器中统一处理：

axiosInstance.interceptors.response.use(
  (response) => response,
  (error) => {
    if (axios.isAxiosError(error)) {
      Sentry.captureException(new Error(`API 请求失败: ${error.message}`), {
        extra: {
          url: error.config?.url,
          method: error.config?.method,
          status: error.response?.status,
          data: error.response?.data,
        },
      });
    }
    return Promise.reject(error);
  }
);

这种方式更简洁，能统一处理 axios 请求中的异常，避免每个 API 方法都重复写 Sentry.wrap 逻辑。

结合 swr (stable-while-revalidate)

有关 swr 请阅读 WHAT - React 请求方案之 SWR（stale-while-revalidate）

结合 SWR 与 Sentry 进行 API 异常捕获是一种非常高效且优雅的实践。

SWR 本身具备出色的错误处理机制，我们可以借助 SWR 的 onError 回调或 error 对象来将异常信息上报到 Sentry。

SWR + Sentry 集成示例

1. 使用 onError 回调 (推荐)

SWR 提供的 onError 回调是处理全局错误的最佳入口，结合 Sentry 时尤为方便。

示例实现：

import useSWR from 'swr';
import * as Sentry from '@sentry/react';
import axios from 'axios';

// 创建 axios 请求器
const fetcher = async (url: string) => {
  const response = await axios.get(url);
  return response.data;
};

const ExampleComponent = () => {
  const { data, error, isLoading } = useSWR('/api/data', fetcher, {
    onError: (error, key) => {
      if (axios.isAxiosError(error)) {
        Sentry.captureException(new Error(`SWR 请求错误: ${error.message}`), {
          extra: {
            url: key,
            status: error.response?.status,
            data: error.response?.data,
          },
        });
      }
    },
  });

  if (isLoading) return <p>加载中...</p>;
  if (error) return <p>请求失败，请稍后重试。</p>;

  return <div>数据: {JSON.stringify(data)}</div>;
};

2. 使用 error 对象 (备选)

当你需要更细粒度的错误处理（如区分业务逻辑异常）时，可以通过 error 对象直接捕获并上报错误。

示例实现：

import useSWR from 'swr';
import * as Sentry from '@sentry/react';

const fetcher = async (url: string) => {
  const response = await fetch(url);
  if (!response.ok) {
    const error = new Error(`请求失败: ${response.status}`);
    error.name = 'APIError';
    throw error;
  }
  return await response.json();
};

const ExampleComponent = () => {
  const { data, error, isLoading } = useSWR('/api/data', fetcher);

  if (error) {
    // 捕获并上报 SWR 错误
    Sentry.captureException(error, {
      extra: { url: '/api/data' },
    });
    return <p>数据加载失败，请稍后重试。</p>;
  }

  if (isLoading) return <p>加载中...</p>;

  return <div>数据: {JSON.stringify(data)}</div>;
};

3. 使用全局错误处理 (适合全局拦截)

如果希望捕获所有 SWR 请求的错误，可以利用 SWRConfig 提供的 onError 参数。

示例实现：

import { SWRConfig } from 'swr';
import * as Sentry from '@sentry/react';
import axios from 'axios';

const fetcher = (url: string) => axios.get(url).then((res) => res.data);

const App = () => (
  <SWRConfig
    value={{
      fetcher,
      onError: (error, key) => {
        if (axios.isAxiosError(error)) {
          Sentry.captureException(new Error(`SWR 请求错误: ${error.message}`), {
            extra: {
              url: key,
              status: error.response?.status,
              data: error.response?.data,
            },
          });
        }
      },
    }}
  >
    <YourComponent />
  </SWRConfig>
);

4. 最佳实践建议

4.1 使用 onError 回调可避免在每个 useSWR 请求中重复写 Sentry.captureException。
4.2 在 Sentry.captureException 中利用 extra 字段，记录 url、status、params 等关键信息，便于快速排查问题。
4.3 如果 SWR 请求需要重试，推荐在 onErrorRetry 中增加重试机制，避免重复上报错误。

5. onErrorRetry 重试机制示例

import useSWR from 'swr';

const fetcher = async (url: string) => {
  const response = await fetch(url);
  if (!response.ok) throw new Error('请求失败');
  return await response.json();
};

const ExampleComponent = () => {
  const { data, error, isValidating } = useSWR('/api/data', fetcher, {
    onErrorRetry: (error, key, config, revalidate, { retryCount }) => {
      // 网络错误或5次重试后停止
      if (error.status === 404 || retryCount >= 5) return;
      setTimeout(() => revalidate({ retryCount }), 2000); // 2秒后重试
    },
  });

  if (error) return <p>请求失败，请稍后重试。</p>;
  if (isValidating) return <p>加载中...</p>;

  return <div>数据: {JSON.stringify(data)}</div>;
};

6. 推荐组合
   6.1 局部错误处理：在请求中使用 error 对象
   6.2 全局错误处理：在 SWRConfig 中使用 onError
   6.4 自动重试机制：使用 onErrorRetry 控制重试逻辑

第四步：Sentry.captureException: 手动上报错误（可选）

在某些场景下，你可能需要手动捕获并上报错误：

import * as Sentry from '@sentry/react';

const handleClick = () => {
  try {
    // 模拟错误
    throw new Error('手动触发的错误');
  } catch (error) {
    Sentry.captureException(error);
  }
};

第五步：组件渲染性能监控（可选）

Sentry 提供了 withProfiler，用于监控组件的渲染性能：

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

function HomePage() {
  return <div>主页</div>;
}

export default withProfiler(HomePage);

第六步：验证 Sentry 是否成功集成

1. 启动项目后，访问页面并手动触发错误（如 throw new Error('测试错误')）。
2. 前往 Sentry 控制台 检查是否已捕获到错误。

注意事项

• tracesSampleRate 控制性能监控的采样率，值越大，性能数据越详细（生产环境推荐 0.2 - 0.5）。
• 在开发环境中，建议使用环境变量来管理 dsn 等敏感信息。
• 对于 API 请求中的异常，可以将 fetch 或 axios 相关逻辑封装在 Sentry.wrap 中以自动捕获错误。

如果需要更详细的集成方案（如路由监控、用户信息上报等），欢迎提问。😊