AWS Lambda integration guide

Add BugSnag to your AWS Lambda applications to report errors, function timeouts and handled events, with metadata from your Lambda function.

Installation

Using PyPI:

pip install bugsnag

Basic configuration

Configure BugSnag and attach the AWS Lambda handler decorator:

# Configure BugSnag
import bugsnag

bugsnag.configure(
    api_key="YOUR_API_KEY_HERE",
)

# Wrap your Lambda app with BugSnag
@bugsnag.aws_lambda_handler
def lambda_handler(event, context):
    pass

You can find your API key in Project Settings from your BugSnag dashboard.

The BugSnag AWS Lambda handler can be configured by passing options to the decorator.

flush_timeout_ms

BugSnag will wait for events and sessions to be delivered before allowing the Lambda function to exit. This option can be used to control the maximum amount of time to wait before timing out.

By default, BugSnag will timeout after 2000 milliseconds.

@bugsnag.aws_lambda_handler(flush_timeout_ms=5000)
def lambda_handler(event, context):
    pass

If a timeout does occur, BugSnag will log a warning and events & sessions may not be delivered.

lambda_timeout_notify_ms

BugSnag will send a handled event to your dashboard to notify you of timeouts in a Lambda function, just before a timeout occurs. This option can be used to control the number of milliseconds before a timeout that BugSnag should be notified.

By default, BugSnag will notify 1000 milliseconds before the Lambda timeout.

@bugsnag.aws_lambda_handler(lambda_timeout_notify_ms=2000)
def lambda_handler(event, context):
    pass

Set this value to 0 to disable the automatic notification.

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)

To record breadcrumbs for log messages, you can add the leave_breadcrumbs log filter:

from bugsnag.handlers import BugsnagHandler

logger = logging.getLogger("test.logger")
handler = BugsnagHandler()

logger.addFilter(handler.leave_breadcrumbs)

This will capture a breadcrumb for each log message at or above the configured breadcrumb_log_level, which defaults to INFO.

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.

Avoiding re-notifying exceptions

Sometimes after catching and notifying a handled exception you may want to re-raise the exception to be dealt with by your standard error handlers without sending an automatic exception to BugSnag.

This can be accomplished by calling bugsnag.notify(), adding a custom skip_bugsnag attr to your exception, and then re-raising the exception:

try:
    raise Exception('Something went wrong!')
except Exception as exception:
    bugsnag.notify(exception)
    exception.skip_bugsnag = True

    # Now this won't be sent a second time by the exception handlers
    raise exception

Sending diagnostic data

Automatically captured diagnostics

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

• AWS Lambda handler event and context arguments
• 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 your lambda handler is invoked.

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.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

By default, BugSnag captures the following events as breadcrumbs:

• Error reports

This can be controlled using the enabled_breadcrumb_types configuration option.

Leaving manual breadcrumbs

You can use the leave_breadcrumb method to log potentially useful events in your own applications:

bugsnag.leave_breadcrumb("Something happened!")

Additional data can also be attached to breadcrumbs by providing the optional type and metadata parameters. For more information and examples for how custom breadcrumbs can be integrated, see customizing breadcrumbs.

Next steps

• Catch and report errors in your client-side JavaScript with the Web browser JavaScript guide
• View bugsnag-python, the library powering this integration, on GitHub
• Get support for your questions and feature requests