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 behvaiour, 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 thegetLogger()
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/]