All Skills > SDK Setup > Python SDK

Sentry Python SDK

Pythonプロジェクトをスキャンして完全なSentryセットアップをガイドする見識に基づいたウィザード。

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

• ユーザーが「Pythonに Sentry を追加して」や「Python アプリにセットアップして」と要求した場合
• ユーザーが Python でエラー監視、トレーシング、プロファイリング、ロギング、メトリクス、またはクロンを望んでいる場合
• ユーザーが sentry-sdk、sentry_sdk、または Sentry + Python フレームワークに言及した場合
• ユーザーが Django ビュー、Flask ルート、FastAPI エンドポイント、Celery タスク、またはスケジュール済みジョブを監視したい場合

注: 以下の SDK バージョンと API は、このドキュメント作成時点の Sentry ドキュメント (sentry-sdk 2.x) を反映しています。 実装する前に必ず docs.sentry.io/platforms/python/ で確認してください。

---

フェーズ 1: 検出

推奨を行う前にプロジェクトを理解するために次のコマンドを実行してください:

# 既存の Sentry をチェック
grep -i sentry requirements.txt pyproject.toml setup.cfg setup.py 2>/dev/null

# Web フレームワークを検出
grep -rE "django|flask|fastapi|starlette|aiohttp|tornado|quart|falcon|sanic|bottle" \
  requirements.txt pyproject.toml 2>/dev/null

# タスクキューを検出
grep -rE "celery|rq|huey|arq|dramatiq" requirements.txt pyproject.toml 2>/dev/null

# ロギングライブラリを検出
grep -E "loguru" requirements.txt pyproject.toml 2>/dev/null

# AI ライブラリを検出
grep -rE "openai|anthropic|langchain|huggingface|google-genai|pydantic-ai|litellm" \
  requirements.txt pyproject.toml 2>/dev/null

# スケジューラー / クロンを検出
grep -rE "celery|apscheduler|schedule|crontab" requirements.txt pyproject.toml 2>/dev/null

# OpenTelemetry トレーシング — SDK + インストルメンテーションをチェック
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

# コンパニオンフロントエンドをチェック
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、またはクロンパターンが検出された
• ⚡ メトリクス — ビジネス 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、またはクロンパターン	${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: ガイド

インストール

# コア SDK (常に必須)
pip install sentry-sdk

# オプションの追加機能 (検出されたフレームワークに一致するもののみをインストール):
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]"

# 複数の追加機能:
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. "myapp@1.0.0"
    send_default_pii=True,

    # トレーシング (トラフィックの多い本番環境では 0.1～0.2 に低下)
    traces_sample_rate=1.0,

    # プロファイリング — 連続、アクティブなスパンに関連付け
    profile_session_sample_rate=1.0,
    profile_lifecycle="trace",

    # 構造化ログ (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 内	デュアルプロセス初期化が必須
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,
)

# Django 設定の残り...
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()

自動有効化 vs 明示的インテグレーション

ほとんどのインテグレーションは、そのパッケージがインストールされると自動的にアクティベートされます — 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 トラッキング
クロン	${SKILL_ROOT}/references/crons.md	スケジューラー / クロンパターンが検出
AI 監視	${SKILL_ROOT}/references/ai-monitoring.md	AI ライブラリが検出

各機能について: ${SKILL_ROOT}/references/<feature>.md を読み、手順に従い、機能を確認します。

---

設定リファレンス

主要な sentry_sdk.init() オプション

オプション	型	デフォルト	目的
dsn	str	None	空の場合は SDK が無効; 環境変数: SENTRY_DSN
environment	str	"production"	例: "staging"; 環境変数: SENTRY_ENVIRONMENT
release	str	None	例: "myapp@1.0.0"; 環境変数: SENTRY_RELEASE
send_default_pii	bool	False	IP、ヘッダー、クッキー、認証ユーザーを含める
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 がイベントを受け取っていることをテストしてください:

# 実際のエラーイベントをトリガー — 数秒以内にダッシュボードでチェック
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 の場合: 初期化が呼び出しプロセスだけでなくワーカープロセスで実行されていることを確認

---

フェーズ 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() を使用
RQ ワーカーがレポートしない	--sentry-dsn="" を RQ の独自の Sentry ショートカットを無効化するために渡す; 代わりに設定ファイル経由で初期化