Python Configuration - Configuring the Instana package

General

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.

AutoTrace

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.

com.instana.plugin.python:
  # Python autodiscovery will automatically find and instrument Python processes.
  # This is supported on Linux 64bit Python processes.
  autodiscovery:

    # 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.
    whitelist:
      - '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.
    blacklist:
      - 'pipenv'         # pipenv processes
      - 'runserver'      # development webservers
      - 'setup.py'
      - '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 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 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

or

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.

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, add the following to your Python app deployment descriptor:

- name: INSTANA_AGENT_HOST
valueFrom:
  fieldRef:
    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

Frameworks

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',
]

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.

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.

CherryPy WSGI

import cherrypy
import instana
from instana.wsgi import iWSGIMiddleware

# 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 wsgi app in Instana middleware (iWSGIMiddleware)
wsgiapp = iWSGIMiddleware(cherrypy.tree.mount(Root()))

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

uwsgi --socket 127.0.0.1:8080 --protocol=http --wsgi-file mycherry.py --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
from instana.wsgi import iWSGIMiddleware

app = falcon.API()

# ...

app = iWSGIMiddleware(app)

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

Tools

Thumbor

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 docker-entrypoint.sh file
  3. Rebuild and run the container.

Webservers

uWSGI Webserver

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

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.

Forking off Workers

If you use uWSGI in forking workers mode, you must specify --lazy-apps (or lazy-apps = true in ini style) to load the application in the worker instead of the master process.

uWSGI Example: Command-line

uwsgi --socket 0.0.0.0:5000 --protocol=http -w wsgi -p 4 --enable-threads --lazy-apps

uWSGI Example: ini file

[uwsgi]
http = :5000
master = true
processes = 4
enable-threads = true # required
lazy-apps = true # if using "processes", set lazy-apps to true

# Set the Instana sensor environment variable here
env = AUTOWRAPT_BOOTSTRAP=instana

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