Django integration guide

Add Bugsnag to your Django applications.


Using PyPI:

pip install bugsnag

Basic configuration

  1. Configure the library in your Django

    BUGSNAG = {
        'api_key': 'YOUR_API_KEY_HERE',
        'project_root': '/path/to/your/app',

    If not set, the project_root will default to the current working directory, and api_key will default to the BUGSNAG_API_KEY environment variable.

  2. Add the Bugsnag middleware to the top of MIDDLEWARE in


    Note: For versions of Django less than 1.10, use MIDDLEWARE_CLASSES instead of MIDDLEWARE.

Logging configuration

Bugsnag’s handler can integrate with Django’s logging configuration by adding bugsnag.handlers.BugsnagHandler to the application’s logging configuration.

For example, to send any logs that are ERROR and above to Bugsnag (in addition to the existing logging behaviour) the configuration would look like:

    'version': 1,
    'disable_existing_loggers': False,

    'root': {
        'level': 'ERROR',
        'handlers': ['bugsnag'],

    'handlers': {
        'bugsnag': {
            'level': 'INFO',
            'class': 'bugsnag.handlers.BugsnagHandler',

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 meta_data 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!"),
    meta_data={"special_info":{"request_id": 12345, "message_id": 854}}

For more information, see reporting handled errors.

Logging diagnostic data

The BugsnagHandler accepts a special keyword argument to its __init__() function: extra_fields. This is optional and may be a dictionary of extra attributes to gather from each LogRecord and insert into meta_data to be attached to Bugsnag error reports.

The keys in the extra_fields dictionary should be tab names for where you would like the data displayed in Bugsnag, and the values should be attributes to pull off each log record and enter into section. The attributes are not required to exist on the log record, and any non-existent attribute will be ignored. Example:

bs_handler = BugsnagHandler(extra_fields={"some_tab":["context_attribute"]})

This is very useful if you are assigning context-specific attributes to your LogRecord objects, as described in the python logging cookbook.

Session tracking

Bugsnag can track the number of “sessions” that happen in your application. This enables Bugsnag to provide and compare stability scores between releases to help you understand the quality of your releases. This functionality is disabled by default, but can be enabled through the configuration:


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.

By default it is automatically populated with the HttpRequest.user. To override this behaviour see customizing error reports.

Next steps