sentry-python-setup

Sentry Python 设置

在 Python 项目中安装并配置 Sentry。

何时使用本技能

• 用户要求在 Python 应用中“添加 Sentry”或“安装 Sentry”
• 用户希望在 Python 中进行错误监控、日志记录或链路追踪
• 用户提到“sentry-sdk”或 Python 框架（Django、Flask、FastAPI）

重要： 下方的配置选项和代码示例仅为示例。实施前请务必对照 docs.sentry.io 进行核实，因为 API 和默认值可能已发生变化。

安装

pip install sentry-sdk

配置

在应用中尽可能早地初始化：

import sentry_sdk

sentry_sdk.init(
    dsn="YOUR_SENTRY_DSN",
    send_default_pii=True,
    
    # Tracing
    traces_sample_rate=1.0,
    
    # Profiling
    profile_session_sample_rate=1.0,
    profile_lifecycle="trace",
    
    # Logs
    enable_logs=True,
)

异步应用

对于异步应用，在异步函数内部初始化：

import asyncio
import sentry_sdk

async def main():
    sentry_sdk.init(
        dsn="YOUR_SENTRY_DSN",
        send_default_pii=True,
        traces_sample_rate=1.0,
        enable_logs=True,
    )
    # ... rest of app

asyncio.run(main())

框架集成

使用上面所示的同一个 sentry_sdk.init() 调用。将它放在应用启动之前运行的位置：

框架	初始化位置	说明
Django	settings.py 顶部	自动检测 Django，无需额外安装
Flask	在 app = Flask(__name__) 之前	自动检测 Flask
FastAPI	在 app = FastAPI() 之前	自动检测 FastAPI
Celery	在 Celery worker 配置中	自动检测 Celery
AIOHTTP	在应用创建之前	自动检测 AIOHTTP

配置选项

选项	描述	默认值	最低 SDK
dsn	Sentry DSN	None（没有它时 SDK 不执行任何操作）	—
send_default_pii	包含用户数据	None	—
traces_sample_rate	被追踪的事务百分比	None（追踪已禁用）	—
profile_session_sample_rate	被性能分析的会话百分比	None（性能分析已禁用）	2.24.1+
profile_lifecycle	性能分析模式（"trace" 或 "manual"）	"manual"	2.24.1+
enable_logs	将日志发送到 Sentry	False	2.35.0+
environment	环境名称	"production"（或 SENTRY_ENVIRONMENT 环境变量）	—
release	发布版本	自动检测	—

环境变量

SDK 会自动读取这些变量：

SENTRY_DSN=https://[email protected]/456
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0

对于 sentry-cli（source maps、releases），还需设置：

SENTRY_AUTH_TOKEN=sntrys_xxx
SENTRY_ORG=my-org
SENTRY_PROJECT=my-project

或在代码中传入 DSN：

import os
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ.get("SENTRY_DSN"),
    # ...
)

验证

# Intentional error to test
division_by_zero = 1 / 0

或手动捕获：

sentry_sdk.capture_message("Test message from Python")

故障排除

问题	解决方案
错误未出现	确保尽早调用 init()，检查 DSN
没有追踪数据	将 traces_sample_rate 设置为大于 0
IPython 错误未被捕获	从文件运行，而不是交互式 shell
异步错误缺失	在异步函数内部初始化