Get started with a custom Python stack

Opbeat comes with a generic WSGI middleware that works with most Python WSGI frameworks. But you can also configure Opbeat as a logging handler, or log exceptions manually.

Note: please also check out our documentation for Django and Flask.

Installation

# Install Opbeat
$ pip install opbeat

Initializing the client

To initialize the client, you need

  • your organization ID
  • your app ID
  • your secret token

You can provide these variables as environment variables, or use them explicitly when initializing the client

from opbeat import Client

# Read configuration from the environment,
# using these environment variables:
#
# OPBEAT_ORGANIZATION_ID = <organization-id>
# OPBEAT_APP_ID = <app-id>
# OPBEAT_SECRET_TOKEN = <secret-token>

client = Client()

# Configure a client manually
client = Client(
    organization_id='<organization-id>',
    app_id='<app-id>',
    secret_token='<secret-token>',
)

Configuring Opbeat as a WSGI middleware

To use Opbeat as a WSGI middleware, wrap your application with the Opbeat middleware.

from opbeat import Client
from opbeat.middleware import Opbeat

application = Opbeat(
    application,
    Client(
        organization_id='<organization-id>',
        app_id='<app-id>',
        secret_token='<secret-token>',
    )
)

Note: Some frameworks will not automatically propagate uncaught exceptions to WSGI middleware. Check the documentation of your framework for more information.

Configure Opbeat as a logging handler

Opbeat comes with a logging handler, which allows you to send log messages to Opbeat through the Python logging framework.

You can configure the Opbeat logging handler like this:

import logging
from opbeat import Client
from opbeat.handlers.logging import OpbeatHandler

client = Client(
    organization_id='<organization-id>',
    app_id='<app-id>',
    secret_token='<secret-token>',
)

handler = OpbeatHandler(client)

logger = logging.getLogger()
logger.addHandler(handler)

Or alternatively, using logging.config.dictConfig:

import logging
import logging.config

logging.config.dictConfig({
    'version': 1,
    'formatters': {
        'verbose': {
            'format': '%(asctime)s %(name)s %(levelname)s %(funcName)s  %(filename)s:%(lineno)s %(message)s'
        }
    },
    'handlers': {
        'opbeat': {
            'level': 'INFO',
            'class': 'opbeat.handlers.logging.OpbeatHandler',
            # fill in your credentials here
            'organization_id': '<organization-id>',
            'app_id': '<app-id>',
            'secret_token': '<secret-token>'
        },
        'console': {
            'level': 'INFO',
            'class': 'logging.StreamHandler',
            'formatter': 'verbose'
        },
    },
    'loggers': {
        'opbeat': {
            'handlers': ['opbeat'],
            'level': 'ERROR',
            'propagate': False,
        },
        'opbeat.errors': {
            'handlers': ['console']
        },
    }
}

logger = logging.getLogger('opbeat')

You can also set the organization_id, app_id and secret_token as environment variables, using OPBEAT_ORGANIZATION_ID, OPBEAT_APP_ID and OPBEAT_SECRET_TOKEN, respectively.

Now you can log messages to Opbeat like this:

logger.warning('This is a warning!', extra={'foo': 'bar'})

Any data set in the extra parameter will appear in the “Extra” tab on Opbeat.

Manually send exceptions to Opbeat

You can also send exceptions to Opbeat manually. As usual, instantiate a client first:

from opbeat import Client
client = Client(
    organization_id='<organization-id>',
    app_id='<app-id>',
    secret_token='<secret-token>',
)

Then, capture an exception and send it to Opbeat:

try:
    do_something_dangerous()
except OhNoNotAgain:
    client.capture_exception()