Python integration guide

Typical installation time: 5 minutes

Hi there! You’ve found Honeybadger’s guide to Python error tracking and performance monitoring. Once installed, Honeybadger will automatically report errors and performance insights from your application.

Installing the package

Install the honeybadger Python package with pip (or add it to your requirements.txt):

pip install honeybadger

See the framework-specific sections on this page for how to configure Honeybadger for your application.

For other frameworks (tornado, web2py, etc.) or plain Python scripts, simply import honeybadger and configure it with your API key. Honeybadger uses a global exception hook to automatically report uncaught exceptions:

from honeybadger import honeybadger

honeybadger.configure(
    api_key='PROJECT_API_KEY',
    insights_enabled=True
)

raise Exception("This will get reported!")

Tip

You can also configure Honeybadger with environment variables:

export HONEYBADGER_API_KEY="PROJECT_API_KEY"
export HONEYBADGER_INSIGHTS_ENABLED=True

If you use this method, you can omit explicit configuration in your application code. Environment variables take precedence over programmatic configuration when both are present.

See the Configuration reference for additional info.

Testing your installation

Note

Honeybadger does not report errors in development and test environments by default. To enable reporting in development environments, temporarily add force_report_data=True to your Honeybadger config.

To test that Honeybadger is working, you can create a simple test exception:

from honeybadger import honeybadger

try:
    raise Exception("Honeybadger test exception")
except Exception as e:
    honeybadger.notify(e)

If the installation is working correctly, this error should appear in your Honeybadger dashboard.

Supported frameworks

Django

See the Django integration guide.

Flask

See the Flask integration guide.

AWS Lambda

AWS Lambda environments are auto-detected by Honeybadger with no additional configuration. Here’s an example lambda function with Honeybadger:

from honeybadger import honeybadger

honeybadger.configure(
    api_key='PROJECT_API_KEY',
    insights_enabled=True
)

def lambda_handler(event, context):
    """
    A buggy lambda function that tries to perform a zero division
    """
    a = 1
    b = 0

    return (a/b)  # This will be reported

Celery

A Celery extension is available for initializing and configuring Honeybadger: honeybadger.contrib.celery.CeleryHoneybadger. The extension adds the following information to reported exceptions:

• component: The module that the task is defined at.
• action: The name of the task.
• params: The arguments and keyword arguments passed to the task.
• context: A dictionary containing the following:
  • task_id: The id of the current task.
  • retries: The number of retries that have been attempted.
  • max_retries: The maximum number of retries that will be attempted.

Example

from celery import Celery
from honeybadger.contrib import CeleryHoneybadger

app = Celery(__name__)
app.conf.update(
    HONEYBADGER_API_KEY='PROJECT_API_KEY',
    HONEYBADGER_ENVIRONMENT='production',
    HONEYBADGER_INSIGHTS_ENABLED=True
)
CeleryHoneybadger(app, report_exceptions=True)

FastAPI

FastAPI is based on Starlette, an ASGI application. You use Honeybadger’s ASGI middleware on these types of applications.

from fastapi import FastAPI
from honeybadger import contrib

app = FastAPI()
app.add_middleware(contrib.ASGIHoneybadger)

You can pass additional configuration parameters as keyword arguments:

from fastapi import FastAPI
from honeybadger import honeybadger, contrib

honeybadger.configure(
    api_key="PROJECT_API_KEY",
    insights_enabled=True
)
app = FastAPI()
app.add_middleware(contrib.ASGIHoneybadger, params_filters=["sensitive_data"])

FastAPI advanced usage

Consuming the request body in an ASGI application’s middleware is problematic and discouraged. This is the reason why request body data won’t be sent to the web UI.

FastAPI allows overriding the logic used by the Request and APIRoute classes, by using custom APIRoute classes. This gives more control over the request body, and makes it possible to send request body data along with honeybadger notifications.

A custom API Route is available at honeybadger.contrib.fastapi:

from fastapi import FastAPI, APIRouter
from honeybadger import honeybadger
from honeybadger.contrib.fastapi import HoneybadgerRoute

honeybadger.configure(
    api_key="PROJECT_API_KEY",
    insights_enabled=True
)
app = FastAPI()
app.router.route_class = HoneybadgerRoute

router = APIRouter(route_class=HoneybadgerRoute)

Starlette

You can configure Honeybadger to work with Starlette just like in any other ASGI framework.

from starlette.applications import Starlette
from honeybadger import contrib

app = Starlette()
app.add_middleware(contrib.ASGIHoneybadger)

Other ASGI applications

A generic ASGI middleware plugin is available for initializing and configuring Honeybadger: honeybadger.contrib.asgi.

The general pattern for ASGI applications is wrapping your application with the middleware:

from honeybadger import contrib

asgi_application = someASGIApplication()
asgi_application = contrib.ASGIHoneybadger(asgi_application)

You can pass configuration parameters (or additional configuration parameters) as keyword arguments at plugin’s initialization:

from honeybadger import contrib

asgi_application = someASGIApplication()
asgi_application = contrib.ASGIHoneybadger(
    asgi_application,
    api_key="PROJECT_API_KEY",
    insights_enabled=True,
    params_filters=["sensible_data"]
)

Or you may want to initialize Honeybadger before your application, and then just register the plugin/middleware:

from honeybadger import honeybadger, contrib

honeybadger.configure(
    api_key='PROJECT_API_KEY',
    insights_enabled=True
)

# You can track errors happening before your plugin initialization
some_possibly_failing_function()

asgi_application = someASGIApplication()
asgi_application = contrib.ASGIHoneybadger(asgi_application)

Sending logs from your infrastructure

Honeybadger isn’t just for errors and application data! You can use our syslog, Vector, or PaaS integrations to send additional data from your infrastructure to Honeybadger Insights, where you can query, visualize, and analyze all of your production data in one place.