Python Configuration - Configuring the Instana package

Deprecated: Legacy Auto Installation of Python AutoTrace via Host Agent

The preferred approach to monitor Python applications is the AutoTrace WebHook. However, this approach only works on Kubernetes/OpenShift. Customers who are not on Kubernetes, and have not completed the manual instrumentation yet, can temporarily do the following:

After the Instana Host Agent is installed in your host machine, it can periodically scan for running Python processes and automatically apply the Instana Python instrumentation retroactively.

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 automatic installation of the Python AutoTracing feature through the host agent mechanism is deprecated and scheduled for complete removal in April 2024. Do not enable this feature. The Python Automatic instrumentation is configured by using the following block in the configuration.yaml file of the Instana host agent. To see what each option does, see the in-line explanations:

com.instana.plugin.python:
  # Python AutoTrace will automatically find and instrument Python processes.
  # This is supported on Linux 64bit Python processes.
  autotrace:
    # 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.
    includes:
      - '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.
    excludes:
      - 'pipenv'         # pipenv processes
      - 'setup.py'       # Package development

    cat /proc/sys/kernel/yama/ptrace_scope

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

uWSGI Webserver

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

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