Connect Python to Bugsink

When a Python application fails, Bugsink gives you the exception, stack trace, and context you need to investigate it.

This guide covers the initial setup, other ways to capture errors, and the useful context you can attach to them. You’ll start by setting up the connection and triggering a deliberate error to confirm that it reaches Bugsink.

To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Install the SDK

Install the open-source Sentry SDK (sentry-sdk) in the environment your application already uses. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project.

python -m pip install --upgrade sentry-sdk

Configure your DSN

Initialize the SDK early in your application’s startup. This example reads the DSN from the environment so it does not have to live in source control:

import os

import sentry_sdk


sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
)

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the application:

export SENTRY_DSN=https://key@bugsink.example/1

Send a test error

Temporarily add an exception to a code path you can run:

raise RuntimeError("Bugsink setup check")

Run that code path once. The exception should still behave normally in your application; the SDK reports it to Bugsink before the process exits.

See the error in Bugsink

Open your Bugsink project. The new RuntimeError issue contains the Python stack trace and points at the line that raised the exception.

Bugsink preview

That’s it: your application is connected. Remove the deliberate exception. Bugsink will capture future unhandled exceptions without any reporting calls in your application code.

Capture other kinds of errors

Unhandled exceptions arrive automatically. You can also report exceptions your code catches, error-level log records, and exceptional conditions that do not have an exception.

Handled exceptions

Capturing a handled exception sends it to Bugsink without changing how your code recovers. Call capture_exception() inside an except block when you still want its stack trace and surrounding context. Handled Errors explains when this is useful in more depth.

try:
    process_order(order_id, 0)
except OrderQuantityError:
    sentry_sdk.capture_exception()

The exception remains handled by your application and appears as an issue in Bugsink.

Bugsink preview: handled exception
Bugsink preview

Log records

Log records at ERROR or higher become Bugsink events automatically. This is useful when your code logs a failure—such as an unavailable payment provider— instead of raising an exception. getLogger("orders") names the logger shown in Bugsink; error() supplies the message and level:

import logging

logger = logging.getLogger("orders")
logger.error("Payment provider unavailable")

Lower-level records become breadcrumbs on the next error instead of separate issues.

Bugsink preview: error log record
Bugsink preview

Messages without exceptions

A message creates a Bugsink event without an exception. Use capture_message() for a condition such as an unresponsive queue or failed defensive check, and pass the text and severity you want Bugsink to show. There is no exception stack, so prefer an exception or normal logging when either fits:

sentry_sdk.capture_message("Order queue is not responding", level="error")

Bugsink preview: captured message
Bugsink preview

Add useful context

An exception tells you what failed; context helps explain why. Context added to the current scope is attached to subsequent events.

Tags

Tags make events searchable by short key/value pairs. Bugsink already adds tags such as environment and release; use set_tag() for your own component, region, plan, or feature flag. This call adds component:orders to later events in the current scope, so you can find order failures:

sentry_sdk.set_tag("component", "orders")

Bugsink preview: component tag
Bugsink preview

Structured context

Structured context adds a named group of details to an event. Use it for values you want to inspect but not search, such as the order or job being processed. set_context("order", ...) creates an Order section on later events containing the identifier and quantity:

sentry_sdk.set_context("order", {"id": order_id, "quantity": quantity})

Bugsink preview: structured context
Bugsink preview

Breadcrumbs record what happened before an error. The SDK adds some automatically; call add_breadcrumb() for steps it cannot know about, such as starting checkout or retrying an external call. This records a category, message, level, and data without creating an event; the next error includes it:

sentry_sdk.add_breadcrumb(
    category="order",
    message="Starting order processing",
    data={"order_id": order_id},
    level="info",
)

Bugsink preview: breadcrumb
Bugsink preview

Python frameworks

Framework and worker integrations capture failures in their normal request or task lifecycle and add the relevant context automatically.

FastAPI Capture unhandled FastAPI endpoint exceptions with their ASGI request and application frame. Flask Capture unhandled Flask view exceptions with their HTTP request and application frame. Django Capture unhandled Django view exceptions with request and application context. Celery Capture failed Celery tasks with their task name, worker-side Python stack, and task ID. Tornado Capture unhandled Tornado request-handler exceptions with their HTTP request and application frame. Sanic Capture unhandled Sanic request-handler exceptions with their HTTP request and application frame. aiohttp Capture unhandled aiohttp handler exceptions with their HTTP request and application frame. Starlette Capture unhandled Starlette endpoint exceptions with their ASGI request and application frame. RQ Capture failed RQ jobs with their function, worker-side Python stack, and generated job ID. Falcon Capture unhandled Falcon resource exceptions with their HTTP request and application frame. Bottle Capture unhandled Bottle route exceptions with their HTTP request and application frame. Litestar Capture unhandled Litestar handler exceptions with their HTTP request and application frame. Graphene Capture resolver failures with their named GraphQL operation, HTTP request, and application frame while preserving the normal GraphQL response. Strawberry GraphQL Capture resolver failures with their original exception, named GraphQL operation, HTTP request, and application frame. Pyramid Capture unhandled Pyramid view exceptions with their HTTP request and application frame. Quart Capture unhandled Quart view exceptions with their HTTP request and application frame. Starlite Capture unhandled legacy Starlite handler exceptions with their HTTP request and application frame.