Skip to content

AdamSelene/pyrollbar

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Rollbar notifier for Python Build Status

Python notifier 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.3, 3.4, or 3.5
  • requests 0.12+
  • A Rollbar account

Configuration

Django

In your settings.py, add 'rollbar.contrib.django.middleware.RollbarNotifierMiddleware' as the last item in

  • MIDDLEWARE_CLASSES in Django 1.9 and earlier:

    MIDDLEWARE_CLASSES = [
        # ... other middleware classes ...
        'rollbar.contrib.django.middleware.RollbarNotifierMiddleware',
    ]
  • MIDDLEWARE in Django 1.10 and up:

    MIDDLEWARE = [
        # ... other middleware classes ...
        'rollbar.contrib.django.middleware.RollbarNotifierMiddleware',
    ]

Add these configuration variables in settings.py:

ROLLBAR = {
    'access_token': 'POST_SERVER_ITEM_ACCESS_TOKEN',
    'environment': 'development' if DEBUG else 'production',
    'branch': 'master',
    'root': '/absolute/path/to/code/root',
}

Be sure to replace POST_SERVER_ITEM_ACCESS_TOKEN with your project's post_server_item access token, which you can find in the Rollbar.com interface.

Check out the Django example.

Pyramid

In your ini file (e.g. production.ini), add rollbar.contrib.pyramid to the end of your pyramid.includes:

[app:main]
pyramid.includes =
    pyramid_debugtoolbar
    rollbar.contrib.pyramid

And add these rollbar configuration variables:

[app:main]
rollbar.access_token = POST_SERVER_ITEM_ACCESS_TOKEN
rollbar.environment = production
rollbar.branch = master
rollbar.root = %(here)s

Be sure to replace POST_SERVER_ITEM_ACCESS_TOKEN with your project's post_server_item access token, which you can find in the Rollbar.com interface.

The above will configure Rollbar to catch and report all exceptions that occur inside your Pyramid app. However, in order to catch exceptions in middlewares or in Pyramid itself, you will also need to wrap your app inside a pipeline with Rollbar as a filter.

To do this, first change your ini file to use a pipeline. Change this:

[app:main]
#...

To:

[pipeline:main]
pipeline =
    rollbar
    YOUR_APP_NAME

[app:YOUR_APP_NAME]
pyramid.includes =
    pyramid_debugtoolbar
    rollbar.contrib.pyramid

rollbar.access_token = POST_SERVER_ITEM_ACCESS_TOKEN
rollbar.environment = production
rollbar.branch = master
rollbar.root = %(here)s

[filter:rollbar]
use = egg:rollbar#pyramid
access_token = POST_SERVER_ITEM_ACCESS_TOKEN
environment = production
branch = master
root = %(here)s

Note that the access_token, environment, and other Rollbar config params do need to be present in both the app section and the filter section.

Additionally, note that because Pyramid uses INI files for configuration, any changes to nested settings, like the locals dictionary, will need to be handled in code.

Flask

Check out rollbar-flask-example.

Be sure to add the required blinker dependency! See requirements.txt in the example repo for how.

Bottle

Import the plugin and install! Can be installed globally or on a per route basis.

import bottle
from rollbar.contrib.bottle import RollbarBottleReporter

rbr = RollbarBottleReporter(access_token='POST_SERVER_ITEM_ACCESS_TOKEN', environment='production') #setup rollbar

bottle.install(rbr) #install globally

@bottle.get('/')
def raise_error():
  '''
  When navigating to /, we'll get a regular 500 page from bottle,
  as well as have the error below listed on Rollbar.
  '''
  raise Exception('Hello, Rollbar!')

if __name__ == '__main__':
    bottle.run(host='localhost', port=8080)

Be sure to replace POST_SERVER_ITEM_ACCESS_TOKEN with your project's post_server_item access token, which you can find in the Rollbar.com interface.

Twisted

Check out the Twisted example.

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)

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

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:

  • blocking -- runs in main thread
  • thread -- spawns a new thread
  • agent -- writes messages to a log file for consumption by rollbar-agent
  • 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: thread

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
whitelisted_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: []

Help / Support

If you run into any issues, please email us at support@rollbar.com

You can also find us in IRC: #rollbar on chat.freenode.net

For bug reports, please open an issue on GitHub.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature).
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Tests are in rollbar/test. To run the tests: python setup.py test

About

Error tracking and logging from Python to Rollbar

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 100.0%