Sentry 是一套用于异常收集、性能监控、错误追踪的系统。它可以在应用运行时自动收集错误堆栈、请求信息、用户行为轨迹和性能数据，帮助开发者更快地定位问题、复现问题并修复问题。
从架构上看，Sentry 由两部分组成：
SDK：负责在前端、后端或移动端采集错误、性能和上下文信息。你可以把它理解为“可观测性中的错误和性能层”，它不只是告诉你“出错了”，还会告诉你“在哪里出错、什么时候出错、前面发生了什么、影响了谁”。
Sentry 同时提供：
SaaS 服务在异常监控领域，常见方案还有 BugSnag、Rollbar、Fundebug 等。选择 Sentry 的原因通常有以下几个：
Breadcrumbs、Transactions、Spans、Web Vitals。官方平台列表可查看：
Sentry 官方提供了基于 Docker 的自建部署方案：getsentry/onpremise。
Sentry 的后台依赖多个服务协同工作，例如：
PostgresClickHouseRedisKafkaRelay如果手工一个个搭建，成本会很高，所以通常直接使用官方 onpremise 仓库。
git clone https://github.com/getsentry/onpremise
cd onpremise
执行：
./install.sh
如果在 macOS 上遇到：
./install/_lib.sh: line 15: realpath: command not found
可以先安装 coreutils：
brew install coreutils
如果安装时报 Docker 内存不足，需要把 Docker 分配的内存调大一些，建议至少 4G。
docker-compose up -d
启动后访问：
http://localhost:9000/
如果安装时没创建账号，也可以手动创建超级管理员：
docker-compose run --rm web createuser --superuser
如果要强制更新已有账号：
docker-compose run --rm web createuser --superuser --force-update
docker-compose down
再次启动后，数据会保留。
登录 Sentry 后台，进入：
Projects -> Create Project
平台选择 React，然后创建一个项目，例如：
cra-test创建完成后，后台会给出一段接入指引。
npm install --save @sentry/react @sentry/tracing
或：
yarn add @sentry/react @sentry/tracing
在入口文件中配置：
import React from 'react';
import ReactDOM from 'react-dom';
import * as Sentry from '@sentry/react';
import { Integrations } from '@sentry/tracing';
import App from './App';
Sentry.init({
dsn: 'http://xxxx@localhost:9000/3',
environment: 'localhost',
integrations: [new Integrations.BrowserTracing()],
tracesSampleRate: 1.0,
release: '0.0.1',
});
ReactDOM.render(<App />, document.getElementById('root'));
dsnSentry SDK 上报数据的目标地址。它告诉 SDK 事件要发到哪里。
格式通常为：
{PROTOCOL}://{PUBLIC_KEY}@{HOST}{PATH}/{PROJECT_ID}
它可以公开，但不要把私钥或服务端鉴权信息混进去。
environment用于区分不同运行环境，例如：
developmentteststagingproduction后台会根据这个值做筛选和展示，排查问题时非常有用。
integrations: [new Integrations.BrowserTracing()]这个集成负责采集页面加载、路由变化、XHR / fetch 请求等性能相关数据，让你能够看到 Transaction 和 Span。
release表示当前构建版本。建议每次发布都更新它，方便：
sourcemap为了验证接入是否成功，可以故意制造一个运行时错误：
function App() {
function fn() {
console.log(window.a.b);
}
return <button onClick={fn}>Break the world</button>;
}
export default App;
点击按钮后，前端会报错，同时 Sentry 会收到一条事件。
在后台的 Issues 页面，可以查看：
Tags）如果不上传 sourcemap，Sentry 看到的通常是压缩后的代码，定位体验会差很多。上传后，Sentry 能把压缩后的堆栈还原成源码位置。
常见方式有两种：
sentry-cliwebpack plugin，推荐这种方式安装：
npm install -g --unsafe-perm=true --allow-root @sentry/cli
登录配置：
sentry-cli --url http://127.0.0.1:9000 login
登录完成后，会生成配置文件 ~/.sentryclirc，内容类似：
[auth]
token=xxxx
[defaults]
url=http://127.0.0.1:9000
org=sentry
project=cra-test
上传源码映射：
npm run build
sentry-cli releases files 0.0.1 upload-sourcemaps --url-prefix '~/' './build'
其中 --url-prefix 要和线上资源路径一致，否则 Sentry 可能匹配不到正确文件。
安装：
npm i -D @sentry/webpack-plugin
示例配置：
const SentryCliPlugin = require('@sentry/webpack-plugin');
module.exports = function override(config) {
config.devtool = 'source-map';
config.plugins.push(
new SentryCliPlugin({
release: '0.0.1',
authToken: 'xxxx',
url: 'http://127.0.0.1:9000',
org: 'sentry',
project: 'cra-test',
urlPrefix: '~/',
include: './build',
ignore: ['node_modules'],
})
);
return config;
};
这种方式更适合接入 CI/CD，在构建完成后自动上传 sourcemap。
sourcemap 不建议直接部署到线上静态资源里，避免源码泄露。
构建后可以根据你的产物目录清理 *.map 文件，例如：
{
"scripts": {
"build": "react-app-rewired build && rm -rf dist/*.map"
}
}
Breadcrumbs 是错误发生前的一串行为记录，比如：
它的价值在于：让你看到“错误前用户做了什么”。
Sentry 会自动采集很多 Breadcrumb，也可以手动添加：
Sentry.addBreadcrumb({
category: 'auth',
message: 'Authenticated user ' + user.email,
level: Sentry.Severity.Info,
});
Transaction 表示一次完整的操作过程，例如：
它是性能和链路追踪的基本单位。
Span 是 Transaction 内部的一个子步骤，例如：
一个 Transaction 往往由多个 Span 组成。
Trace 是把多个相关的 Transaction 串起来形成的一条完整链路。
通常可以理解为：
TransactionTransactionTransactionTraceSentry 的 Performance 面板可以帮助你分析页面加载和接口耗时，常见指标包括：
FCP - First Contentful PaintLCP - Largest Contentful PaintFID - First Input DelayCLS - Cumulative Layout ShiftFP - First PaintTTFB - Time To First Byte| 指标 | 含义 | 关注点 |
|---|---|---|
| FCP | 首次内容绘制 | 页面是否“开始有内容” |
| FP | 首次绘制 | 页面是否“开始有像素” |
| LCP | 最大内容绘制 | 页面主要内容是否加载得足够快 |
| FID | 首次输入延迟 | 用户第一次操作时是否卡顿 |
| CLS | 累积布局偏移 | 页面是否频繁跳动 |
| TTFB | 首字节时间 | 服务端响应是否够快 |
在 Performance 页面中，你通常会看到：
Transaction 的统计p50 / p75 / p95 分位数TPM（每分钟事务数）ApdexFailure RateApdex 用于衡量用户对响应速度的满意度：
Apdex = (满意请求数 + 可容忍请求数 / 2) / 总请求数
它把请求分成三类：
Satisfactory：满意Tolerable：可容忍Frustrated：不满意这个指标很适合拿来衡量整体体验，而不是只盯着平均值。
Failure Rate 表示失败 Transaction 的比例。对于性能分析来说，它可以帮助你快速发现：
如果想快速验证 Performance 面板，可以在 Chrome DevTools 中把网络限速改成：
Fast 3GSlow 3G然后刷新页面几次，就能更容易看到较差的性能指标数据。
release 正确。sourcemap 只上传到 Sentry，不要长期暴露在公网静态目录。environment，方便过滤和排查。LCP、CLS、FID，对接口关注失败率和耗时分布。Sentry 的核心价值不是“收集错误”这么简单，而是把异常、用户行为、链路追踪和性能指标组合到一起，让问题排查更快、更完整。
如果你只接了基础错误上报，它是一个报错收集器；如果你把 Breadcrumbs、Tracing、Source Map 和 Performance 都接上，它就会变成一套真正可用的线上诊断系统。