sentry-python-sdk

所有技能 > SDK 设置 > Python SDK

Sentry Python SDK

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

在以下情况下调用此技能

• 用户要求在 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|pyramid" \
  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

# OpenTelemetry tracing — check for SDK + instrumentations
grep -rE "opentelemetry-sdk|opentelemetry-instrumentation|opentelemetry-distro" \
  requirements.txt pyproject.toml 2>/dev/null
grep -rn "TracerProvider\|trace\.get_tracer\|start_as_current_span" \
  --include="*.py" 2>/dev/null | head -5

# 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 会自动插桩。）
• 是否使用了 OpenTelemetry 追踪？（使用 OTLP 路径，而非原生追踪。）
• 是否有配套的前端？（会触发阶段 4 的交叉链接。）

---

阶段 2：提出建议

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

根据 OTel 检测结果选择路径：

• 检测到 OTel 追踪（requirements 中包含 opentelemetry-sdk / opentelemetry-distro，或源代码中包含 TracerProvider）→ 使用 OTLP 路径：OTLPIntegration()；不要设置 traces_sample_rate；Sentry 会自动将错误关联到 OTel 追踪

始终推荐（核心覆盖）：

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

检测到以下情况时推荐：

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

建议矩阵：

功能	推荐时机……	参考
错误监控	始终 — 必不可少的基线	${SKILL_ROOT}/references/error-monitoring.md
OTLP 集成	检测到 OTel 追踪时 — 取代原生追踪	${SKILL_ROOT}/references/tracing.md
追踪	检测到 Django/Flask/FastAPI/AIOHTTP 等时；检测到 OTel 追踪时跳过	${SKILL_ROOT}/references/tracing.md
性能分析	生产环境 + 对性能敏感的工作负载；检测到 OTel 追踪时跳过（需要 traces_sample_rate，与 OTLP 不兼容）	${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

检测到 OTel 追踪： “我发现项目中使用了 OpenTelemetry 追踪。我建议使用 Sentry 的 OTLP 集成进行追踪（通过你现有的 OTel 设置），并启用错误监控和 Sentry 日志记录[+视情况启用指标监控/定时任务/AI 监控]。要继续吗？”

未检测到 OTel： “我建议启用错误监控和追踪[+视情况启用日志记录]。还需要性能分析、定时任务或 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() 之前
Pyramid	模块级别，在 config = Configurator() 之前	WSGI 框架
Sanic	在 @app.listener("before_server_start") 中	Sanic 的生命周期要求进行异步初始化
Celery	在工作进程中使用 @signals.celeryd_init.connect，并在调用进程中初始化	需要在两个进程中初始化
RQ	工作进程通过 rq worker -c mysettings 加载的 mysettings.py
ARQ	工作进程模块和入队进程中都需要初始化

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、Pyramid、Sanic、Bottle	DramatiqIntegration
Celery、RQ、Huey、ARQ	GRPCIntegration
SQLAlchemy、Redis、asyncpg、pymongo	StrawberryIntegration
Requests、HTTPX、httpx2、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	检测到调度器／cron 模式
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、标头、Cookie、身份验证用户和查询字符串（ASGI 框架）
traces_sample_rate	float	None	事务采样率；None 表示禁用追踪
traces_sampler	Callable	None	自定义每笔事务的采样（优先于采样率）
profile_session_sample_rate	float	None	连续性能分析会话采样率
profile_lifecycle	str	"manual"	"trace" = 随 Span 自动启动性能分析器
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	每个事件的面包屑上限
debug	bool	False	输出详细的 SDK 调试信息
before_send	Callable	None	用于修改或丢弃错误事件的钩子
before_send_transaction	Callable	None	用于修改或丢弃事务事件的钩子
ignore_errors	list	[]	要抑制的异常类型或正则表达式模式
auto_enabling_integrations	bool	True	设为 False 可禁用所有自动检测

OTLPIntegration 选项（传入构造函数）

选项	类型	默认值	用途
setup_otlp_traces_exporter	bool	True	自动配置 OTLP 导出器；如果要发送到自己的 Collector，请设为 False
collector_url	str	None	OTel Collector 的 OTLP HTTP 端点（例如 http://localhost:4318/v1/traces）；设置后，Span 会发送到 Collector，而不是直接发送到 Sentry
setup_propagator	bool	True	自动配置用于分布式追踪的 Sentry 传播器
capture_exceptions	bool	False	拦截通过 OTel Span.record_exception 记录的异常

环境变量

变量	映射到	备注
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 异常	确保在 settings.py 的顶部、其他导入之前调用 sentry_sdk.init()
未捕获 Flask 异常	必须在 app = Flask(__name__) 之前完成初始化
未捕获 FastAPI 异常	在 app = FastAPI() 之前初始化；StarletteIntegration 和 FastApiIntegration 均会自动启用
ASGI 链式异常被抑制	默认情况下，Sentry 的 ASGI 中间件会移除异常链（raise exc from None）。若要保留链式异常，请在 sentry_sdk.init() 中设置 _experiments={"suppress_asgi_chained_exceptions": False}
未捕获 Celery 任务错误	必须通过 celeryd_init 信号在工作进程中调用 sentry_sdk.init()
Sanic 初始化无效	必须在 @app.listener("before_server_start") 内初始化，而不是在模块级别初始化
uWSGI 未捕获错误	在 uWSGI 命令中添加 --enable-threads --py-call-uwsgi-fork-hooks
未显示跟踪（原生）	确认已设置 traces_sample_rate（而非 None）；检查集成是否已自动启用
未显示跟踪（OTLP）	确认已安装 sentry-sdk[opentelemetry-otlp]；使用 OTLPIntegration 时不要设置 traces_sample_rate
性能分析未启动	需要 traces_sample_rate > 0，且还需设置 profile_session_sample_rate 或 profiles_sample_rate；与 OTLP 路径不兼容
enable_logs 无效	需要 SDK ≥ 2.35.0；直接使用结构化日志时，请使用 sentry_sdk.logger；使用标准库桥接时，请使用 LoggingIntegration(sentry_logs_level=...)
事务过多	降低 traces_sample_rate，或使用 traces_sampler 丢弃运行状况检查
跨请求数据泄漏	不要将 get_global_scope() 用于每个请求的数据——请使用 get_isolation_scope()
未捕获查询字符串（ASGI）	ASGI 框架（FastAPI、Starlette 等）中的查询字符串和客户端 IP 需要设置 send_default_pii=True
RQ 工作进程未报告	传入 --sentry-dsn="" 以禁用 RQ 自带的 Sentry 快捷方式；改用设置文件进行初始化