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.

Note

Instrumentation tools that use a runner or wrapper script may conflict with the Contrast Runner. If your application has issues starting when you use the Contrast Runner with other instrumentation tools, configure your application with Contrast's middleware.

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 manage.py runserver

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

      contrast-python-run -- python manage.py runserver

    Note

    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/app.py 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/app.py 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/wsgi.py --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 manage.py runserver
In this section: