Skip to main content

Contrast Runner

As of version 5.24.0, the Python agent provides a new command-line interface (also called a runner) for instrumenting Python applications. In general, when using the runner, it is no longer required to manually configure middleware. Instead, the Contrast runner automatically applies framework-specific instrumentation to your Python application.

The runner command is called contrast-python-run and is provided as part of the contrast-agent package. In most Python environments it will be available on the command line without further changes when the contrast-agent package is installed.

Using the runner

The runner is used by adding the contrast-python-run command to the beginning of the original command that starts your application.

  • For example, with a Django application that is started with the following command:

    python runserver
    • You would run the following command to add Contrast to this application:

      contrast-python-run -- python runserver


    The double dash separator “--” is used to separate the runner command's arguments from those that belong to the original command.

  • In another example, with a Flask application that is started with the following command:

    FLASK_APP=apps/ flask run --host=localhost --port=8080
    • Using the Contrast runner would look like this (note that setting the environment variable still happens before the runner command):

      FLASK_APP=apps/ contrast-python-run -- flask run --host=localhost --port=8080
  • The contrast-python-run command also works when deploying with web servers such as uwsgi and gunicorn. For example:

    contrast-python-run -- gunicorn apps/app:app --preload -b localhost:8080
  • It also works when deploying to Apache using mod_wsgi-express. For example:

    contrast-python-run -- mod_wsgi-express start-server app/ --user=www-data --group www-data

The runner follows the normal order of precedence for Contrast configuration. It is also possible to use environment variables with the runner directly on the command line:

CONTRAST__AGENT__LOGGER__LEVEL=DEBUG contrast-python-run -- python runserver