Python 异常上报的 Sentry 集成

python项目自动上报异常到sentry需在启动最早期调用sentry-sdk.init()，确保每个进程（如gunicorn worker）都初始化；框架内500错误需手动在Error handler中调用capture_exception()；通过environment、release和configure_scope()传上下文；本地开发用before_send拦截。

怎么让 Python 项目自动把异常发到 Sentry

直接装 sentry-sdk，调 init()，它就会自动捕获未处理异常。不需要改任何 try/except，也不用重写 sys.excepthook —— SDK 已经帮你做了。

常见错误是只在某个模块里 init()，结果其他模块的异常没上报。必须确保 init() 在应用启动最早期执行（比如 main.py 开头、django 的 settings.py 末尾、flask 的创建 app 前）。

• init() 只能调一次，重复调用会静默失败，且后续配置不生效
• 如果用 Gunicorn/Uvicorn，要确保每个 worker 进程都初始化，不能只在主进程 init
• Django 用户别再用旧的 raven，sentry-sdk 自动集成中间件和日志处理器，Logging 配置里加 SentryHandler 是多此一举

为什么 Flask/fastapi 的 500 错误不上报

因为这些框架默认捕获了异常并返回 HTML 或 json 响应，异常没“漏”到顶层，sentry-sdk 的全局钩子就收不到。得手动触发上报。

FastAPI 用 exception_handler；Flask 用 @app.errorhandler(500)，在 handler 里显式调 capture_exception()。

立即学习“Python免费学习笔记（深入）”；

• Flask 示例：

  from sentry_sdk import capture_exception<br>@app.errorhandler(500)<br>def handle_500(e):<br>  capture_exception(e)<br>  return "Server Error", 500

• FastAPI 示例：

  from fastapi import Request<br>from sentry_sdk import capture_exception<br>@app.exception_handler(500)<br>async def unicorn_exception_handler(request: Request, exc: Exception):<br>  capture_exception(exc)<br>  return JSONResponse(...)

• 别在 handler 里只 log，不 capture_exception() —— 日志不会自动转成 Sentry Event

环境名、Release 版本、用户信息怎么传进去

靠 init() 的参数或 configure_scope() 动态补全。硬编码在 init() 里适合简单场景；需要按请求动态设（比如用户 ID），就得在中间件或 handler 里用 configure_scope()。

• 环境名必须设，否则所有事件混在 production 下：init(..., environment="staging")
• Release 推荐用 git commit hash：init(..., release=os.environ.get("GIT_COMMIT"))
• 用户信息不能放敏感字段（如密码、Token），只传 id、email（脱敏后）、username：

  with configure_scope() as scope:<br>  scope.user = {"id": user_id, "email": masked_email}

• Scope 是线程/协程局部的，FastAPI 的 async context 没问题；但多线程服务（如 Celery）要确保每个 task 单独 set scope

本地开发时异常总上报，怎么关掉

不是靠删 init()，而是用 before_send 钩子拦截。它比环境变量开关更可靠，因为有些异常可能来自第三方库，绕过了环境判断逻辑。

• 最简方案：init(..., before_send=Lambda event, _: None if os.getenv("DEBUG") else event)
• 注意：返回 None 表示丢弃，返回 event 才会上报；别写成 return event if ... else None 然后忘了 return
• 不要用 traces_sample_rate=0 关闭性能监控来“顺便”停异常上报——两者独立，异常上报不受采样率影响
• Celery task 里如果也想关，得在 task 内部单独配 before_send，因为 worker 初始化时可能已读取了环境变量

最麻烦的是异步任务和信号处理器里的异常 —— 它们脱离主请求生命周期，scope 不自动继承，容易漏传上下文。这时候得手动在 task 开头 configure_scope()，或者用 with push_scope() 包一层。