Sentry for Python

Install

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

pip install "sentry-sdk"

pip install "sentry-sdk"

uv add "sentry-sdk"

poetry add "sentry-sdk"

This guide requires sentry-sdk version 2.70.0 or later. If you already have the SDK installed, upgrade it with pip install --upgrade sentry-sdk.

Configure

Error Monitoring starts working as soon as you call sentry_sdk.init(). Logs and Application Metrics need no extra configuration when using sentry_sdk.logger and sentry_sdk.metrics, and you'll learn how to send them in steps #3 and #4. This guide also enables Tracing and Profiling.

Initialize the Sentry SDK

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

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

The snippet also turns on:

• Collection of user data, such as the user's IP address: via data_collection
• Tracing: via traces_sample_rate
• Profiling: via profile_session_sample_rate and profile_lifecycle

Don't need a feature? Remove its options from the snippet.

import sentry_sdk
sentry_sdk.init(
    dsn="___PUBLIC_DSN___",

    # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected
    data_collection={
        "user_info": True,
    },

    # Enables Tracing.
    # Set to 1.0 to capture 100% of spans for tracing.
    # We recommend reducing this value in production.
    traces_sample_rate=1.0,

    # Enables Profiling.
    # Set to 1.0 to profile 100% of sessions.
    profile_session_sample_rate=1.0,
    # Profiles are collected while a transaction is active.
    profile_lifecycle="trace",
)

import sentry_sdk
sentry_sdk.init(
    dsn="___PUBLIC_DSN___",

    # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected
    data_collection={
        "user_info": True,
    },

    # Enables Tracing.
    # Set to 1.0 to capture 100% of spans for tracing.
    # We recommend reducing this value in production.
    traces_sample_rate=1.0,

    # Enables Profiling.
    # Set to 1.0 to profile 100% of sessions.
    profile_session_sample_rate=1.0,
    # Profiles are collected while a transaction is active.
    profile_lifecycle="trace",
)

In async programs, add the AsyncioIntegration to instrument your async code. This integration isn't enabled by default. Call sentry_sdk.init() at the beginning of the first async function you call:

import asyncio
import sentry_sdk
from sentry_sdk.integrations.asyncio import AsyncioIntegration

async def main():
    sentry_sdk.init(
        ...,  # same options as above
        integrations=[AsyncioIntegration()],
    )

asyncio.run(main())

import asyncio
import sentry_sdk
from sentry_sdk.integrations.asyncio import AsyncioIntegration

async def main():
    sentry_sdk.init(
        ...,  # same options as above
        integrations=[AsyncioIntegration()],
    )

asyncio.run(main())

Instrumenting Your App

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.

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"):
        ...

Send Logs

Use sentry_sdk.logger to send structured logs at different levels. You can include searchable attributes with each message.

To capture records from Python's standard-library logging module or Loguru, configure capture_sentry_logs=True on the corresponding integration. See the standard logging and Loguru integration guides.

See Set Up Logs for all available logging methods and formatting options.

import sentry_sdk

sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123")
sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"})

import sentry_sdk

sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123")
sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"})

Send Application Metrics NEW

Use sentry_sdk.metrics to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK.

See Set Up Metrics for all available metric types and configuration options.

import sentry_sdk

sentry_sdk.metrics.count("checkout.failed", 1)
sentry_sdk.metrics.gauge("active_connections", 42)
sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond")

import sentry_sdk

sentry_sdk.metrics.count("checkout.failed", 1)
sentry_sdk.metrics.gauge("active_connections", 42)
sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond")

Verify Your Setup

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

Run this code after sentry_sdk.init() to send a test error, along with a trace, a log, and a metric:

import sentry_sdk

with sentry_sdk.start_transaction(op="test", name="Verify Sentry setup"):
    sentry_sdk.logger.info("Sentry verification log")
    sentry_sdk.metrics.count("sentry.verification", 1)
    1 / 0

import sentry_sdk

with sentry_sdk.start_transaction(op="test", name="Verify Sentry setup"):
    sentry_sdk.logger.info("Sentry verification log")
    sentry_sdk.metrics.count("sentry.verification", 1)
    1 / 0

View Captured Data in Sentry

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).

Next Steps

At this point, you should have integrated Sentry into your Python application. Here's what to explore next:

• Explore practical guides on what to monitor, log, track, and investigate after setup
• Set up Agent Tracing to monitor your AI systems
• Learn how to manually capture errors