# Python exception notifier for Airbrake
## Installation
pybrake requires Python 3.6+.
``` shell
pip install -U pybrake
```
## Configuration
You **must** set both `project_id` & `project_key`.
To find your `project_id` and `project_key` navigate to your project's
_Settings_ and copy the values from the right sidebar.
![project-idkey]
```python
import pybrake
notifier = pybrake.Notifier(project_id=123,
project_key='FIXME',
environment='production')
```
## Sending errors to Airbrake
```python
try:
raise ValueError('hello')
except Exception as err:
notifier.notify(err)
```
### Sending errors synchronously
By default, the `notify` function sends errors asynchronously using
`ThreadPoolExecutor` and returns a `concurrent.futures.Future`, a synchronous
API is also made available with the `notify_sync` function:
```python
notice = notifier.notify_sync(err)
if 'id' in notice:
print(notice['id'])
else:
print(notice['error'])
```
## Adding custom params
To set custom params you can build and send notice in separate steps:
```python
notice = notifier.build_notice(err)
notice['params']['myparam'] = 'myvalue'
notifier.send_notice(notice)
```
You can also add custom params to every error notice before it's sent to Airbrake
with the `add_filter` function.
```python
def my_filter(notice):
notice['params']['myparam'] = 'myvalue'
return notice
notifier.add_filter(my_filter)
```
## Ignoring notices
There may be some notices/errors thrown in your application that you're not
interested in sending to Airbrake, you can ignore these using the `add_filter`
function.
```python
def my_filter(notice):
if notice['context']['environment'] == 'development':
# Ignore notices in development environment.
return None
return notice
notifier.add_filter(my_filter)
```
## Filtering keys
With `keys_blocklist` option you can specify list of keys containing sensitive information that must be filtered out, e.g.:
```python
notifier = pybrake.Notifier(
...
keys_blocklist=[
'password', # exact match
re.compile('secret'), # regexp match
],
)
```
## Logging integration
pybrake provides a logging handler that sends your logs to Airbrake.
```python
import logging
import pybrake
airbrake_handler = pybrake.LoggingHandler(notifier=notifier,
level=logging.ERROR)
logger = logging.getLogger('test')
logger.addHandler(airbrake_handler)
logger.error('something bad happened')
```
## Disabling pybrake logs
The pybrake logger can be silenced by setting the logging level to
`logging.CRITICAL`.
``` python
import logging
logging.getLogger("pybrake").setLevel(logging.CRITICAL)
```
## Sending route stats
`notifier.routes.notify` allows sending route stats to Airbrake. The library
provides integrations with Django and Flask. (your routes are tracked
automatically). You can also use this API manually:
```py
from pybrake import RouteMetric
metric = RouteMetric(method=request.method, route=route)
metric.status_code = response.status_code
metric.content_type = response.headers.get("Content-Type")
metric.end_time = time.time()
notifier.routes.notify(metric)
```
## Sending route breakdowns
`notifier.routes.breakdowns.notify` allows sending performance breakdown stats
to Airbrake. You can use this API manually:
```py
from pybrake import RouteMetric
metric = RouteMetric(
method=request.method,
route='/things/1',
status_code=200,
content_type=response.headers.get('Content-Type'))
metric._groups = {'db': 12.34, 'view': 56.78}
metric.end_time=time.time()
notifier.routes.breakdowns.notify(metric)
```
## Sending query stats
`notifier.queries.notify` allows sending SQL query stats to Airbrake. The
library provides integration with Django (your queries are tracked
automatically). You can also use this API manually:
```py
notifier.queries.notify(
query="SELECT * FROM foos",
method=request.method,
route=route,
function="test",
file="test",
line=10,
start_time=time.time(),
end_time=time.time(),
)
```
## Sending queue stats
`notifier.queues.notify` allows sending queue (job) stats to Airbrake. The
library provides integration with Celery (your queues are tracked
automatically). You can also use this API manually:
```py
from pybrake import QueueMetric
metric = QueueMetric(queue="foo_queue")
metric._groups = {'redis': 24.0, 'sql': 0.4}
notifier.queues.notify(metric)
```
## Framework Integration
Pybrake provides a ready-to-use solution with minimal configuration for python
frameworks.
* [AIOHTTP](https://docs.airbrake.io/docs/platforms/framework/python/aiohttp)
* [BottlePy](https://docs.airbrake.io/docs/platforms/framework/python/bottle)
* [Celery](https://docs.airbrake.io/docs/platforms/framework/python/celery)
* [CherryPy](https://docs.airbrake.io/docs/platforms/framework/python/cherrypy)
* [Django](https://docs.airbrake.io/docs/platforms/framework/python/django)
* [FastAPI](https://docs.airbrake.io/docs/platforms/framework/python/fastapi)
* [Falcon](https://docs.airbrake.io/docs/platforms/framework/python/falcon)
* [Flask](https://docs.airbrake.io/docs/platforms/framework/python/flask)
* [Hug](https://docs.airbrake.io/docs/platforms/framework/python/hug)
* [Masonite](https://docs.airbrake.io/docs/platforms/framework/python/masonite)
* [Pycnic](https://docs.airbrake.io/docs/platforms/framework/python/pycnic)
* [Pyramid](https://docs.airbrake.io/docs/platforms/framework/python/pyramid)
* [Sanic](https://docs.airbrake.io/docs/platforms/framework/python/sanic)
* [Starlette](https://docs.airbrake.io//docs/platforms/framework/python/starlette)
* [Tornado](https://docs.airbrake.io//docs/platforms/framework/python/tornado)
* [Turbogears2](https://docs.airbrake.io//docs/platforms/framework/python/turbogears2)
## Development
### Running the tests
```shell
pip install -r requirements.txt
pip install -r test-requirements.txt
pytest
```
### Uploading to PyPI
```shell
python setup.py sdist upload
```
### Remote configuration
Every 10 minutes the notifier issues an HTTP GET request to fetch remote
configuration. This might be undesirable while running tests. To suppress this
HTTP call, you need to pass `remote_config=False` to the notifier.
[project-idkey]: https://s3.amazonaws.com/airbrake-github-assets/pybrake/project-id-key.png
Raw data
{
"_id": null,
"home_page": "http://github.com/airbrake/pybrake",
"name": "pybrake",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "airbrake exception error notifier",
"author": "Airbrake Technologies, Inc.",
"author_email": "support@airbrake.io",
"download_url": "https://files.pythonhosted.org/packages/e1/b6/60cc1574170587a6e26d22a461a4b1c204a6e68ebeef3fafb1b933425254/pybrake-1.10.1.tar.gz",
"platform": null,
"description": "# Python exception notifier for Airbrake\n\n\n\n## Installation\n\npybrake requires Python 3.6+.\n\n``` shell\npip install -U pybrake\n```\n\n## Configuration\n\nYou **must** set both `project_id` & `project_key`.\n\nTo find your `project_id` and `project_key` navigate to your project's\n_Settings_ and copy the values from the right sidebar.\n\n![project-idkey]\n\n```python\nimport pybrake\n\nnotifier = pybrake.Notifier(project_id=123,\n project_key='FIXME',\n environment='production')\n```\n\n## Sending errors to Airbrake\n\n```python\ntry:\n raise ValueError('hello')\nexcept Exception as err:\n notifier.notify(err)\n```\n\n### Sending errors synchronously\n\nBy default, the `notify` function sends errors asynchronously using\n`ThreadPoolExecutor` and returns a `concurrent.futures.Future`, a synchronous\nAPI is also made available with the `notify_sync` function:\n\n```python\nnotice = notifier.notify_sync(err)\nif 'id' in notice:\n print(notice['id'])\nelse:\n print(notice['error'])\n```\n\n## Adding custom params\n\nTo set custom params you can build and send notice in separate steps:\n\n```python\nnotice = notifier.build_notice(err)\nnotice['params']['myparam'] = 'myvalue'\nnotifier.send_notice(notice)\n```\n\nYou can also add custom params to every error notice before it's sent to Airbrake\nwith the `add_filter` function.\n\n```python\ndef my_filter(notice):\n notice['params']['myparam'] = 'myvalue'\n return notice\n\nnotifier.add_filter(my_filter)\n```\n\n## Ignoring notices\n\nThere may be some notices/errors thrown in your application that you're not\ninterested in sending to Airbrake, you can ignore these using the `add_filter`\nfunction.\n\n```python\ndef my_filter(notice):\n if notice['context']['environment'] == 'development':\n # Ignore notices in development environment.\n return None\n return notice\n\nnotifier.add_filter(my_filter)\n```\n\n## Filtering keys\n\nWith `keys_blocklist` option you can specify list of keys containing sensitive information that must be filtered out, e.g.:\n\n```python\nnotifier = pybrake.Notifier(\n ...\n keys_blocklist=[\n 'password', # exact match\n re.compile('secret'), # regexp match\n ],\n)\n```\n\n## Logging integration\n\npybrake provides a logging handler that sends your logs to Airbrake.\n\n```python\nimport logging\nimport pybrake\n\n\nairbrake_handler = pybrake.LoggingHandler(notifier=notifier,\n level=logging.ERROR)\n\nlogger = logging.getLogger('test')\nlogger.addHandler(airbrake_handler)\n\nlogger.error('something bad happened')\n```\n\n## Disabling pybrake logs\n\nThe pybrake logger can be silenced by setting the logging level to\n`logging.CRITICAL`.\n\n``` python\nimport logging\n\n\nlogging.getLogger(\"pybrake\").setLevel(logging.CRITICAL)\n```\n\n## Sending route stats\n\n`notifier.routes.notify` allows sending route stats to Airbrake. The library\nprovides integrations with Django and Flask. (your routes are tracked\nautomatically). You can also use this API manually:\n\n```py\nfrom pybrake import RouteMetric\n\nmetric = RouteMetric(method=request.method, route=route)\nmetric.status_code = response.status_code\nmetric.content_type = response.headers.get(\"Content-Type\")\nmetric.end_time = time.time()\n\nnotifier.routes.notify(metric)\n```\n\n## Sending route breakdowns\n\n`notifier.routes.breakdowns.notify` allows sending performance breakdown stats\nto Airbrake. You can use this API manually:\n\n```py\nfrom pybrake import RouteMetric\n\nmetric = RouteMetric(\n method=request.method,\n route='/things/1',\n status_code=200,\n content_type=response.headers.get('Content-Type'))\nmetric._groups = {'db': 12.34, 'view': 56.78}\nmetric.end_time=time.time()\n\nnotifier.routes.breakdowns.notify(metric)\n```\n\n## Sending query stats\n\n`notifier.queries.notify` allows sending SQL query stats to Airbrake. The\nlibrary provides integration with Django (your queries are tracked\nautomatically). You can also use this API manually:\n\n```py\nnotifier.queries.notify(\n query=\"SELECT * FROM foos\",\n method=request.method,\n route=route,\n function=\"test\",\n file=\"test\",\n line=10,\n start_time=time.time(),\n end_time=time.time(),\n)\n```\n\n## Sending queue stats\n\n`notifier.queues.notify` allows sending queue (job) stats to Airbrake. The\nlibrary provides integration with Celery (your queues are tracked\nautomatically). You can also use this API manually:\n\n```py\nfrom pybrake import QueueMetric\n\nmetric = QueueMetric(queue=\"foo_queue\")\nmetric._groups = {'redis': 24.0, 'sql': 0.4}\nnotifier.queues.notify(metric)\n```\n\n## Framework Integration\n\nPybrake provides a ready-to-use solution with minimal configuration for python \nframeworks.\n\n* [AIOHTTP](https://docs.airbrake.io/docs/platforms/framework/python/aiohttp)\n* [BottlePy](https://docs.airbrake.io/docs/platforms/framework/python/bottle)\n* [Celery](https://docs.airbrake.io/docs/platforms/framework/python/celery)\n* [CherryPy](https://docs.airbrake.io/docs/platforms/framework/python/cherrypy)\n* [Django](https://docs.airbrake.io/docs/platforms/framework/python/django)\n* [FastAPI](https://docs.airbrake.io/docs/platforms/framework/python/fastapi)\n* [Falcon](https://docs.airbrake.io/docs/platforms/framework/python/falcon)\n* [Flask](https://docs.airbrake.io/docs/platforms/framework/python/flask)\n* [Hug](https://docs.airbrake.io/docs/platforms/framework/python/hug)\n* [Masonite](https://docs.airbrake.io/docs/platforms/framework/python/masonite)\n* [Pycnic](https://docs.airbrake.io/docs/platforms/framework/python/pycnic)\n* [Pyramid](https://docs.airbrake.io/docs/platforms/framework/python/pyramid)\n* [Sanic](https://docs.airbrake.io/docs/platforms/framework/python/sanic)\n* [Starlette](https://docs.airbrake.io//docs/platforms/framework/python/starlette)\n* [Tornado](https://docs.airbrake.io//docs/platforms/framework/python/tornado)\n* [Turbogears2](https://docs.airbrake.io//docs/platforms/framework/python/turbogears2)\n\n## Development\n\n### Running the tests\n\n```shell\npip install -r requirements.txt\npip install -r test-requirements.txt\npytest\n```\n\n### Uploading to PyPI\n\n```shell\npython setup.py sdist upload\n```\n\n### Remote configuration\n\nEvery 10 minutes the notifier issues an HTTP GET request to fetch remote\nconfiguration. This might be undesirable while running tests. To suppress this\nHTTP call, you need to pass `remote_config=False` to the notifier.\n\n[project-idkey]: https://s3.amazonaws.com/airbrake-github-assets/pybrake/project-id-key.png\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python exception notifier for Airbrake",
"version": "1.10.1",
"split_keywords": [
"airbrake",
"exception",
"error",
"notifier"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1b660cc1574170587a6e26d22a461a4b1c204a6e68ebeef3fafb1b933425254",
"md5": "e22633c44f7c0e7fceabcc0d9f1005a4",
"sha256": "df87930919109ef3559e44d8bfddf783b094de840f3cab2718f83b97b96b0e76"
},
"downloads": -1,
"filename": "pybrake-1.10.1.tar.gz",
"has_sig": false,
"md5_digest": "e22633c44f7c0e7fceabcc0d9f1005a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 102694,
"upload_time": "2023-01-10T14:00:08",
"upload_time_iso_8601": "2023-01-10T14:00:08.738495Z",
"url": "https://files.pythonhosted.org/packages/e1/b6/60cc1574170587a6e26d22a461a4b1c204a6e68ebeef3fafb1b933425254/pybrake-1.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-10 14:00:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "airbrake",
"github_project": "pybrake",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "tdigest",
"specs": []
}
],
"lcname": "pybrake"
}
JSON
