pyrollbar is a Python SDK for reporting exceptions, errors, and log messages to Rollbar.

Quick start

Install using pip:

pip install rollbar
import rollbar
rollbar.init('POST_SERVER_ITEM_ACCESS_TOKEN', 'production')  # access_token, environment

try:
    main_app_loop()
except IOError:
    rollbar.report_message('Got an IOError in the main loop', 'warning')
except:
    # catch-all
    rollbar.report_exc_info()
    # equivalent to rollbar.report_exc_info(sys.exc_info())

Requirements

  • Python 2.7, 3.4, 3.5, 3.6, 3.7 or 3.8
  • requests 0.12+
  • A Rollbar account

Configuration

Other

For generic Python or a non-Django/non-Pyramid framework just initialize the Rollbar library with your access token and environment.

rollbar.init('POST_SERVER_ITEM_ACCESS_TOKEN', environment='production', **other_config_params)

Other options can be passed as keyword arguments. See the reference below for all options.

Command-line usage

pyrollbar comes with a command-line tool that can be used with other UNIX utilities to create an ad-hoc monitoring solution.

e.g. Report all 5xx haproxy requests as warning

tail -f /var/log/haproxy.log | awk '{print $11,$0}' | grep '^5' | awk '{$1="";print "warning",$0}' | rollbar -t POST_SERVER_ITEM_ACCESS_TOKEN -e production -v

e.g. Test an access token

rollbar -t POST_SERVER_ITEM_ACCESS_TOKEN -e test debug testing access token

Reference

$ rollbar --help
Usage: rollbar [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -t ACCESS_TOKEN, --access_token=ACCESS_TOKEN
                        You project's access token from rollbar.com.
  -e ENVIRONMENT, --environment=ENVIRONMENT
                        The environment to report errors and messages to.
  -u ENDPOINT_URL, --url=ENDPOINT_URL
                        The Rollbar API endpoint url to send data to.
  -m HANDLER, --handler=HANDLER
                        The method in which to report errors.
  -v, --verbose         Print verbose output.

Usage

The Django, Pyramid, Flask, and Bottle integrations will automatically report uncaught exceptions to Rollbar.

Exceptions

To report a caught exception to Rollbar, use rollbar.report_exc_info():

try:
    do_something()
except:
    rollbar.report_exc_info(sys.exc_info())
    # or if you have a webob-like request object, pass that as well:
    # rollbar.report_exc_info(sys.exc_info(), request)

Logging

You can also send any other log messages you want, using rollbar.report_message():

try:
    do_something()
except IOError:
    rollbar.report_message('Got an IOError while trying to do_something()', 'warning')
    # report_message() also accepts a request object:
    #rollbar.report_message('message here', 'warning', request)

Ignoring items

To ignore an item and not send to Rollbar, add a payload handler. The payload handler will be called for each payload, and your custom logic can be applied to determine whether to send or ignore. To send, return the payload object. To ignore, return False.

Note: Payload handlers must be added after Rollbar.init(), as init() will reset the list of handlers.

Example:

import rollbar
 
rollbar.init(ACCESS_TOKEN, 'production')
 
def ignore_handler(payload, **kw): # kw is currently unused
   if payload['data']['environment'] == 'test':
       return False
   else:
       return payload
 
rollbar.events.add_payload_handler(ignore_handler)

Transforming the payload

To add, remove or modify data in the payload before sending, add a payload handler. The payload handler will be called for each payload, and any part of the payload can be modified before returning. Any changes to the payload must comply with the Rollbar API schema, or the payload will be rejected at the API.

Note: Payload handlers must be added after Rollbar.init(), as init() will reset the list of handlers.

Example:

import rollbar
 
rollbar.init(ACCESS_TOKEN, 'production')
 
def payload_handler(payload, **kw): # kw is currently unused
   payload['data']['foo'] = 'bar' # Add new key/value to the payload
   return payload
 
rollbar.events.add_payload_handler(payload_handler)

The pyrollbar SDK supplies a UUID during the occurrence creation process in report_message() and report_exc_info() method calls of the __init__.py file. This UUID can be used to track customer issues, correlate exceptions to automated test sessions, and more.

📘

UUIDs

To learn more about the UUID feature and its usage, visit this guide.

Examples

Here's a full example, integrating into a simple Gevent app.

"""
Sample Gevent application with Rollbar integration.
"""
import sys
import logging

from gevent.pywsgi import WSGIServer
import rollbar
import webob

# configure logging so that rollbar's log messages will appear
logging.basicConfig()

def application(environ, start_response):
    request = webob.Request(environ)
    status = '200 OK'
    headers = [('Content-Type', 'text/html')]
    start_response(status, headers)

    yield '<p>Hello world</p>'

    # extra fields we'd like to send along to rollbar (optional)
    extra_data = {'datacenter': 'us1', 'app' : {'version': '1.1'}}

    try:
        # will raise a NameError about 'bar' not being defined
        foo = bar
    except:
        # report full exception info
        rollbar.report_exc_info(sys.exc_info(), request, extra_data=extra_data)

        # and/or, just send a string message with a level
        rollbar.report_message("Here's a message", 'info', request, extra_data=extra_data)

        yield '<p>Caught an exception</p>'

# initialize rollbar with an access token and environment name
rollbar.init('POST_SERVER_ITEM_ACCESS_TOKEN', 'development')

# now start the wsgi server
WSGIServer(('', 8000), application).serve_forever()

Configuration reference

Option

Description

access_token

Access token from your Rollbar project

agent.log_file

If handler is agent, the path to the log file. Filename must end in .rollbar

branch

Name of the checked-out branch.

Default: master

code_version

A string describing the current code revision/version (i.e. a git sha). Max 40 characters.

Default: None

enabled

Controls whether or not Rollbar will report any data

Default: True

endpoint

URL items are posted to.

Default: https://api.rollbar.com/api/1/item/

environment

Environment name. Any string up to 255 chars is OK. For best results, use production for your production environment.

exception_level_filters

List of tuples in the form (class, level) where class is an Exception class you want to always filter to the respective level. Any subclasses of the given class will also be matched.

Valid levels: 'critical', 'error', 'warning', 'info', 'debug' and 'ignored'.

Use 'ignored' if you want an Exception (sub)class to never be reported to Rollbar.

Any exceptions not found in this configuration setting will default to 'error'.

Django settings.py example (and Django default):

from django.http import Http404

ROLLBAR = {
    ...
    'exception_level_filters': [
        (Http404, 'warning')
    ]
}

In a Pyramid ini file, define each tuple as an individual whitespace delimited line, for example:

rollbar.exception_level_filters =
    pyramid.exceptions.ConfigurationError critical
    #...

handler

The method for reporting rollbar items to api.rollbar.com

One of:

  • default -- uses default handler (thread for sync reporting and async for async reporting)
  • blocking -- runs in main thread
  • thread -- spawns a new thread
  • async -- uses default (httpx) async handler to send the payload
  • agent -- writes messages to a log file for consumption by rollbar-agent
  • httpx -- uses the HTTPX async library to send the payload
  • tornado -- uses the Tornado async library to send the payload
  • gae -- uses the Google AppEngineFetch library to send the payload
  • twisted -- uses the Twisted event-driven networking library to send the payload

Default: default

locals

Configuration for collecting local variables. A dictionary:

  • enabled
    • If True, variable values will be collected for stack traces. Default True.
  • safe_repr
    • If True, non-built-in objects will be serialized into just their class name. If False repr(obj) will be used for serialization. Default True.
  • sizes
    • Dictionary of configuration describing the max size to repr() for each type.
      • maxdict: Default 10
      • maxarray: Default 10
      • maxlist: Default 10
      • maxtuple: Default 10
      • maxset: Default 10
      • maxfrozenset: Default 10
      • maxdeque: Default 10
      • maxstring: Default 100
      • maxlong: Default 40
      • maxother: Default 100
  • safelisted_types
    • A list of type objects, (e.g. type(my_class_instance) or MyClass) that will be serialized using
      repr(). Default []
  • scrub_varargs
    • If True, variable argument values will be scrubbed. Default True.

root

Absolute path to the root of your application, not including the final /.

scrub_fields

List of sensitive field names to scrub out of request params and locals. Values will be replaced with asterisks. If overriding, make sure to list all fields you want to scrub, not just fields you want to add to the default. Param names are converted to lowercase before comparing against the scrub list.

Default: ['pw', 'passwd', 'password', 'secret', 'confirm_password', 'confirmPassword', 'password_confirmation', 'passwordConfirmation', 'access_token', 'accessToken', 'auth', 'authentication']

timeout

Timeout for any HTTP requests made to the Rollbar API (in seconds).

Default: 3

allow_logging_basic_config

When True, logging.basicConfig() will be called to set up the logging system. Set to False to skip this call. If using Flask, you'll want to set to False. If using Pyramid or Django, True should be fine.

Default: True

url_fields

List of fields treated as URLs and scrubbed.

Default ['url', 'link', 'href']

verify_https

If True, network requests will fail unless encountering a valid certificate. Default True.

shortener_keys

A list of key prefixes (as tuple) to apply our shortener transform to. Added to built-in list:

[
    ('body', 'request', 'POST'),
    ('body', 'request', 'json')
]

If locals.enabled is True, extra keys are also automatically added:

[
    ('body', 'trace', 'frames', '*', 'code'),
    ('body', 'trace', 'frames', '*', 'args', '*'),
    ('body', 'trace', 'frames', '*', 'kwargs', '*'),
    ('body', 'trace', 'frames', '*', 'locals', '*')
]

Default: []

suppress_reinit_warning

If True, suppresses the warning normally shown when rollbar.init() is called multiple times.

Default: False.

capture_ip

If equal to True, we will attempt to capture the full client IP address from a request.

If equal to the string anonymize, we will capture the client IP address, but then semi-anonymize it by masking out the least significant bits.

If equal to False, we will not capture the client IP address from a request.

Default: True

capture_email

If set to True, we will attempt to enrich person data with an email address if available.

Default: False

capture_username

If set to True, we will attempt to enrich person data with a username if available.

Default: False

Help / Support

If you run into any issues, please email us at [email protected]

For bug reports, please open an issue on GitHub.


Did this page help you?