sentry_sdk.init()必须在所有业务代码执行前于入口文件最顶部调用，否则异常发生时SDK未接管全局钩子；需配合框架Integration、显式设environment="production"、避免重复初始化。
为什么直接 import sentry_sdk.init() 不生效
常见现象是代码里写了 sentry_sdk.init()，但线上报错依然没进 Sentry。根本原因是初始化时机不对——必须在所有业务代码执行前完成，否则异常发生时 SDK 还没接管全局异常钩子。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 把
sentry_sdk.init()放在项目入口文件最顶部（比如main.py或app.py开头），确保早于from myapp import app或uvicorn.run() - 避免写在函数里、类里或配置加载之后；Django/Flask 的
settings.py或__init__.py里调用也不可靠 - 检查是否重复初始化：多次调用
sentry_sdk.init()会静默失败，可用sentry_sdk.is_initialized()验证
如何让 Flask/FastAPI/Django 自动捕获路由异常
默认情况下，sentry_sdk 能自动集成 Flask 和 FastAPI，但需要显式启用对应集成模块；Django 则依赖 django.conf.settings 加载时机。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- Flask：确保安装时带
flask额外依赖（pip install "sentry-sdk[flask]"），然后sentry_sdk.init(..., integrations=[FlaskIntegration()]) - FastAPI：同理用
FastApiIntegration()，注意它依赖 Starlette，别漏装starlette - Django：不需手动传 integration，但必须保证
sentry_sdk.init()在django.setup()之后、URL 路由加载之前执行；推荐放在manage.py或wsgi.py中 - Web 框架外的后台任务（如 Celery、APScheduler）需单独配
CeleryIntegration()等，否则任务内异常不会上报
生产环境必须设置的三个关键参数
本地能上报 ≠ 生产能上报。常见失效原因是未关掉采样、没设环境标识、或 DSN 权限受限。
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
environment必须显式设为"production"或"staging"，否则默认是"development"，Sentry 控制台可能过滤掉 -
sample_rate建议设为1.0（全量）或至少0.1，避免因默认1.0却被反向代理/Nginx 重写 Host 导致匹配失败而降级为 0 -
dsn必须用后端专用 DSN（以https://xxx@oxxx.ingest.sentry.io/xxx开头），不能用前端 DSN（含.public.字样），否则 403 被拒 - 额外建议：加
release=os.environ.get("RELEASE", "unknown")，方便关联 commit 版本；用server_name区分多实例
为什么 500 错误没上报，但手动 capture_exception() 可以
这说明 SDK 初始化成功，但框架异常拦截没生效。典型场景是：WSGI/ASGI 中间件顺序错乱、异步上下文丢失、或错误发生在 Sentry 初始化前的早期阶段（如配置解析失败）。
排查路径：
- 开 debug 模式：
sentry_sdk.init(..., debug=True)，看日志里是否有Not capturing event: ...或Failed to bind scope - 检查是否用了
try/except吞掉了异常且没 re-raise —— Sentry 只捕获未处理异常 - 异步服务（FastAPI/Uvicorn）中，确保没在
async def里用time.sleep()这类阻塞调用导致事件循环卡住，影响 SDK 异步发送 - 容器环境注意时区和系统时间是否严重偏差，Sentry 服务端会拒收时间戳超前/滞后过久的事件
"Production" 和 "production" 是两个环境；还有 DSN 里 project ID 是否对应当前团队的实际项目，换环境时经常粘贴错。 
