Python Configuration - Configuring the Instana package


The Instana Python package aims to be a fully no-touch automatic solution for Python monitoring but still be fully configurable when needed. This page outlines the options available in configuring this package.


By default, Instana provides a proprietary no touch, automatic remote performance monitoring technology that is named Instana AutoTrace™.

This means:

  1. No Python package installation required
  2. No configuration required
  3. No changes to your environment
  4. No code changes required
  5. No re-deploys of applications, workers or queues
  6. No process restarts

Zero user steps required from you or your team for full visibility into Python after the Instana Host Agent is installed.

Once the Instana host agent is installed on your host, it will periodically scan for running Gunicorn and uwsgi processes and automatically apply the Python instrumentation transparently.

This process is controlled by the Instana host agent and can be configured with a change in your configuration.yaml file. See the Agent Configuration page for full details on this file but for the specifics on Python, keep reading.

The Python Automatic instrumentation can be optionally configured by adding the following block to your Instana host agent configuration.yaml. Explanations of what each option does is provided in-line.

  # Python autodiscovery will automatically find and instrument Python processes.
  # This is supported on Linux 64bit Python processes.

    # Valid values: true, false
    enabled: true

    # the autodiscovery white list is used to identify python processes.  It is applied
    # _before_ the blacklist to get a list of potential candidate processes.  The white
    # list is used to create a list of processes that contain the following strings in
    # their command line.  Matching is case sensitive.
      - 'gunicorn'
      - 'uwsgi'

    # the autodiscovery black list is used to identify processes to ignore.  It is applied
    # _after_ the whitelist.  Any processes that have the following strings in their
    # command line will be ignored.  Matching is case sensitive.
      - 'pipenv'         # pipenv processes
      - 'runserver'      # development webservers
      - ''
      - 'ipython'
      - 'terminator'     # Linux console
      - 'mintupdate'

Notes & Limitations

Python AutoTrace is:

  • supported on Linux 64bit binaries only
  • not currently supported on Alpine (musl) based binaries

If you are adding custom code to your application (such as OpenTracing or Python based configuration) then you should use the manual install method instead.

Host Agent Communication

The sensor tries to communicate with the Instana agent via IP and as a fallback via the host’s default gateway for containerized environments. Should the agent not be available at either of these locations, you can use environment variables to configure where to look for the Instana Host Agent.

The environment variables should be set in the environment of the running process.

export INSTANA_AGENT_PORT = '42699'

See also the General Reference: Environment Variables for Language Sensors

Setting the Service Name

If you’d like to assign a single service name for the entire application you can do so by setting an environment variable or via code:

export INSTANA_SERVICE_NAME=myservice


instana.service_name = "myservice"

See also the General Reference: Environment Variables for Language Sensors

Package Configuration

The Instana package includes a runtime configuration module that manages the configuration of various components.

Note: as the package evolves, more options will be added here

from instana.configurator import config

# To enable tracing context propagation across Asyncio ensure_future and create_task calls
# Default is false
config['asyncio_task_context_propagation']['enabled'] = True

Debugging & More Verbosity

Setting INSTANA_DEBUG to a non nil value will enable extra logging output generally useful for development and troubleshooting.

export INSTANA_DEBUG="true"

See also the General Reference: Environment Variables for Language Sensors

Disabling Automatic instrumentation

This Instana package includes automatic instrumentation that is initialized on package load. This instrumentation provides distributed tracing information to your Instana dashboard. To see the full list of automatic instrumentation, see the Supported Versions document.

You can this disable automatic instrumentation (tracing) by setting the environment variable INSTANA_DISABLE_AUTO_INSTR. This will suppress the loading of instrumentation built-into the sensor.


In certain scenarios on this platform, the Python sensor may not be able to automatically locate and contact the Instana host agent. To resolve this, add the following to your Python app deployment descriptor:

    fieldPath: status.hostIP

This will set the environment variable INSTANA_AGENT_HOST with the IP of the host so the Python sensor can properly locate the Host agent.

See also the General Reference: Environment Variables for Language Sensors


Django (Manual)

When the AUTOWRAPT_BOOTSTRAP=instana environment variable is set, the Django framework should be automatically detected and instrumented. If for some reason, you prefer to or need to manually instrument Django, you can instead add instana.instrumentation.django.middleware.InstanaMiddleware to your MIDDLEWARE list in

import os
import instana

# ... <snip> ...


WSGI Stacks

The Instana sensor includes WSGI middleware that can be added to any WSGI compliant stack. This is automated for various stacks but can also be done manually for those we haven’t added support for yet.

Once the Instana Python package is installed (via pip install instana), the general usage is:

import instana
from instana.wsgi import iWSGIMiddleware

# Wrap the wsgi app in Instana middleware (iWSGIMiddleware)
wsgiapp = iWSGIMiddleware(MyWSGIApplication())

We are working to automate this for all major frameworks but in the meantime, here are some specific quick starts for those we don’t have automatic support for yet.

Bottle WSGI

# Import Instana and the Instana WSGI middleware wrapper
import instana
from instana.wsgi import iWSGIMiddleware

from bottle import Bottle, run

app = Bottle()

def hello():
    return "Hello World!"

# Wrap the application with the Instana WSGI Middleware
app = iWSGIMiddleware(app)

# Alternative method for reference
# app = iWSGIMiddleware(bottle.default_app())

run(app, host='localhost', port=8080)

CherryPy WSGI

import cherrypy

# Import Instana and the Instana WSGI middleware wrapper
import instana
from instana.wsgi import iWSGIMiddleware

# My CherryPy application
class Root(object):
    def index(self):
        return "hello world"

cherrypy.config.update({'engine.autoreload.on': False})

# Wrap the application with the Instana WSGI Middleware
wsgiapp = iWSGIMiddleware(cherrypy.tree.mount(Root()))

In this example, we use uwsgi as the webserver and booted with:

uwsgi --socket --enable-threads --protocol=http --wsgi-file --callable wsgiapp -H ~/.local/share/virtualenvs/cherrypyapp-C1BUba0z

Where ~/.local/share/virtualenvs/cherrypyapp-C1BUba0z is the path to my local virtualenv from pipenv

Falcon WSGI

The Falcon framework can also be instrumented via the WSGI wrapper as such:

import falcon

# Import Instana and the Instana WSGI middleware wrapper
import instana
from instana.wsgi import iWSGIMiddleware

app = falcon.API()

# ...

# Wrap the application with the Instana WSGI Middleware
app = iWSGIMiddleware(app)

Then booting your stack with gunicorn myfalcon:app as an example



Thumbor is an open-source image manipulation tool. For the time being, Instana will likely not automatically instrument Thumbor processes but it can be manually instrumented by performing the following steps on the container image:

  1. Add instana>=1.11.0 to the requirements.txt
  2. Add export AUTOWRAPT_BOOTSTRAP=instana to the file
  3. Rebuild and run the container.


uWSGI Webserver

tldr; Make sure enable-threads is enabled for uwsgi.


This Python instrumentation spawns a lightweight background thread to periodically collect and report process metrics. By default, the GIL and threading is disabled under uWSGI. If you wish to instrument your application running under uWSGI, make sure that you enable threads by passing --enable-threads (or enable-threads = true in ini style). More details in the uWSGI documentation.

uWSGI Example: Command-line

uwsgi --socket --protocol=http -w wsgi -p 4 --enable-threads

uWSGI Example: ini file

http = :5000
master = true
processes = 4
enable-threads = true # required

End User Monitoring (EUM)

Instana provides deep end user monitoring that links server side traces with browser events to give you a complete view from server to browser.

See the End User Monitoring page for more details.

See Also