Add BugSnag to your Bottle applications.
New to BugSnag? Create an account
Looking for performance monitoring? See our performance guide
Using PyPI:
pip install bugsnag
The latest available version of bugsnag
is v4.7.1
.
Configure the library when your python app starts
import bugsnag
bugsnag.configure(
api_key = "YOUR_API_KEY_HERE",
project_root = "/path/to/your/app"
)
You can find your API key in Project Settings from your BugSnag dashboard.
Add the BugSnag middleware
import bottle
from bugsnag.wsgi.middleware import BugsnagMiddleware
app = bottle.app()
# Don't catch exceptions in bottle.
app.catchall = False
# Catch them in BugSnag instead.
myapp = BugsnagMiddleware(app)
bottle.run(app=myapp)
If you are running your app using uWSGI, run uwsgi
with the --enable-threads
option to allow events and sessions to be sent.
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
.
See grouping_hash to understand how you can control the grouping of your log messages.
At this point, BugSnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your BugSnag dashboard.
Automatic detection of unhandled exceptions in threads relies on threading.excepthook
, which is only supported in Python 3.8 and above.
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.
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
As well as a full stacktrace for every exception, BugSnag will automatically capture the following diagnostic data:
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.
The BugsnagHandler accepts a special keyword argument to its __init__()
function: extra_fields
. This is an optional dictionary of
extra attributes to gather from each LogRecord and insert into metadata
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. The values should be attributes to
extract from each log record. The attributes are not required to exist on the
log record, and any non-existent attribute will be ignored. For example:
logger = logging.getLogger("your_logger_name")
handler = BugsnagHandler(extra_fields={
"tab_name": [
"keyA",
"keyB"
]
})
logger.addHandler(handler)
logger.warning('A warning', extra={
'keyA': 'abc', # will be added to tab "tab_name"
'keyB': 'def', # will be added to tab "tab_name"
'keyC': 'ghi' # will be ignored by BugsnagHandler
})
This is very useful if you are assigning context-specific attributes to your LogRecord objects, as described in the python logging cookbook.
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 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.
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.
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.
By default, BugSnag captures the following events as breadcrumbs:
Error reports
HTTP requests
This can be controlled using the enabled_breadcrumb_types
configuration option.
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.
bugsnag-python
, the library
powering this integration, on GitHub