sentry-python-sdk

すべてのスキル > SDK のセットアップ > 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/ で確認してください。

---

Phase 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 では 2 つのプロセスでの初期化が必要です。RQ では設定ファイルが必要です。）
• AI ライブラリを使用していますか？（OpenAI、Anthropic、LangChain は自動計装されます。）
• OpenTelemetry トレーシングを使用していますか？（ネイティブトレーシングではなく、OTLP 経由の方法を使用してください。）
• 併用するフロントエンドはありますか？（Phase 4 の相互リンクが必要になります。）

---

Phase 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 経由の方法では利用できません
• ⚡ Cron — 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
Cron	Celery Beat、APScheduler、または cron のパターンがある場合	${SKILL_ROOT}/references/crons.md
AI 監視	OpenAI/Anthropic/LangChain などが検出された場合	${SKILL_ROOT}/references/ai-monitoring.md

OTel トレーシングを検出： 「プロジェクトで OpenTelemetry トレーシングが使われているようです。既存の OTel セットアップを利用した Sentry の OTLP インテグレーションによるトレーシングと、エラー監視、Sentry ログ記録［該当する場合は、メトリクス／Cron／AI 監視も］をおすすめします。進めてもよいですか？」

OTel なし： 「エラー監視とトレーシング［該当する場合はログ記録も］をおすすめします。プロファイリング、Cron、AI 監視も追加しますか？」

---

Phase 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	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、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

合意された各機能について

機能を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、認証ユーザー、クエリ文字列（ASGI フレームワーク）を含めます
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 に設定します

OTLPIntegration のオプション（コンストラクターに渡します）

オプション	型	デフォルト	目的
setup_otlp_traces_exporter	bool	True	OTLP エクスポーターを自動設定します。独自の Collector に送信する場合は False に設定します
collector_url	str	None	OTel Collector の OTLP HTTP エンドポイント（例：http://localhost:4318/v1/traces）。設定すると、スパンは Sentry に直接送信されず、Collector に送信されます
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 の内部情報が標準出力に表示されます
2. DSN が正しいことを確認します
3. 実行中のプロセスで SENTRY_DSN 環境変数が設定されていることを確認します
4. Celery/RQ の場合：init が呼び出し元のプロセスだけでなく、ワーカープロセスでも実行されることを確認します

---

フェーズ 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 はどちらも自動的に有効になります
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 ワーカーが報告しない	RQ 独自の Sentry ショートカットを無効にするには --sentry-dsn="" を渡し、代わりに設定ファイル経由で初期化します