sentry-python-sdk

Sentry Python SDK

有主见的向导，可扫描你的 Python 项目并引导你完成完整的 Sentry 设置。

在以下情况调用此 Skill

• 用户要求在 Python 应用中“添加 Sentry”或“设置 Sentry”
• 用户希望在 Python 中进行错误监控、追踪、性能分析、日志记录、指标或定时任务
• 用户提到 sentry-sdk、sentry_sdk 或 Sentry + 任何 Python 框架
• 用户希望监控 Django 视图、Flask 路由、FastAPI 端点、Celery 任务或计划任务

注意： 下方的 SDK 版本和 API 反映的是撰写时的 Sentry 文档（sentry-sdk 2.x）。 在实现之前，请务必对照 docs.sentry.io/platforms/python/ 进行核实。

---

阶段 1：检测

运行以下命令，在给出建议之前先了解项目：

# Check existing Sentry
grep -i sentry requirements.txt pyproject.toml setup.cfg setup.py 2>/dev/null

# Detect web framework
grep -rE "django|flask|fastapi|starlette|aiohttp|tornado|quart|falcon|sanic|bottle" \
  requirements.txt pyproject.toml 2>/dev/null

# Detect task queues
grep -rE "celery|rq|huey|arq|dramatiq" requirements.txt pyproject.toml 2>/dev/null

# Detect logging libraries
grep -E "loguru" requirements.txt pyproject.toml 2>/dev/null

# Detect AI libraries
grep -rE "openai|anthropic|langchain|huggingface|google-genai|pydantic-ai|litellm" \
  requirements.txt pyproject.toml 2>/dev/null

# Detect schedulers / crons
grep -rE "celery|apscheduler|schedule|crontab" requirements.txt pyproject.toml 2>/dev/null

# Check for companion frontend
ls frontend/ web/ client/ ui/ static/ templates/ 2>/dev/null

需要留意的内容：

• sentry-sdk 是否已在 requirements 中？如果是，检查是否存在 sentry_sdk.init() —— 可能只需要配置功能。
• 是哪个框架？（决定将 sentry_sdk.init() 放在哪里。）
• 是哪个任务队列？（Celery 需要双进程初始化；RQ 需要设置文件。）
• 是否有 AI 库？（OpenAI、Anthropic、LangChain 会自动插桩。）
• 是否有配套前端？（触发阶段 4 的交叉链接。）

---

阶段 2：建议

根据你的发现，提出具体方案。不要问开放式问题 —— 先给出建议：

始终推荐（核心覆盖）：

• ✅ 错误监控 —— 捕获未处理的异常，支持 ExceptionGroup（Python 3.11+）
• ✅ 日志记录 —— Python logging 标准库自动捕获；如果检测到 Loguru 则增强

检测到以下情况时推荐：

• ✅ 追踪 —— 检测到 HTTP 框架（Django/Flask/FastAPI/等）
• ✅ AI 监控 —— 检测到 OpenAI/Anthropic/LangChain/等（自动插桩，零配置）
• ⚡ 性能分析 —— 性能至关重要的生产应用
• ⚡ 定时任务 —— 检测到 Celery Beat、APScheduler 或 cron 模式
• ⚡ 指标 —— 业务 KPI、SLO 跟踪

推荐矩阵：

功能	在以下情况推荐……	参考
错误监控	始终 —— 不可协商的基线	${SKILL_ROOT}/references/error-monitoring.md
追踪	检测到 Django/Flask/FastAPI/AIOHTTP/等	${SKILL_ROOT}/references/tracing.md
性能分析	生产环境 + 性能敏感型工作负载	${SKILL_ROOT}/references/profiling.md
日志记录	始终（标准库）；对 Loguru 增强	${SKILL_ROOT}/references/logging.md
指标	需要业务事件或 SLO 跟踪	${SKILL_ROOT}/references/metrics.md
定时任务	Celery Beat、APScheduler 或 cron 模式	${SKILL_ROOT}/references/crons.md
AI 监控	检测到 OpenAI/Anthropic/LangChain/等	${SKILL_ROOT}/references/ai-monitoring.md

建议：“我推荐错误监控 + 追踪 [+ 日志记录（如适用）]。还想要性能分析、定时任务或 AI 监控吗？”

---

阶段 3：引导

安装

# Core SDK (always required)
pip install sentry-sdk

# Optional extras (install only what matches detected framework):
pip install "sentry-sdk[django]"
pip install "sentry-sdk[flask]"
pip install "sentry-sdk[fastapi]"
pip install "sentry-sdk[celery]"
pip install "sentry-sdk[aiohttp]"
pip install "sentry-sdk[tornado]"

# Multiple extras:
pip install "sentry-sdk[django,celery]"

附加组件是可选的 —— 普通的 sentry-sdk 适用于所有框架。附加组件会安装补充包。

快速开始 —— 推荐的初始化

完整初始化，启用最多功能并采用合理默认值。放在任何应用/框架代码之前：

import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    environment=os.environ.get("SENTRY_ENVIRONMENT", "production"),
    release=os.environ.get("SENTRY_RELEASE"),   # e.g. "[email protected]"
    send_default_pii=True,

    # Tracing (lower to 0.1–0.2 in high-traffic production)
    traces_sample_rate=1.0,

    # Profiling — continuous, tied to active spans
    profile_session_sample_rate=1.0,
    profile_lifecycle="trace",

    # Structured logs (SDK ≥ 2.35.0)
    enable_logs=True,
)

各框架的初始化位置

框架	调用 sentry_sdk.init() 的位置	说明
Django	settings.py 顶部，在任何导入之前	无需中间件 — Sentry 会在内部对 Django 打补丁
Flask	在 app = Flask(__name__) 之前	必须早于应用创建
FastAPI	在 app = FastAPI() 之前	StarletteIntegration + FastApiIntegration 会自动一起启用
Starlette	在 app = Starlette(...) 之前	自动集成方式与 FastAPI 相同
AIOHTTP	模块级，在 web.Application() 之前
Tornado	模块级，在应用设置之前	无需集成类
Quart	在 app = Quart(__name__) 之前
Falcon	模块级，在 app = falcon.App() 之前
Sanic	在 @app.listener("before_server_start") 内	Sanic 的生命周期要求异步初始化
Celery	在 worker 和调用进程中均使用 @signals.celeryd_init.connect	需要双进程初始化
RQ	worker 通过 rq worker -c mysettings 加载 mysettings.py
ARQ	worker 模块和入队进程都要

Django 示例（settings.py）：

import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    send_default_pii=True,
    traces_sample_rate=1.0,
    profile_session_sample_rate=1.0,
    profile_lifecycle="trace",
    enable_logs=True,
)

# rest of Django settings...
INSTALLED_APPS = [...]

FastAPI 示例（main.py）：

import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    send_default_pii=True,
    traces_sample_rate=1.0,
    profile_session_sample_rate=1.0,
    profile_lifecycle="trace",
    enable_logs=True,
)

from fastapi import FastAPI
app = FastAPI()

自动启用与显式集成

大多数集成在安装其包后会自动激活 — 无需 integrations=[...]：

自动启用	需要显式指定
Django、Flask、FastAPI、Starlette、AIOHTTP、Tornado、Quart、Falcon、Sanic、Bottle	DramatiqIntegration
Celery、RQ、Huey、ARQ	GRPCIntegration
SQLAlchemy、Redis、asyncpg、pymongo	StrawberryIntegration
Requests、HTTPX、aiohttp-client	AsyncioIntegration
OpenAI、Anthropic、LangChain、Pydantic AI、MCP	OpenTelemetryIntegration
Python logging、Loguru	WSGIIntegration / ASGIIntegration

针对每个已确认的功能

逐个功能地进行。加载参考文档，按照其中的步骤操作，验证后再继续：

功能	参考文件	加载时机...
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终（基线）
链路追踪	${SKILL_ROOT}/references/tracing.md	HTTP 处理器 / 分布式追踪
性能分析	${SKILL_ROOT}/references/profiling.md	性能敏感的生产环境
日志	${SKILL_ROOT}/references/logging.md	始终；针对 Loguru 增强
指标	${SKILL_ROOT}/references/metrics.md	业务 KPI / SLO 跟踪
定时任务	${SKILL_ROOT}/references/crons.md	检测到调度器 / 定时任务模式
AI 监控	${SKILL_ROOT}/references/ai-monitoring.md	检测到 AI 库

对于每个功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按步骤操作，验证其可用。

---

配置参考

sentry_sdk.init() 的关键选项

选项	类型	默认值	用途
dsn	str	None	为空时禁用 SDK；环境变量：SENTRY_DSN
environment	str	"production"	例如 "staging"；环境变量：SENTRY_ENVIRONMENT
release	str	None	例如 "[email protected]"；环境变量：SENTRY_RELEASE
send_default_pii	bool	False	包含 IP、headers、cookies、认证用户
traces_sample_rate	float	None	事务采样率；None 禁用追踪
traces_sampler	Callable	None	自定义按事务采样（覆盖采样率）
profile_session_sample_rate	float	None	持续性能分析会话采样率
profile_lifecycle	str	"manual"	"trace" = 随 span 自动启动 profiler
profiles_sample_rate	float	None	基于事务的性能分析采样率
enable_logs	bool	False	将日志发送到 Sentry（SDK ≥ 2.35.0）
sample_rate	float	1.0	错误事件采样率
attach_stacktrace	bool	False	在 capture_message() 时附加堆栈跟踪
max_breadcrumbs	int	100	每个事件的最大 breadcrumb 数
debug	bool	False	输出详细的 SDK 调试信息
before_send	Callable	None	用于修改/丢弃错误事件的钩子
before_send_transaction	Callable	None	用于修改/丢弃事务事件的钩子
ignore_errors	list	[]	要抑制的异常类型或正则表达式模式
auto_enabling_integrations	bool	True	设为 False 可禁用所有自动检测

环境变量

变量	映射到	备注
SENTRY_DSN	dsn
SENTRY_RELEASE	release	也会从 git SHA、Heroku、CircleCI、CodeBuild、GAE 自动检测
SENTRY_ENVIRONMENT	environment
SENTRY_DEBUG	debug

---

验证

测试 Sentry 是否正在接收事件：

# Trigger a real error event — check dashboard within seconds
division_by_zero = 1 / 0

或者进行不崩溃的检查：

sentry_sdk.capture_message("Sentry Python SDK test")

如果没有任何内容出现：

1. 在 sentry_sdk.init() 中设置 debug=True — 将 SDK 内部信息打印到 stdout
2. 验证 DSN 是否正确
3. 检查运行中的进程是否设置了 SENTRY_DSN 环境变量
4. 对于 Celery/RQ：确保初始化在 worker 进程中运行，而不仅仅是在调用进程中

---

第 4 阶段：交叉链接

完成 Python 设置后，检查是否有缺少 Sentry 的配套前端：

ls frontend/ web/ client/ ui/ 2>/dev/null
cat frontend/package.json web/package.json client/package.json 2>/dev/null \
  | grep -E '"react"|"svelte"|"vue"|"next"|"nuxt"'

如果存在没有 Sentry 的前端，建议匹配的技能：

检测到的前端	建议技能
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue / Nuxt	使用 @sentry/vue — 参见 docs.sentry.io/platforms/javascript/guides/vue/
其他 JS/TS	sentry-react-sdk（涵盖通用浏览器 JS 模式）

---

疑难解答

问题	解决方案
事件未显示	设置 debug=True，验证 DSN，检查运行进程中的环境变量
DSN 格式错误	格式：https://<key>@o<org>.ingest.sentry.io/<project>
未捕获 Django 异常	确保 sentry_sdk.init() 位于 settings.py 的顶部，在其他导入之前
未捕获 Flask 异常	初始化必须在 app = Flask(__name__) 之前进行
未捕获 FastAPI 异常	在 app = FastAPI() 之前初始化；StarletteIntegration 和 FastApiIntegration 均自动启用
未捕获 Celery 任务错误	必须通过 celeryd_init 信号在 worker 进程中调用 sentry_sdk.init()
Sanic 初始化不生效	初始化必须位于 @app.listener("before_server_start") 内部，而非模块级别
uWSGI 未捕获	在 uWSGI 命令中添加 --enable-threads --py-call-uwsgi-fork-hooks
未显示 trace	验证 traces_sample_rate 已设置（非 None）；检查集成是否自动启用
Profiling 未启动	需要 traces_sample_rate > 0，并且设置 profile_session_sample_rate 或 profiles_sample_rate
enable_logs 不生效	需要 SDK ≥ 2.35.0；直接结构化日志使用 sentry_sdk.logger；标准库桥接使用 LoggingIntegration(sentry_logs_level=...)
事务过多	降低 traces_sample_rate 或使用 traces_sampler 丢弃健康检查
跨请求数据泄漏	不要使用 get_global_scope() 处理每请求数据 — 请使用 get_isolation_scope()
RQ worker 未上报	传入 --sentry-dsn="" 以禁用 RQ 自带的 Sentry 快捷方式；改为通过设置文件初始化