Skip to main content

Python web servers

The Python agent is tested against several common production web servers. Some servers require certain configuration options in order to work properly with Contrast.


You can integrate Gunicorn with popular frameworks like Django, Pyramid, Tornado, or others.

Use the following command to start Gunicorn: gunicorn app.wsgi_app:application (where app is the folder of your application).

The following configurations are available within your Gunicorn server:

  • Bind:

    -b ADDRESS1

    gunicorn -b

  • Timeout:

    -t INT or --timeout INT

    Workers silent for more than this many seconds are killed and restarted.

    Value is a positive number or 0. Setting it to 0 has the effect of infinite timeouts by disabling timeouts for all workers entirely.

    The default is 30 seconds. Only set this noticeably higher if you’re sure of the repercussions for sync workers. For the non sync workers, it means that the worker process is still communicating and is not tied to the length of time required to handle a single request.


Uvicorn is an asynchronous web server that can be installed with: pip install uvicorn[standard].

The following are some suggested configurations:

  • --loop=uvloop

  • --http=httptools

    Both uvloop and httptools are written in Cython, and offer greater performance but are not compatible with Windows or PyPy.

  • --interface

    You may set this to some of the ASGI protocols. If you are using WSGI, and using —ws=websockets, websockets will not be used and defaults to auto.

  • --ws

    If you have set --ws-max-size--ws-ping-interval, --ws-ping-timeout, and —ws is not set with websockets, everything will be ignored. 

  • To use gunicorn as a manager to uvicorn you can do that by the following:

    gunicorn -k uvicorn.workers.UvicornWorker

  • The UvicornWorker implementation uses the uvloop and httptools implementations. To run under PyPy, you will need to use pure-python implementation instead. You can do this by using the UvicornH11Worker class.gunicorn -k uvicorn.workers.UvicornH11Worker.

uWSGI configuration

Contrast requires the following configuration options when running on uWSGI. You can set these on the command line or in your uWSGI configuration (.ini) file:

  • --enable-threads: Contrast's machinery utilizes threads. This option must be enabled so the agent can start background threads.

  • --single-interpreter: The Python agent applies its instrumentation to the Python process in which it is initialized. This option ensures that Contrast is initialized in the same process that handles requests for your application.

  • If using --master you must also use --lazy-apps: When running in master mode, uWSGI initializes the application in a master process but forks this process into workers which handle requests. To operate correctly, Contrast must be initialized independently in each worker process; --lazy-apps achieves this.