必须在应用启动最早期调用sentry_sdk.init(),否则早期异常会丢失;推荐在主模块入口顶部直接初始化,传入dsn、environment和traces_sample_rate等关键参数,并避免常见配置错误。

如何在Python项目中初始化Sentry SDK
必须在应用启动最早期完成初始化,否则早期异常会丢失。推荐在主模块入口(如 app.py 或 main.py)顶部直接调用 sentry_sdk.init(),不要包裹在函数或类里。
关键参数:dsn 是必填项(从 Sentry 项目设置页复制),environment 建议显式指定(如 "production" 或 "staging"),否则默认为 "production",不利于区分环境;traces_sample_rate 可设为 0.1 控制性能监控采样率,不填则不采集追踪。
常见错误:
- 把
sentry_sdk.init()放在 Flask/FastAPI 的@app.route回调里 —— 此时 SDK 尚未激活,异常根本不会上报 - 在多进程场景(如 Gunicorn)中,仅在 worker 进程初始化一次即可,无需在 master 进程重复 init
- 使用
os.environ.get("SENTRY_DSN")但忘了校验是否为空,导致静默失败
Flask 和 FastAPI 中的异常自动捕获是否开箱即用
是的,但有前提:必须确保框架的异常处理机制未被覆盖。Sentry SDK 会自动 patch flask.app.Flask 和 fastapi.FastAPI 的内部错误处理器,前提是没手动替换 app.errorhandler(500) 或重写 exception_handler。
立即学习“Python免费学习笔记(深入)”;
实操建议:
- Flask:避免定义全局
@app.errorhandler(Exception),若必须自定义,应在 handler 内显式调用sentry_sdk.capture_exception() - FastAPI:不要用
app.add_exception_handler(Exception, ...)拦截所有异常后再吞掉,除非你手动转发给 Sentry - 异步路由(如
async def)同样被支持,无需额外配置
验证方式:在路由中主动抛出 ValueError("test sentry"),查看 Sentry 后台是否收到事件 —— 注意检查 environment 标签是否匹配。
如何让Sentry捕获非 Web 请求中的异常(如 Celery、定时任务、脚本)
这类场景不会经过 Web 框架的生命周期,SDK 不会自动注入上下文,需手动包装执行逻辑。
以 Celery 为例:
- 在 task 函数外层加装饰器
@sentry_sdk.crons.monitor(...)(用于监控任务健康度) - 更通用的做法:用
with sentry_sdk.push_scope() as scope:手动添加上下文(如scope.set_tag("job", "sync_user_data")) - 确保每个 worker 进程都完成了
sentry_sdk.init(),而不是只在导入时初始化(否则 fork 后可能失效)
常见坑:
- Celery 使用
fork启动 worker 时,若sentry_sdk.init()在模块顶层执行,子进程可能继承损坏的 client 状态 —— 应改在worker_process_init信号中初始化 - 纯命令行脚本(如
python migrate.py)需在脚本末尾显式调用sentry_sdk.flush(timeout=2),否则进程退出可能导致上报丢弃
哪些异常默认不被捕获?如何主动上报
Sentry 默认捕获未处理的异常(即未被 try/except 拦截的顶层异常),但以下情况不会自动上报:
- 被
try/except捕获但未重新抛出的异常 - 系统级信号(如
SIGSEGV)或 OOM killer 终止 - 异步任务中未 await 的协程抛出的异常(如忘记
await async_func())
主动上报方式:
- 记录已捕获异常:
sentry_sdk.capture_exception(exc)(传入Exception实例) - 上报自定义消息:
sentry_sdk.capture_message("cache_missed", level="warning") - 附加用户信息:
sentry_sdk.set_user({"id": user_id, "email": email})—— 建议在请求中间件中统一设置
注意 capture_exception() 不会自动打印 traceback 到 stderr,调试时容易误以为“没报错”,建议搭配日志使用。
最易被忽略的一点:Sentry 对 KeyboardInterrupt 和 SystemExit 默认忽略,这是有意设计(避免 Ctrl+C 被当成线上故障)。如果真要上报这类中断,得手动 patch 或在 signal handler 中调用 capture_exception()。


















