Python Configuration - Configuring the Instana package

AutoProfile™

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 127.0.0.1 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_HOST = '127.0.0.1'
export INSTANA_AGENT_PORT = '42699'

See also:

• Configuring Agent Network Access for Kubernetes
• General Reference: Environment Variables for Language Sensors

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

Setting the Process Name

Use INSTANA_PROCESS_NAME to set a custom label for infrastructure entity that represents the Python process.

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

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:

• Python Host Agent Communication
• 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 settings.py:

import os
import instana

# ... <snip> ...

MIDDLEWARE = [
    'instana.instrumentation.django.middleware.InstanaMiddleware',
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

Pyramid

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 __init__.py file for your Pyramid application
3. Add the Instana instrumentation Tween to your configuration

import instana

with Configurator(settings=settings) as config:
    # ...
    config.include('instana.instrumentation.pyramid.tweens')
    # ...

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 =
    instana.instrumentation.pyramid.tweens.InstanaTweenFactory
    # 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.

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

from bottle import Bottle, run

app = Bottle()

@app.route('/hello')
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)

import cherrypy

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

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

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

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

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

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)

    from gevent import monkey
    monkey.patch_all()
    import instana # <--- after the gevent monkey patching of stdlib

export INSTANA_GEVENT_MONKEY_OPTIONS='--no-socket, --dns, --no-time, --select, --no-ssl'

{: codeblock}

{: codeblock}

If you use `Django` together with `gevent` and Instana autotracing, then ensure that you set the **`DJANGO_SETTINGS_MODULE`** environment variable before the autotracing starts. For more information about the **`DJANGO_SETTINGS_MODULE`** environment variable, see the [Django](https://docs.djangoproject.com/en/5.0/topics/settings/#designating-the-settings) documentation.

If this level of customization is still insufficient, then use the [Activating with code changes](../../ecosystem/python/index.html#activating-with-code-changes) method of package activation.

## <a href="#tools"><img src="../../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> Tools
{: #tools}

## <a href="#webservers"><img src="../../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> Webservers
{: #webservers}

### <a href="#uwsgi-webserver"><img src="../../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> uWSGI Webserver
{: #uwsgi-webserver}

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

#### <a href="#threads"><img src="../../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> Threads
{: #threads}

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](https://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html#a-note-on-python-threads).

#### <a href="#uwsgi-example-command-line"><img src="../../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> uWSGI Example: Command-line
{: #uwsgi-example-command-line}

```shell
uwsgi --socket 0.0.0.0:5000 --protocol=http -w wsgi -p 4 --enable-threads

[uwsgi]
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

• Python Overview
• Python Configuration
• Python Tracing SDK
• Python OpenTracing
• OpenTracing Best Practices
• Python Troubleshooting
• Python Supported Components & Versions
• Python Github Repository