Django-CSR架构总结Sentry
这篇讲什么
- Sentry 的 SDK 三行代码就能接上,但它服务端为什么能扛住「每秒几万条错误」是个架构问题。这篇把 Sentry 自托管版的组件拆开讲:Relay 负责收与挡,Kafka 负责排队,ingest-consumer 负责加工,Snuba + ClickHouse 负责存与查,Postgres 负责元数据,Symbolicator 负责把符号化后的堆栈还原出来。
- SDK 侧的字段是实测的(本机用自定义 transport 截获事件,不发网络);服务端组件的职责按官方架构文档整理,本机没有部署 Sentry 服务端,未验证。
- 实测环境:Django 5.2.19 LTS + sentry-sdk 2.73.0。
- 服务端架构参考 Sentry 官方文档与自托管仓库,属于「读文档 + 对照 SDK 行为」的整理,不是实机复现。
Sentry 解决什么问题
- 错误与异常的收集、聚合、统计、报警通知。
- 性能追踪(Transaction / Span / Trace),按抽样比例上报。
- 版本与发布维度的回归定位:「这个 issue 是哪个 release 引入的」。
- 多环境隔离(开发/预发/线上)与团队协作(指派、静音、解决、告警规则)。
它和 Prometheus 的分工是「单次故障 vs 趋势阈值」,两边配合的接法见《Django-接入监控告警》。
SDK 侧实测:一条事件里到底有什么
传输单位是 envelope
sentry-sdk 2.x 不再走 capture_event,而是把事件装进 Envelope 交给 transport。实测(自定义 transport 本地截获):
1 | 传输类型 = envelope |
信封头里就带 trace,这是服务端能把「错误事件」和「性能事务」串起来的依据。
事件字段
1 | ['breadcrumbs', 'contexts', 'environment', 'event_id', 'exception', 'extra', 'level', |
逐项含义:
| 字段 | 内容 | 实测值 |
|---|---|---|
exception.values |
异常类型、消息、栈帧 | ValueError / 探针故意抛出:boom |
stacktrace.frames |
栈帧列表 | 3 帧,末帧 core/views.py:31 |
transaction |
分组用的事务名 | /boom/(路由模板,不是带参 URL) |
contexts.trace |
trace_id / span_id / parent_span_id |
parent_span_id = None(入口 span) |
environment / release |
环境名与版本号 | probe / probe@1.0.0 |
server_name |
主机名 | Y9000P |
modules |
依赖版本清单 | 默认附带 |
request |
请求上下文 | send_default_pii=False 时不含 cookies |
breadcrumbs |
面包屑(请求、日志、SQL 等轨迹) | 默认开启 |
三个实测到的行为差异
1 | pii=False 时 request 键 = 没有 cookies、没有 env/headers |
- 想过滤/改写事件只能用
before_send(返回None丢弃),老配置项ignore_exceptions在 2.x 已不存在。 release一定要设(构建号或 git sha),否则「按版本聚合」和「回归告警」都没法用。modules默认带全量依赖清单,方便定位版本相关 bug,敏感场景在before_send里event.pop("modules", None)。
Django 接入的最小配置
1 | import os |
traces_sample_rate 控制性能事务的抽样比例(实测 1.0 时每个请求都会额外产生 transaction 信封),生产从 0.1 起步。
服务端组件:谁负责什么

| 组件 | 职责 | 关键点 |
|---|---|---|
| Relay | 接收 SDK 请求,做鉴权、限流、脱敏、事件校验,然后写入 Kafka | 立刻返回 200 或 429,不在请求线程里做重活 |
| Kafka | 事件与指标的消息总线(ingest-events、ingest-metrics 等 topic) |
削峰,让消费端按自己节奏处理 |
| ingest-consumer | 消费 Relay 写入的消息,做 process_event |
事件加工的主力(Python 侧) |
| process_event | 栈处理、插件预处理、分组、规则计算 | 决定这条事件归到哪个 issue |
| PostgreSQL | 元数据:组织、项目、用户、规则、issue 的部分状态 | 不存海量事件本体 |
| Snuba | 事件/时间序列的存储与查询服务,对外提供查询接口 | 把 ClickHouse 抽象隔离掉 |
| ClickHouse | OLAP 列存,做搜索、聚合、标签统计 | 高压缩比 + 快扫描 |
| Redis | 缓存与队列辅助 | 集群里也要高可用 |
| Symbolicator | 符号化:把原生/混淆栈还原成函数名、文件位置、代码上下文 | 移动端与 JS source map 场景必需 |
| Nginx/Envoy | 入口与路由 | 自托管版前置 |
老笔记里有两处笔误:ngest-consumer 应为 ingest-consumer;GitlablJira 应为 Gitlab / Jira。
为什么错误会「聚合成一条 issue」
分组发生在 process_event:Sentry 按异常类型、堆栈指纹(fingerprint)、模块等算出一个 grouping key,相同 key 的事件合并成一条 issue,只累加计数并保留样本。这就是为什么:
transaction用路由模板而不是带参 URL(实测/boom/),否则每个 id 都会分裂成一条 issue。- 可以用
before_send里改event["fingerprints"] = ["{{ default }}", my_key]手工控制聚合粒度。 - 「按 release 看回归」依赖
release字段配好。
429 与限流
Relay 侧对每个 project key 做速率限制,超限直接 429;SDK 会尊重这个信号并丢弃后续事件(本地截获时看不到 429,因为它发生在服务端)。所以「错误风暴时 Sentry 不会把自己打挂」,但你的应用也可能因此丢事件——真要全量留证,就该走日志而不是 Sentry。

Snuba 的作用

- 承担事件与时间序列的存储与查询,对上层提供统一查询接口(issue 列表、趋势图、告警规则里的计数都走它)。
- 对 ClickHouse 做抽象与隔离:换存储引擎或改表结构时,上层代码不用跟着改。
- 由两部分组成:consumer(消费 Kafka 写入存储)与 query(提供查询 API)。
- 支持搜索、聚合、标签统计这类 OLAP 查询,本质是把「事件流」变成「可分析的列存表」。
老笔记里「用作搜索,图计算,规则处理查询」这句要收窄:图计算不是 Snuba 的职责,规则处理发生在 process_event 与规则引擎侧,Snuba 管的是存与查。
五、自托管部署(官方文档步骤,未在本机验证)
本机没有 Docker 运行时,本节未实测,只给官方推荐路线与要求,具体以官方文档为准:
1 | $ git clone https://github.com/getsentry/self-hosted.git |
要点:
- 官方明确不建议用 Kubernetes 之外的手工编排,也不建议自己拼组件;升级走
self-hosted仓库的固定流程。 - 资源要求不低(官方给的起步配置就是多核 + 大内存,ClickHouse 与 Kafka 都吃内存),单机小内存跑不动很正常。
- 数据卷、备份(Postgres + ClickHouse 两套)、证书、SMTP 都要单独配。
- 如果只是想要「能用的错误监控」,SaaS 版省心得多;自托管的价值在于数据不出内网。
Sentry 的强项与代价
强项(对应老笔记那份清单,做了归并):
- API 简单、各语言 SDK 自动集成,Django 只要一行
init。 - 自动聚合与 Tag 维度统计,趋势可视化开箱可用。
- 性能监控支持抽样,成本可控。
- 多租户、双因素认证、敏感内容脱敏(
before_send+ 服务端 scrubbing)。 - 生态集成:GitLab / Jira / Slack / webhook 等。
- 多环境隔离(
environment字段,实测会进信封头)。
代价:
- 服务端组件多,自托管运维成本明显高于「装个 Redis」。
- 事件量大的项目对 Kafka/ClickHouse 规模敏感,容量规划要提前做。
- 抽样与限流意味着不是全量留证,合规审计场景要另配日志。
- SDK 版本迭代快,选项名会变(实测
ignore_exceptions已移除)。
和其它监控手段的关系
| 需求 | 用什么 | 备注 |
|---|---|---|
| 未捕获异常、堆栈与上下文 | Sentry | 实测事件结构见第二节 |
| 错误率、延迟、QPS 趋势与阈值告警 | Prometheus + django-prometheus | 见《Django-接入监控告警》 |
| 全量访问日志、审计留证 | 应用日志 + 采集(journald/Loki/ELK) | Sentry 不替代日志 |
| 业务指标(订单量、支付成功率) | Prometheus 自定义 Counter 或数仓 | SDK 的 capture_message 不适合当指标用 |
| 慢 SQL / 查询数 | django-prometheus 指标 + CaptureQueriesContext |
见《Django-让网站访问更快》 |
参考
- Sentry 官方:架构概览:Relay、Kafka、Snuba、ClickHouse 的分工。
- Sentry 自托管仓库:
install.sh与组件清单、资源要求。 - Snuba 仓库说明:consumer 与 query 两部分服务。
- Symbolicator 文档:符号化处理。
- Sentry Python SDK:envelope、
before_send、traces_sample_rate。 - Sentry 事件分组文档:fingerprint 与 issue 聚合规则。