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

To configure the Sentry SDK, initialize it in your settings.py file:

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

To further customize your setup, review the Options section below.

Capturing Errors

Sentry automatically captures errors and reports issues for you. You can also expect the following for your Django project:

• If you use django.contrib.auth, and you've either enabled user_info in the data_collection option or set send_default_pii=True in your call to init, user data (such as current user ID, email address, username) will be attached to error events. send_default_pii will be removed in version 3.0 of the SDK.
• Request data will be attached to all events: HTTP method, URL, headers, form data, JSON payloads. Sentry excludes raw bodies and multipart file uploads.
• Logs emitted by any logger will be recorded as breadcrumbs by the Logging integration (this integration is enabled by default).

To learn how to manually report issues, see Capturing Errors.

Instrumenting Your App

The Sentry SDK automatically monitors the following parts of your Django project:

• Middleware stack
• Signals
• Database queries
• Redis commands
• Access to Django caches

You can also manually capture performance data – see Custom Instrumentation to learn more.

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.

Add a view that raises an exception and route it in your Django application:

from django.urls import path

def trigger_error(request):
    1 / 0

urlpatterns = [path("sentry-debug/", trigger_error)]

from django.urls import path

def trigger_error(request):
    1 / 0

urlpatterns = [path("sentry-debug/", trigger_error)]

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

Options

Add DjangoIntegration explicitly to your sentry_sdk.init() call to set options for DjangoIntegration to change its behavior:

import django.db.models.signals

import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

sentry_sdk.init(
    # ...
    integrations=[
        DjangoIntegration(
            transaction_style='url',
            middleware_spans=True,
            signals_spans=True,
            signals_denylist=[
                django.db.models.signals.pre_init,
                django.db.models.signals.post_init,
            ],
            cache_spans=False,
            http_methods_to_capture=("GET",),
        ),
    ],
)

import django.db.models.signals

import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

sentry_sdk.init(
    # ...
    integrations=[
        DjangoIntegration(
            transaction_style='url',
            middleware_spans=True,
            signals_spans=True,
            signals_denylist=[
                django.db.models.signals.pre_init,
                django.db.models.signals.post_init,
            ],
            cache_spans=False,
            http_methods_to_capture=("GET",),
        ),
    ],
)

You can pass the following keyword arguments to DjangoIntegration():

Next Steps

At this point, you should have integrated Sentry into your Django 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