README.md

airbrake-python

Note. Python 3.4+ are advised to use new Airbrake Python notifier which supports async API and code hunks. Python 2.7 users should continue to use this notifier.

Airbrake integration for python that quickly and easily plugs into your existing code.

import airbrake

logger = airbrake.getLogger()

try:
    1/0
except Exception:
    logger.exception("Bad math.")

airbrake-python is used most effectively through its logging handler, and uses the Airbrake V3 API for error reporting.

install

To install airbrake-python, run:

$ pip install -U airbrake

setup

The easiest way to get set up is with a few environment variables:

export AIRBRAKE_API_KEY=*****
export AIRBRAKE_PROJECT_ID=12345
export AIRBRAKE_ENVIRONMENT=dev

and you're done!

Otherwise, you can instantiate your AirbrakeHandler by passing these values as arguments to the getLogger() helper:

import airbrake

logger = airbrake.getLogger(api_key=*****, project_id=12345)

try:
    1/0
except Exception:
    logger.exception("Bad math.")

By default, airbrake will catch and send uncaught exceptions. To avoid this behaviour, use the send_uncaught_exc option: logger = airbrake.getLogger(api_key=*****, project_id=12345, send_uncaught_exc=False)

setup for Airbrake On-Premise and other compatible back-ends (e.g. Errbit)

Airbrake Enterprise and self-hosted alternatives, such as Errbit, provide a compatible API.

You can configure a different endpoint than the default (https://api.airbrake.io) by either:

• Setting an environment variable:

export AIRBRAKE_HOST=https://self-hosted.errbit.example.com/

• Or passing a host argument to the getLogger() helper:

import airbrake

logger = airbrake.getLogger(api_key=*****, project_id=12345, host="https://self-hosted.errbit.example.com/")

adding the AirbrakeHandler to your existing logger

import logging

import airbrake

yourlogger = logging.getLogger(__name__)
yourlogger.addHandler(airbrake.AirbrakeHandler())

by default, the AirbrakeHandler only handles logs level ERROR (40) and above

Additional Options

More options are available to configure this library.

For example, you can set the environment to add more context to your errors. One way is by setting the AIRBRAKE_ENVIRONMENT env var.

export AIRBRAKE_ENVIRONMENT=staging

Or you can set it more explicitly when you instantiate the logger.

import airbrake

logger = airbrake.getLogger(api_key=*****, project_id=12345, environment='production')

The available options are:

• environment, defaults to env var AIRBRAKE_ENVIRONMENT
• host, defaults to env var AIRBRAKE_HOST or https://api.airbrake.io
• root_directory, defaults to None
• timeout, defaults to 5. (Number of seconds before each request times out)
• send_uncaught_exc, defaults to True (Whether or not to send uncaught exceptions)

giving your exceptions more context

import airbrake

logger = airbrake.getLogger()

def bake(**goods):
    try:
        temp = goods['temperature']
    except KeyError as exc:
        logger.error("No temperature defined!", extra=goods)

Setting severity

[Severity][what-is-severity] allows categorizing how severe an error is. By default, it's set to error. To redefine severity, simply build_notice with the needed severity value. For example:

notice = airbrake.build_notice(exception, severity="critical")
airbrake.notify(notice)

Using this library without a logger

You can create an instance of the notifier directly, and send errors inside exception blocks.

from airbrake.notifier import Airbrake

ab = Airbrake(project_id=1234, api_key='fake')

try:
    amazing_code()
except ValueError as e:
    ab.notify(e)
except:
    # capture all other errors
    ab.capture()

Running Tests Manually

Create your environment and install the test requirements

virtualenv venv
source venv/bin/activate
pip install .
python setup.py test

To run via nose (unit/integration tests):

source venv/bin/activate
pip install -r ./test-requirements.txt
source venv/bin/activate
nosetests

Run all tests, including multi-env syntax, and coverage tests.

pip install tox
tox -v --recreate

It's suggested to make sure tox will pass, as CI runs this. tox needs to pass before any PRs are merged.

---

The airbrake.io api docs used to implement airbrake-python are here: https://airbrake.io/docs/api/

[[what-is-severity]: https://airbrake.io/docs/airbrake-faq/what-is-severity/]