ASGI integration guide

Add Bugsnag to your ASGI applications.

Installation

Using PyPI:

pip install bugsnag

Basic configuration

Configure Bugsnag and attach the ASGI middleware:

import bugsnag
from bugsnag.asgi import BugsnagMiddleware

bugsnag.configure(
  api_key = "YOUR_API_KEY_HERE",
  project_root = "/path/to/your/app",
)

# Wrap your ASGI app with Bugsnag
application = BugsnagMiddleware(application)

You can find your API key in Project Settings.

Logging configuration

You can connect Bugsnag up to Python’s logging framework so that anything of level “error” or above is logged to Bugsnag.

Here is a plain Python example:

import logging

from bugsnag.handlers import BugsnagHandler

# ... (call bugsnag.configure() here)
logger = logging.getLogger("test.logger")
handler = BugsnagHandler()
# send only ERROR-level logs and above
handler.setLevel(logging.ERROR)
logger.addHandler(handler)

Reporting unhandled errors

At this point, Bugsnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your Bugsnag dashboard.

Reporting handled errors

If you would like to send handled exceptions to Bugsnag, you should import the bugsnag module:

import bugsnag

Then to notify Bugsnag of an error, you can call bugsnag.notify:

bugsnag.notify(Exception("Something broke!"))

You can also pass additional configuration options in as named parameters. These parameters will only affect the current call to notify.

Sending diagnostic data

Automatically captured diagnostics

As well as a full stacktrace for every exception, Bugsnag will automatically capture the following diagnostic data:

  • Request information, including ip, headers, URL, HTTP method, and HTTP params
  • Session data
  • Release stage (production, beta, staging, etc)
  • Hostname

Custom diagnostics

The metadata field is a dictionary of dictionaries which will be rendered as a tab in a Bugsnag error report. This example would create a special_info tab:

bugsnag.notify(Exception("Something broke!"),
    context="myContext",
    metadata={"special_info":{"request_id": 12345, "message_id": 854}}
)

For more information, see reporting handled errors.

Session tracking

Bugsnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behavior can be disabled using the auto_capture_sessions configuration option.

Using this option, Bugsnag will report a session each time a request is made to the server.

If you want control over what is deemed a session, rather than using the auto_capture_sessions option, you can call Bugsnag.start_session when appropriate for your application.

Identifying users

The user field is information about the person currently using your application. It should be a dictionary containing id, email, and/or name.

bugsnag.notify(e, user={"id":"bob-hoskins", name: "Bob Hoskins", email: "foo@bar.com"})

For more information, see reporting handled errors. To set user information for every report, see customizing error reports.

Next steps