Sentry Python 异常上报集成指南

本文详细讲解了如何在Python项目中正确集成Sentry实现异常自动上报，涵盖初始化时机（必须在应用启动最早期、每个worker进程独立调用）、主流框架（Django/Flask/FastAPI）对500错误的特殊处理方式（需手动在error handler中调用capture_exception）、上下文信息（environment/release/user）的灵活注入技巧，以及本地开发时通过before_send精准拦截避免误报的实用策略，同时澄清了常见误区如重复init失效、日志处理器冗余配置、异步任务上下文丢失等问题，是一份兼顾原理与实战的高效排坑指南。

怎么让 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()。

• Flask 示例：

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

• FastAPI 示例：

  from fastapi import Request
  from sentry_sdk import capture_exception
  @app.exception_handler(500)
  async def unicorn_exception_handler(request: Request, exc: Exception):
    capture_exception(exc)
    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:
    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() 包一层。

到这里，我们也就讲完了《Sentry Python 异常上报集成指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！