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 called 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 and you get full Python visibility.

Note: Yes this also includes metrics and traces for all supported Python components.

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

This process is controlled by the Instana host agent and can be customized with changes to 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 with following block in your Instana host agent configuration.yaml. Explanations of what each option does is provided in-line.

  # Python AutoTrace will automatically find and instrument Python processes.
  # This is supported on Linux 64bit Python processes.
    # Valid values: true, false
    enabled: true

    # The AutoTrace includes are used to identify python processes.  They are applied
    # _before_ the excludes to get a list of potential candidate processes.  The
    # includes are used to create a list of processes that contain the following strings
    # in their command line.  Items specified here will _override_ the defaults.
    # Matching is case sensitive.
      - 'gunicorn'
      - 'uwsgi'
      - 'python'

    # The AutoTrace excludes used to identify processes to ignore.  It is applied
    # _after_ the includes.  Any processes that have the following strings in their
    # command line will be ignored.  Items specified here will be added to the built
    # in defaults.  
    # Matching is case sensitive.
      - 'pipenv'         # pipenv processes
      - ''       # Package development

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) then you should use one of the manual install methods instead.


AutoProfile generates and reports process profiles to Instana automatically and continuously. Learn more about profiles in Analyze Profiles section.

To enable AutoProfile set the environment variable INSTANA_AUTOPROFILE=true. AutoProfile is currently supported for manual installation only. Please make sure the Instana sensor is initialized in the main thread.

Host Agent Communication

The Instana Python package 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:

Setting the Service Name

By default, the Instana will make a best effort in naming your services appropriately. If for any reason you wish to customize how services are named, you can do so by setting an environment variable:

export 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.

Kubernetes & OpenShift

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, see the Configuring Agent Network Access for Kubernetes section in the documentation.

See also:


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> ...



Since: Instana Python Package 1.22.0

The Instana package includes manual support for Pyramid. To add visibility to your Pyramid based application:

  1. Assure that the instana package is added to the requirements.txt and installed in the virtual environment or container
  2. Add import instana to the top of your file for your Pyramid application
  3. Add the Instana instrumentation Tween to your configuration
import instana

with Configurator(settings=settings) as config:
    # ...
    # ...

For example:


In case you have the pyramid.tweens option set in your production.ini config, make sure that instana.instrumentation.pyramid.tweens.InstanaTweenFactory is the first entry in this list:

pyramid.tweens =
    # other tweens

In a future version of the Instana package, these manual steps will not be required and will happen automatically when Pyramid is detected.

WSGI & ASGI Stacks

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

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

import instana

from instana.middleware import InstanaWSGIMiddleware
# or
from instana.middleware import InstanaASGIMiddleware

# Wrap the wsgi app in Instana middleware (InstanaWSGIMiddleware)
wsgiapp = InstanaWSGIMiddleware(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.

Note: The previous import form of from instana.wsgi import iWSGIMiddleware still works but has been deprecated. Support for that import form will be removed in a future version.

Bottle WSGI

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

from bottle import Bottle, run

app = Bottle()

def hello():
    return "Hello World!"

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

# Alternative method for reference
# app = InstanaWSGIMiddleware(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.middleware import InstanaWSGIMiddleware

# 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 = InstanaWSGIMiddleware(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.middleware import InstanaWSGIMiddleware

app = falcon.API()

# ...

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

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

gevent Based Applications

Instana supports applications based on gevent versions 1.4 and greater.

For the default zero-touch AutoTrace Python monitoring, no user steps are needed.

If you are manually importing the Instana Python package, make sure that the gevent import and monkey patching happen first.

    from gevent import monkey
    import instana # <--- after the gevent monkey patching of stdlib

Note: gevent based applications should not use the Activating Without Code Changes method of package activation (using the AUTOWRAPT_BOOTSTRAP environment variable). Unfortunately, this method will not work due to gevent's first order monkey patching requirements as described above. In this case, please use either AutoTrace or the Activating With Code Changes method.



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