sentry-python-sdk

Sentry Python SDK

Python プロジェクトをスキャンし、Sentry の完全なセットアップを案内する、独自の方針を持つウィザードです。

このスキルを呼び出すタイミング

• ユーザーが Python アプリへの「Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが Python でのエラー監視、トレーシング、プロファイリング、ログ記録、メトリクス、または cron の利用を希望する場合
• ユーザーが 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 などが検出された場合（自動計測、設定不要）
• ⚡ プロファイリング — パフォーマンスが重要な本番アプリ
• ⚡ cron — 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
cron	Celery Beat、APScheduler、または cron のパターンがある場合	${SKILL_ROOT}/references/crons.md
AI 監視	OpenAI／Anthropic／LangChain などが検出された場合	${SKILL_ROOT}/references/ai-monitoring.md

次のように提案してください：「エラー監視とトレーシングをおすすめします［該当する場合はログ記録も］。プロファイリング、cron、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]"

Extras は任意です。通常の sentry-sdk であらゆるフレームワークに対応できます。Extras をインストールすると、関連パッケージが追加されます。

クイックスタート — 推奨される初期化

妥当なデフォルト設定で多くの機能を有効にする、完全な初期化方法です。アプリやフレームワークのコードより前に配置してください。

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	ワーカーと呼び出し元プロセスの両方で、@signals.celeryd_init.connect を使用します	2つのプロセスで初期化する必要があります
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、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

合意した各機能について

機能を一度に1つずつ確認します。リファレンスを読み、その手順に従い、次に進む前に動作を検証してください。

機能	リファレンスファイル	読み込むタイミング
エラーモニタリング	${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 のトラッキング
Cron	${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、認証済みユーザーを含めます
traces_sample_rate	float	None	トランザクションのサンプリング率。None の場合、トレーシングは無効になります
traces_sampler	Callable	None	トランザクションごとのカスタムサンプリング（サンプリング率より優先）
profile_session_sample_rate	float	None	継続的プロファイリングセッションのサンプリング率
profile_lifecycle	str	"manual"	"trace" の場合、スパンとともにプロファイラーを自動起動します
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 を設定します

環境変数

変数	対応するオプション	備考
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 の内部情報が標準出力に表示されます
2. DSN が正しいことを確認します
3. 実行中のプロセスで SENTRY_DSN 環境変数が設定されていることを確認します
4. Celery/RQ の場合：呼び出し元のプロセスだけでなく、ワーカープロセスで初期化が実行されることを確認します

---

フェーズ 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 シグナルを介して、ワーカープロセス内で sentry_sdk.init() を呼び出す必要があります
Sanic の初期化が機能しない	モジュールレベルではなく、@app.listener("before_server_start") の内部で初期化する必要があります
uWSGI がデータを捕捉しない	uWSGI コマンドに --enable-threads --py-call-uwsgi-fork-hooks を追加してください
トレースが表示されない	traces_sample_rate が設定されている（None ではない）ことを確認してください。インテグレーションが自動的に有効になっているか確認してください
プロファイリングが開始されない	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 ワーカーが報告しない	RQ 独自の Sentry ショートカットを無効にするには --sentry-dsn="" を渡してください。代わりに設定ファイルから初期化してください