Skills
skills/getsentry/sentry-for-ai/sentry-python-sdk

sentry-python-sdk

SKILL.md

All Skills > SDK Setup > Python SDK

Sentry Python SDK

Opinionated wizard that scans your Python project and guides you through complete Sentry setup.

Invoke This Skill When

  • User asks to "add Sentry to Python" or "setup Sentry" in a Python app
  • User wants error monitoring, tracing, profiling, logging, metrics, or crons in Python
  • User mentions sentry-sdk, sentry_sdk, or Sentry + any Python framework
  • User wants to monitor Django views, Flask routes, FastAPI endpoints, Celery tasks, or scheduled jobs

Note: SDK versions and APIs below reflect Sentry docs at time of writing (sentry-sdk 2.x). Always verify against docs.sentry.io/platforms/python/ before implementing.

Phase 1: Detect

Run these commands to understand the project before making recommendations:

# 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

# 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

What to note:

  • Is sentry-sdk already in requirements? If yes, check if sentry_sdk.init() is present — may just need feature config.
  • Which framework? (Determines where to place sentry_sdk.init().)
  • Which task queue? (Celery needs dual-process init; RQ needs a settings file.)
  • AI libraries? (OpenAI, Anthropic, LangChain are auto-instrumented.)
  • OpenTelemetry tracing? (Use OTLP path instead of native tracing.)
  • Companion frontend? (Triggers Phase 4 cross-link.)

Phase 2: Recommend

Based on what you found, present a concrete proposal. Don't ask open-ended questions — lead with a recommendation:

Route from OTel detection:

  • OTel tracing detected (opentelemetry-sdk / opentelemetry-distro in requirements, or TracerProvider in source) → use OTLP path: OTLPIntegration(); do not set traces_sample_rate; Sentry links errors to OTel traces automatically

Always recommended (core coverage):

  • ✅ Error Monitoring — captures unhandled exceptions, supports ExceptionGroup (Python 3.11+)
  • ✅ Logging — Python logging stdlib auto-captured; enhanced if Loguru detected

Recommend when detected:

  • ✅ Tracing — HTTP framework detected (Django/Flask/FastAPI/etc.)
  • ✅ AI Monitoring — OpenAI/Anthropic/LangChain/etc. detected (auto-instrumented, zero config)
  • ⚡ Profiling — production apps where performance matters; not available with OTLP path
  • ⚡ Crons — Celery Beat, APScheduler, or cron patterns detected
  • ⚡ Metrics — business KPIs, SLO tracking

Recommendation matrix:

Feature Recommend when... Reference
Error Monitoring Always — non-negotiable baseline ${SKILL_ROOT}/references/error-monitoring.md
OTLP Integration OTel tracing detected — replaces native Tracing ${SKILL_ROOT}/references/tracing.md
Tracing Django/Flask/FastAPI/AIOHTTP/etc. detected; skip if OTel tracing detected ${SKILL_ROOT}/references/tracing.md
Profiling Production + performance-sensitive workload; skip if OTel tracing detected (requires traces_sample_rate, incompatible with OTLP) ${SKILL_ROOT}/references/profiling.md
Logging Always (stdlib); enhanced for Loguru ${SKILL_ROOT}/references/logging.md
Metrics Business events or SLO tracking needed ${SKILL_ROOT}/references/metrics.md
Crons Celery Beat, APScheduler, or cron patterns ${SKILL_ROOT}/references/crons.md
AI Monitoring OpenAI/Anthropic/LangChain/etc. detected ${SKILL_ROOT}/references/ai-monitoring.md

OTel tracing detected: "I see OpenTelemetry tracing in the project. I recommend Sentry's OTLP integration for tracing (via your existing OTel setup) + Error Monitoring + Sentry Logging [+ Metrics/Crons/AI Monitoring if applicable]. Shall I proceed?"

No OTel: "I recommend Error Monitoring + Tracing [+ Logging if applicable]. Want Profiling, Crons, or AI Monitoring too?"

Phase 3: Guide

Install

# 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 are optional — plain sentry-sdk works for all frameworks. Extras install complementary packages.

Quick Start — Recommended Init

Full init enabling the most features with sensible defaults. Place before any app/framework code:

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,

    # 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,
)

Where to Initialize Per Framework

Framework Where to call sentry_sdk.init() Notes
Django Top of settings.py, before any imports No middleware needed — Sentry patches Django internally
Flask Before app = Flask(__name__) Must precede app creation
FastAPI Before app = FastAPI() StarletteIntegration + FastApiIntegration auto-enabled together
Starlette Before app = Starlette(...) Same auto-integration as FastAPI
AIOHTTP Module level, before web.Application()
Tornado Module level, before app setup No integration class needed
Quart Before app = Quart(__name__)
Falcon Module level, before app = falcon.App()
Sanic Inside @app.listener("before_server_start") Sanic's lifecycle requires async init
Celery @signals.celeryd_init.connect in worker AND in calling process Dual-process init required
RQ mysettings.py loaded by worker via rq worker -c mysettings
ARQ Both worker module and enqueuing process

Django example (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 example (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()

Auto-Enabled vs Explicit Integrations

Most integrations activate automatically when their package is installed — no integrations=[...] needed:

Auto-enabled Explicit required
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

For Each Agreed Feature

Walk through features one at a time. Load the reference, follow its steps, verify before moving on:

Feature Reference file Load when...
Error Monitoring ${SKILL_ROOT}/references/error-monitoring.md Always (baseline)
Tracing ${SKILL_ROOT}/references/tracing.md HTTP handlers / distributed tracing
Profiling ${SKILL_ROOT}/references/profiling.md Performance-sensitive production
Logging ${SKILL_ROOT}/references/logging.md Always; enhanced for Loguru
Metrics ${SKILL_ROOT}/references/metrics.md Business KPIs / SLO tracking
Crons ${SKILL_ROOT}/references/crons.md Scheduler / cron patterns detected
AI Monitoring ${SKILL_ROOT}/references/ai-monitoring.md AI library detected

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

Configuration Reference

Key sentry_sdk.init() Options

Option Type Default Purpose
dsn str None SDK disabled if empty; env: SENTRY_DSN
environment str "production" e.g., "staging"; env: SENTRY_ENVIRONMENT
release str None e.g., "myapp@1.0.0"; env: SENTRY_RELEASE
send_default_pii bool False Include IP, headers, cookies, auth user
traces_sample_rate float None Transaction sample rate; None disables tracing
traces_sampler Callable None Custom per-transaction sampling (overrides rate)
profile_session_sample_rate float None Continuous profiling session rate
profile_lifecycle str "manual" "trace" = auto-start profiler with spans
profiles_sample_rate float None Transaction-based profiling rate
enable_logs bool False Send logs to Sentry (SDK ≥ 2.35.0)
sample_rate float 1.0 Error event sample rate
attach_stacktrace bool False Stack traces on capture_message()
max_breadcrumbs int 100 Max breadcrumbs per event
debug bool False Verbose SDK debug output
before_send Callable None Hook to mutate/drop error events
before_send_transaction Callable None Hook to mutate/drop transaction events
ignore_errors list [] Exception types or regex patterns to suppress
auto_enabling_integrations bool True Set False to disable all auto-detection

OTLPIntegration Options (pass to constructor)

Option Type Default Purpose
setup_otlp_traces_exporter bool True Auto-configure OTLP exporter; set False if you send to your own Collector
collector_url str None OTLP HTTP endpoint of an OTel Collector (e.g., http://localhost:4318/v1/traces); when set, spans are sent to the collector instead of directly to Sentry
setup_propagator bool True Auto-configure Sentry propagator for distributed tracing
capture_exceptions bool False Intercept exceptions recorded via OTel Span.record_exception

Environment Variables

Variable Maps to Notes
SENTRY_DSN dsn
SENTRY_RELEASE release Also auto-detected from git SHA, Heroku, CircleCI, CodeBuild, GAE
SENTRY_ENVIRONMENT environment
SENTRY_DEBUG debug

Verification

Test that Sentry is receiving events:

# Trigger a real error event — check dashboard within seconds
division_by_zero = 1 / 0

Or for a non-crashing check:

sentry_sdk.capture_message("Sentry Python SDK test")

If nothing appears:

  1. Set debug=True in sentry_sdk.init() — prints SDK internals to stdout
  2. Verify the DSN is correct
  3. Check SENTRY_DSN env var is set in the running process
  4. For Celery/RQ: ensure init runs in the worker process, not just the calling process

Phase 4: Cross-Link

After completing Python setup, check for a companion frontend missing 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"'

If a frontend exists without Sentry, suggest the matching skill:

Frontend detected Suggest skill
React / Next.js sentry-react-sdk
Svelte / SvelteKit sentry-svelte-sdk
Vue / Nuxt Use @sentry/vue — see docs.sentry.io/platforms/javascript/guides/vue/
Other JS/TS sentry-react-sdk (covers generic browser JS patterns)

Troubleshooting

Issue Solution
Events not appearing Set debug=True, verify DSN, check env vars in the running process
Malformed DSN error Format: https://<key>@o<org>.ingest.sentry.io/<project>
Django exceptions not captured Ensure sentry_sdk.init() is at the top of settings.py before other imports
Flask exceptions not captured Init must happen before app = Flask(__name__)
FastAPI exceptions not captured Init before app = FastAPI(); both StarletteIntegration and FastApiIntegration auto-enabled
Celery task errors not captured Must call sentry_sdk.init() in the worker process via celeryd_init signal
Sanic init not working Init must be inside @app.listener("before_server_start"), not module level
uWSGI not capturing Add --enable-threads --py-call-uwsgi-fork-hooks to uWSGI command
No traces appearing (native) Verify traces_sample_rate is set (not None); check that the integration is auto-enabled
No traces appearing (OTLP) Verify sentry-sdk[opentelemetry-otlp] is installed; do not set traces_sample_rate when using OTLPIntegration
Profiling not starting Requires traces_sample_rate > 0 + either profile_session_sample_rate or profiles_sample_rate; not compatible with OTLP path
enable_logs not working Requires SDK ≥ 2.35.0; for direct structured logs use sentry_sdk.logger; for stdlib bridging use LoggingIntegration(sentry_logs_level=...)
Too many transactions Lower traces_sample_rate or use traces_sampler to drop health checks
Cross-request data leaking Don't use get_global_scope() for per-request data — use get_isolation_scope()
RQ worker not reporting Pass --sentry-dsn="" to disable RQ's own Sentry shortcut; init via settings file instead
Weekly Installs
116
Repository
getsentry/sentry-for-ai
GitHub Stars
78
First Seen
Mar 1, 2026
Security Audits
Gen Agent Trust HubPass
SocketFail
SnykPass
Installed on
gemini-cli114
amp114
cline114
github-copilot114
opencode114
cursor114