Configure middleware

Middleware is a software component that's part of a web application, and is capable of reading and modifying inbound requests and outbound responses.

The Python agent is implemented as a middleware for all of the frameworks that Contrast supports. To use the Python agent, you must configure the middleware for the framework that your application uses:

Bottle middleware is a WSGI middleware which operates by wrapping the Bottle application instance. The following example shows a sample Bottle application wrapped by the Contrast middleware class:

from bottle import Bottle, run, redirect
from contrast.bottle import ContrastMiddleware

# This is where the example app is declared. Look for something similar in your
# application since this instance needs to be wrapped by Contrast middleware
app = Bottle(__name__)

# Add routes to your app
@app.route("/")
def index():
    redirect("/home")
    
# This line wraps the application instance with the Contrast middleware
# NOTE: Contrast should be the first middleware if others are used
app = ContrastMiddleware(app)


if __name__ == '__main__':
    run(app)

Note

If your Bottle application uses other middleware in addition to Contrast, Contrast must be the first middleware initialized in order for certain features to work.

Django middleware is configured in the settings.py file. This file isn't found in the same location for all applications, but it's generally near the top of the application source tree. Common locations include:

  • /settings.py

  • config/settings.py

  • app/settings.py

Note

When searching the source tree to find the settings.py, make sure to exclude any directories that correspond to Python virtual environments.

Some applications have multiple settings.py files, which may correspond to different configurations of the application (for example, prod or test). In these cases, add the Contrast agent middleware to any and all of the configurations where it will be used.

For Django 1.10 and later and 2.0 and later, look for the MIDDLEWARE configuration variable, which is an array. Add the Contrast agent module to the list:

MIDDLEWARE = [
  'contrast.agent.middlewares.django_middleware.DjangoMiddleware',
  # OTHER MIDDLEWARE,
]

Include the Contrast middleware as early in the list as is possible; although modifying the order may be necessary to get the application working in some circumstances.

Older versions of Django have a different architecture for middlewares. For Django 1.6 to 1.9, look for the MIDDLEWARE_CLASSES configuration variable in settings.py.

MIDDLEWARE_CLASSES = [
  'contrast.agent.middlewares.legacy_django_middleware.DjangoMiddleware',
  # OTHER MIDDLEWARE
]

See the Django documentation for more details on middleware inclusion.

The Falcon middleware is a WSGI middleware which must be configured as follows:

import falcon

# Create a Falcon app
_app = falcon.API()

# Create a Falcon view endpoint and register the route
home = Home()
_app.add_route('/home', home)

# Wrap the Falcon app in the Contrast middleware
# NOTE: this must happen after route registration
from contrast.agent.middlewares.falcon_middleware import FalconMiddleware as ContrastMiddleware
app = ContrastMiddleware(_app)

Flask middleware is a WSGI middleware which operates by wrapping the Flask application instance. The following example shows a sample Flask application wrapped by the Contrast middleware class:

import Flask

# This line imports the Contrast middleware class from the package
from contrast.agent.middlewares.flask_middleware import FlaskMiddleware as ContrastMiddleware

# This is where the example app is declared. Look for something similar in your
# application since this instance needs to be wrapped by Contrast middleware
app = Flask(__name__)

# This line wraps the application instance with the Contrast middleware
app.wsgi_app = ContrastMiddleware(app)

# Everything below this line is part of the example app. It should not be added
@app.route('/')
def index():
    return render_template('index.html')

if __name__ == '__main__':
    app.run(...)

See the Flask documentation for more details on using WSGI middleware.

Like Flask, Pylons middleware is WSGI middleware which operates by wrapping the Flask application instance:

from pylons.wsgiapp import PylonsApp
# This line imports the Contrast middleware class from the package
from contrast.agent.middlewares.wsgi_middleware import WSGIMiddleware as ContrastMiddleware

app = PylonsApp()
# This line wraps the application instance with the Contrast middleware
app = ContrastMiddleware(app)

In Pyramid, middlewares are called "tweens". See the example below for adding the Contrast middleware to a Pyramid application:

from pyramid.config import Configurator
config = Configurator()

config.add_tween('contrast.agent.middlewares.pyramid_middleware.PyramidMiddleware')

See the Pyramid documentation for additional details on tween configuration.

WSGI middleware is implemented as a class that wraps the application instance. (This is also the basis for both Flask and Pylons middleware.)

# This line imports the Contrast middleware class from the package
from contrast.agent.middlewares.wsgi_middleware import WSGIMiddleware as ContrastMiddleware

# other app code

app = get_wsgi_application()

# This line wraps the application instance with the Contrast middleware
app = ContrastMiddleware(app)

See the WSGI spec for additional details on WSGI middleware.