sentry-sdk

sentry-sdk is the official client library for reporting errors, performance data, and traces from Python applications to Sentry.io (or a self-hosted Sentry instance). It automatically captures unhandled exceptions, breadcrumbs, and stack traces, and enriches every event with request, user, and environment context.

Beyond crash reporting, the SDK ships distributed tracing, profiling, session-replay hooks, and cron/job monitoring, plus more than 80 framework integrations (Django, Flask, FastAPI, Celery, AWS Lambda, and others) that auto-instrument common entry points with minimal setup — typically a single sentry_sdk.init() call.

What You Get

• Automatic unhandled-exception capture with stack traces, local variables, and breadcrumbs
• Distributed tracing and performance monitoring via start_transaction/start_span, propagated across service boundaries
• 80+ framework integrations (Django, Flask, FastAPI, Celery, RQ, AWS Lambda, gRPC, and more) that auto-instrument on init()
• Built-in PII scrubbing (scrubber.py) to redact sensitive data before events leave the process
• Cron/job monitoring via the crons module for tracking scheduled task health
• Configurable sample rates, before_send/before_send_transaction hooks, and release/environment tagging

Common Use Cases

• Capturing and triaging unhandled exceptions in a production web application or API service
• Tracing slow requests across a microservice boundary to find the root cause of latency
• Monitoring the health and duration of scheduled/cron jobs and alerting on missed or failed runs
• Correlating errors with releases and deploys to catch regressions immediately after shipping

Under The Hood

Architecture The SDK is organized around client.py (event construction and transport dispatch), scope.py/hub.py (the context-propagation layer that attaches tags/user/breadcrumbs to whatever is captured next), and tracing.py/traces.py (span/transaction lifecycle for performance monitoring). The 82-module integrations/ package is the largest part of the codebase by file count — each integration hooks a specific framework’s request lifecycle (e.g. Django middleware, Flask signals, Celery task hooks) to automatically start/stop spans and capture exceptions without user code changes. Batching modules (_log_batcher.py, _span_batcher.py, _metrics_batcher.py) buffer and flush telemetry asynchronously to envelope.py/transport.py for network delivery.

Tech Stack Pure Python core with certifi and urllib3 for transport; individual integrations declare their own optional dependencies (Django, Flask, Celery, etc.) so the base install stays lightweight. Uses uv/tox/tox-uv for multi-version testing across the many supported framework versions, ruff for linting, and mypy for type checking (opt-in via a typing dependency group).

Code Quality Very large, framework-specific test suite under tests/ mirroring the integrations/ layout, run across a wide Python/framework version matrix via tox (tox.ini), which is essential given the SDK must support dozens of third-party libraries at multiple versions simultaneously. Uses codecov.yml for coverage tracking and renovate.json for automated dependency updates. The repo also documents its own AI-agent conventions (AGENTS.md, CLAUDE.md), reflecting an actively maintained, process-heavy engineering culture.

API Design The dominant pattern is single-call setup (sentry_sdk.init(dsn=..., integrations=[...])) after which instrumentation is largely implicit — errors and spans are captured automatically once an integration is active, minimizing boilerplate at call sites. Explicit APIs (capture_exception, start_transaction, set_tag) are available for manual instrumentation when auto-instrumentation isn’t enough, giving the SDK both a zero-config default path and a fully explicit one.