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-sdkpython -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"], )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/1export 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")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.
RuntimeError
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()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
OrderQuantityError
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")import logging logger = logging.getLogger("orders") logger.error("Payment provider unavailable")
Lower-level records become breadcrumbs on the next error instead of separate issues.
error orders Payment provider unavailable Payment provider unavailableBugsink preview: error log record
Log Entry
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")sentry_sdk.capture_message("Order queue is not responding", level="error")
error Order queue is not respondingBugsink preview: captured message
Log Entry
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")sentry_sdk.set_tag("component", "orders")
ordersBugsink preview: component tag
Tags
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})sentry_sdk.set_context("order", {"id": order_id, "quantity": quantity})
python-handled 0Bugsink preview: structured context
Contexts
ORDER
Breadcrumbs
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", )sentry_sdk.add_breadcrumb( category="order", message="Starting order processing", data={"order_id": order_id}, level="info", )
Bugsink preview: breadcrumb
order
Starting order processing
event time
Python frameworks
Framework and worker integrations capture failures in their normal request or task lifecycle and add the relevant context automatically.
