Rollbar Python SDK (pyrollbar)

To start reporting exceptions, errors, and log messages to Rollbar, follow these steps:

1. Sign up: Create an account at Rollbar.
2. Install and Configure: Follow the official Python SDK Quick Start guide to install the rollbar package and set up your configuration for your specific platform.

Pyrollbar is compatible with most Python frameworks, with official integrations available for Django, Flask, FastAPI, Celery, Pyramid, and AWS Lambda.

Pyrollbar can capture the values of local variables at each frame of a traceback to provide deeper debugging context.

This is controlled by the locals setting in your configuration. To capture locals, the frame must either be the last frame in the traceback or belong to a file within the directory specified by the root setting.

Note that variables are serialized and transformed (scrubbed/redacted) before being sent to ensure sensitive data is protected.

Pyrollbar automatically enriches error reports with context from web requests.

Request Data: When a request object is passed to report_exc_info or report_message, Pyrollbar detects the framework (e.g., Django, Flask/Werkzeug, Starlette, FastAPI, Tornado, Bottle, Sanic, Falcon) and extracts:

• URL, Method, and Headers
• GET and POST parameters
• User IP (respecting X-Forwarded-For or X-Real-Ip if configured)
• Request body (if include_request_body is enabled in settings)

Person Data: Pyrollbar attempts to identify the logged-in user by looking for:

1. A rollbar_person attribute on the request.
2. A user attribute (common in Starlette/FastAPI).
3. A user_id attribute.

If capture_username or capture_email are set to False in your configuration, these fields will be scrubbed from the payload.

To use asynchronous reporting functions (report_exc_info or report_message), you must ensure your Rollbar configuration uses an async-compatible handler.

Supported handlers for async operations include:

• async
• httpx

If you attempt to use try_report with a handler that is not in the allowed list (and is not the default handler), a RollbarAsyncError will be raised. Additionally, httpx must be installed in your environment for async reporting to function.

When search_items() returns a PagedResult, you can navigate through pages of results using .next_page() and .prev_page().

Example:

result = rollbar.search_items(title='foo')
print(f"First page: {result.data}")

# Get the next page
next_page_result = result.next_page()
print(f"Second page: {next_page_result.data}")

result = rollbar.search_items(title='foo', fields=['id'])
print(f'First page: {result.page}, data: {result.data}')
result = result.next_page()
print(f'Second page: {result.page}, data: {result.data}')

The Rollbar CLI allows you to send log messages or errors directly to your Rollbar project from the command line. You can use it by providing a command (the severity level) followed by the message text. The CLI supports both direct arguments and reading from standard input (stdin).

Severity Commands

Use one of the following commands to specify the level of the message:

• debug
• info
• warning
• error
• critical

Usage Patterns

Direct Argument Mode: Pass the command and the message as arguments:

rollbar error "Something went wrong"

Interactive/Stdin Mode: You can pipe input into the CLI or use it interactively. When reading from stdin, the first word of a line is treated as the command, and the rest is the message:

echo "info system_started" | rollbar

rollbar error "Your message here"

You can integrate Rollbar into your application's existing Python logging setup by using the RollbarHandler. This handler captures log records and reports them to Rollbar.

To use it, initialize Rollbar first, then instantiate the handler and add it to your logger (or the root logger to capture all logs).

import logging
import rollbar
from rollbar.logger import RollbarHandler

# Initialize Rollbar
rollbar.init('ACCESS_TOKEN', 'ENVIRONMENT')

# Setup your logger
logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)

# Create the RollbarHandler
# By default, it reports ERROR and above to Rollbar
rollbar_handler = RollbarHandler()
rollbar_handler.setLevel(logging.ERROR)

# Attach the handler to your logger
logger.addHandler(rollbar_handler)

# Now, logging an error will report to Rollbar
logger.error("Something went wrong!")

The handler setting determines how payloads are sent to the Rollbar API.

Available handlers:

• 'default': Uses a single-use thread (default).
• 'blocking': Makes the HTTP request immediately and blocks execution.
• 'thread': Starts a single-use thread and returns immediately.
• 'async': Uses an async HTTP request (requires Python 3.4+).
• 'agent': Writes to a log file (must end in .rollbar) to be processed by rollbar-agent.
• 'tornado': Uses Tornado's AsyncHTTPClient.
• 'gae': Uses Google App Engine's urlfetch.
• 'twisted': Uses Twisted and treq.
• 'httpx': Uses httpx for async requests (requires Python 3.7+).
• 'thread_pool': Uses a pool of worker threads (requires Python 3.2+).

Pyrollbar supports various Python versions and web frameworks.

Python Version Support

• v1.5.0 (Current): Full support for Python 3.10, 3.11, 3.12, 3.13, and 3.14.
• v0.16.3: Security fixes only for Python 2.7 and 3.4 through 3.11.

Framework Support

Official support includes maintained integrations and CI testing for:

• Django: Versions 4.2, 5.2 (Supported for Release/LTS end + 1 year).
• FastAPI: Versions 0.115, 0.118 (Supported for Release + 1 year).
• Flask: Versions 2.3, 3.1 (Supported for Release + 1 year).
• Pyramid: Versions 1.10, 2.0 (Supported for Release + 1 year).
• Celery: (Supported for Release + 1 year).

Other frameworks like AWS Lambda are supported, and additional community-supported integrations are available.