Python

Learn how to set up Sentry in your Python app, capture your first errors and traces, and view them in Sentry.

Agent-Assisted Setup

Use curl to download, read and follow: https://skills.sentry.dev/sentry-python-sdk/SKILL.md

Your agent will set up Sentry in your Python app automatically. Works with Cursor, Claude Code, Codex, and more.View docs ↗

Install the full skills package

Run this in your project to add Sentry agent skills. See the installation docs for more details.

Copied

npx @sentry/dotagents add getsentry/sentry-for-ai --name sentry-python-sdk

Using a framework?

This guide focuses on plain Python. If you're working with Django, FastAPI, Starlette, or any other web framework, choose the respective guide from the list of supported frameworks.

You need:

A Sentry account and project
Your application up and running

Run the command for your preferred package manager to add the Sentry SDK to your application:

Copied

pip install "sentry-sdk"

pip install "sentry-sdk"

uv add "sentry-sdk"

poetry add "sentry-sdk"

Choose the features you want to configure, and this guide will show you how:

Error MonitoringTracingProfilingLogsMetrics

Want to learn more about these features?

Issues (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
Tracing: Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
Profiling: Gain deeper insight than traditional tracing without custom instrumentation, letting you discover slow-to-execute or resource-intensive functions in your app.
Logs: Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.
Application Metrics: Track and analyze custom application metrics, such as response times and database query durations, to understand trends and patterns in your application's performance and behavior over time.

Configuration should happen as early as possible in your application's lifecycle.

Import and initialize the SDK in your app's entry point:

Copied

import sentry_sdk
# ___PRODUCT_OPTION_START___ metrics
from sentry_sdk import metrics
# ___PRODUCT_OPTION_END___ metrics

sentry_sdk.init(
    dsn="___PUBLIC_DSN___",

    # Add request headers and IP for users,
    # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
    send_default_pii=True,
    # ___PRODUCT_OPTION_START___ performance

    # Set traces_sample_rate to 1.0 to capture 100%
    # of transactions for tracing.
    # see https://docs.sentry.io/platforms/python/configuration/options/#traces_sample_rate for more info
    traces_sample_rate=1.0,
    # ___PRODUCT_OPTION_END___ performance
    # ___PRODUCT_OPTION_START___ profiling

    # Enables continuous profiling.
    # To collect profiles for all profile sessions,
    # set `profile_session_sample_rate` to 1.0.
    # see https://docs.sentry.io/platforms/python/configuration/options/#profile_session_sample_rate for more info
    profile_session_sample_rate=1.0,

    # Profiles will be automatically collected while
    # there is an active span.
    # see https://docs.sentry.io/platforms/python/configuration/options/#profile_lifecycle for more info
    profile_lifecycle="trace",
    # ___PRODUCT_OPTION_END___ profiling
    # ___PRODUCT_OPTION_START___ logs

    # Enable logs to be sent to Sentry
    # see https://docs.sentry.io/platforms/python/configuration/options/#enable_logs for more info
    enable_logs=True,
    # ___PRODUCT_OPTION_END___ logs
)

import sentry_sdk
# ___PRODUCT_OPTION_START___ metrics
from sentry_sdk import metrics
# ___PRODUCT_OPTION_END___ metrics

sentry_sdk.init(
    dsn="___PUBLIC_DSN___",

    # Add request headers and IP for users,
    # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
    send_default_pii=True,
    # ___PRODUCT_OPTION_START___ performance

    # Set traces_sample_rate to 1.0 to capture 100%
    # of transactions for tracing.
    # see https://docs.sentry.io/platforms/python/configuration/options/#traces_sample_rate for more info
    traces_sample_rate=1.0,
    # ___PRODUCT_OPTION_END___ performance
    # ___PRODUCT_OPTION_START___ profiling

    # Enables continuous profiling.
    # To collect profiles for all profile sessions,
    # set `profile_session_sample_rate` to 1.0.
    # see https://docs.sentry.io/platforms/python/configuration/options/#profile_session_sample_rate for more info
    profile_session_sample_rate=1.0,

    # Profiles will be automatically collected while
    # there is an active span.
    # see https://docs.sentry.io/platforms/python/configuration/options/#profile_lifecycle for more info
    profile_lifecycle="trace",
    # ___PRODUCT_OPTION_END___ profiling
    # ___PRODUCT_OPTION_START___ logs

    # Enable logs to be sent to Sentry
    # see https://docs.sentry.io/platforms/python/configuration/options/#enable_logs for more info
    enable_logs=True,
    # ___PRODUCT_OPTION_END___ logs
)

In async programs, we recommend to initialize the Sentry SDK inside an async function to ensure async code is instrumented properly. If possible, call sentry_sdk.init() at the beginning of the first async function you call:

Copied

import asyncio
import sentry_sdk
# ___PRODUCT_OPTION_START___ metrics
from sentry_sdk import metrics
# ___PRODUCT_OPTION_END___ metrics


async def main():
    sentry_sdk.init(
        ...  # same as above
    )

asyncio.run(main())

import asyncio
import sentry_sdk
# ___PRODUCT_OPTION_START___ metrics
from sentry_sdk import metrics
# ___PRODUCT_OPTION_END___ metrics


async def main():
    sentry_sdk.init(
        ...  # same as above
    )

asyncio.run(main())

The Sentry SDK automatically enables integrations for many popular libraries, so operations like HTTP requests or database queries made with supported libraries will be captured as spans automatically.

However, spans are only created within an existing transaction. If you're not using a supported framework that creates transactions automatically, you'll need to create them manually using sentry_sdk.start_transaction().

See Custom Instrumentation for more info.

Copied

import sentry_sdk

def some_function():
    with sentry_sdk.start_transaction(op="task", name="Test Transaction"):
        ...

import sentry_sdk

def some_function():
    with sentry_sdk.start_transaction(op="task", name="Test Transaction"):
        ...

Let's test your setup and confirm that data reaches your Sentry project.

Errors triggered from a Python shell like IPython will not trigger Sentry's error monitoring. Make sure you're running the examples from a file instead.

To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application:

Copied

import sentry_sdk

division_by_zero = 1 / 0

import sentry_sdk

division_by_zero = 1 / 0

To test your tracing configuration, create a custom transaction and span:

Copied

import sentry_sdk

with sentry_sdk.start_transaction(op="task", name="Transaction Name"):
    span = sentry_sdk.start_span(name="Custom Span Name")
    span.finish()

import sentry_sdk

with sentry_sdk.start_transaction(op="task", name="Transaction Name"):
    span = sentry_sdk.start_span(name="Custom Span Name")
    span.finish()

To verify that Sentry catches your logs, add some log statements to your application:

Copied

import sentry_sdk

sentry_sdk.logger.info("This is an info log message")
sentry_sdk.logger.warning("This is a warning message")
sentry_sdk.logger.error("This is an error message")

import sentry_sdk

sentry_sdk.logger.info("This is an info log message")
sentry_sdk.logger.warning("This is a warning message")
sentry_sdk.logger.error("This is an error message")

Send test metrics from your app to verify metrics are arriving in Sentry:

Copied

from sentry_sdk import metrics

metrics.count("checkout.failed", 1)
metrics.gauge("queue.depth", 42)
metrics.distribution("cart.amount_usd", 187.5)

from sentry_sdk import metrics

metrics.count("checkout.failed", 1)
metrics.gauge("queue.depth", 42)
metrics.distribution("cart.amount_usd", 187.5)

Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?

Open the Issues page and select an error from the issues list to view the full details and context of this error. For more details, see this interactive walkthrough.
Open the Traces page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click here.
Open the Profiles page, select a transaction, and then a profile ID to view its flame graph. For more information, click here.
Open the Logs page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click here.
Open the Application Metrics page to view and analyze your metrics. For more details, see this interactive walkthrough.

At this point, you should have integrated Sentry into your Python application and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

Explore practical guides on what to monitor, log, track, and investigate after setup
Continue to customize your configuration
Learn more about manually capturing errors or messages
Dive straight into the API with our API docs

Are you having problems setting up the SDK?

Find various topics in Troubleshooting
Get support

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support