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
2
3
4
传输类型 = envelope
信封头 = {'event_id': 'df203527881c442882a54126bcda7c60',
'sent_at': '2026-11-04T22:38:19.180596Z',
'trace': {'trace_id': '836aca...', 'environment': 'probe', 'release': 'probe@1.0.0'}}

信封头里就带 trace,这是服务端能把「错误事件」和「性能事务」串起来的依据。

事件字段

1
2
3
['breadcrumbs', 'contexts', 'environment', 'event_id', 'exception', 'extra', 'level',
'modules', 'platform', 'release', 'request', 'sdk', 'server_name', 'timestamp',
'transaction', 'transaction_info']

逐项含义:

字段 内容 实测值
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
2
3
4
5
pii=False 时 request 键 = 没有 cookies、没有 env/headers
pii=True 时 request 键 = ['cookies']
ignore_exceptions 选项 -> TypeError : Unknown option 'ignore_exceptions'
before_send 之后上报的异常类型 = ['ValueError']
capture_message 之后信封数 = 2
  • 想过滤/改写事件只能用 before_send(返回 None 丢弃),老配置项 ignore_exceptions 在 2.x 已不存在。
  • release 一定要设(构建号或 git sha),否则「按版本聚合」和「回归告警」都没法用。
  • modules 默认带全量依赖清单,方便定位版本相关 bug,敏感场景在 before_send 里 event.pop("modules", None)。

Django 接入的最小配置

1
2
3
4
5
6
7
8
9
10
11
12
13
import os

import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

sentry_sdk.init(
dsn=os.environ["SENTRY_DSN"],
integrations=[DjangoIntegration()],
environment=os.environ.get("DJANGO_ENV", "prod"),
release=os.environ.get("APP_RELEASE", "unknown"),
send_default_pii=False,
traces_sample_rate=0.1,
)

traces_sample_rate 控制性能事务的抽样比例(实测 1.0 时每个请求都会额外产生 transaction 信封),生产从 0.1 起步。

服务端组件:谁负责什么

Sentry中的概念

组件 职责 关键点
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。

Sentry整体架构

Snuba 的作用

Snuba的作用

  • 承担事件与时间序列的存储与查询,对上层提供统一查询接口(issue 列表、趋势图、告警规则里的计数都走它)。
  • 对 ClickHouse 做抽象与隔离:换存储引擎或改表结构时,上层代码不用跟着改。
  • 由两部分组成:consumer(消费 Kafka 写入存储)与 query(提供查询 API)。
  • 支持搜索、聚合、标签统计这类 OLAP 查询,本质是把「事件流」变成「可分析的列存表」。

老笔记里「用作搜索,图计算,规则处理查询」这句要收窄:图计算不是 Snuba 的职责,规则处理发生在 process_event 与规则引擎侧,Snuba 管的是存与查。

五、自托管部署(官方文档步骤,未在本机验证)

本机没有 Docker 运行时,本节未实测,只给官方推荐路线与要求,具体以官方文档为准:

1
2
3
4
$ git clone https://github.com/getsentry/self-hosted.git
$ cd self-hosted
$ ./install.sh --report-self-hosted-issues
$ docker compose up -d

要点:

  • 官方明确不建议用 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-让网站访问更快》

参考

本文结束 感谢您的阅读
正在加载今日诗词....