Configuring the Python collector

Enabling AutoProfile

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

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

Establishing host agent communication

The Instana Python package tries to communicate with the Instana agent through IP 127.0.0.1 and as a fallback through the host's default gateway for containerized environments. If the agent is not available at either of these locations, you can use environment variables to configure where to look for the Instana host agent.

The environment variables must 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 makes the best effort in naming your services appropriately. If for any reason you want 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.

As the package evolves, more options are added.

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 and more verbosity

Setting INSTANA_DEBUG to a non-nil value enables more logging output that is 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 complete list of automatic instrumentation, see the Supported versions document.

You can disable automatic instrumentation (tracing) by setting the environment variable INSTANA_DISABLE_AUTO_INSTR, which suppresses the loading of instrumentation that is built into the tracer.

export INSTANA_DISABLE_AUTO_INSTR="true"

Tracing root exit span without entry span

By default, the Instana Python Tracer captures only exit spans with an active entry span. However, in certain scenarios, you need to trace exit spans that occur without an entry span.

To configure the Python Tracer to trace standalone exit spans, set the INSTANA_ALLOW_ROOT_EXIT_SPAN environment variable to 1 or true as follows:

export INSTANA_ALLOW_ROOT_EXIT_SPAN=1

This feature is useful in the following scenarios:

• Incoming messages from unsupported messaging libraries.
• Requests that are made through unsupported protocols, such as raw Transmission Control Protocol (TCP) or WebSocket.
• Scheduled jobs that are initiated internally by other applications.
• Execution of Python scripts.

Kubernetes

In certain scenarios on this platform, the Python sensor might not be able to automatically locate and contact the Instana host agent. To resolve this issue, 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 must 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

Starting from Instana Python 3.0.0, the Pyramid instrumentation is automatic.

Starting from version 1.22.0 to 2.5.3, the Instana Python package includes manual support for Pyramid. To add visibility to your Pyramid-based application, complete the following steps:

1. Make sure that the instana package is added to the requirements.txt and installed in the virtual environment or container.
2. Add import instana to the beginning 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')
    # ...

The following image displays an example of the Instana instrumentation in your Pyramid configuration:

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

WSGI and ASGI stacks

The Instana Python package includes Web Server Gateway Interface (WSGI) and Asynchronous Server Gateway Interface (ASGI) middleware that can be added to any compliant stack. Automation is available for various stacks, but manual addition is also possible for those stacks that don't have automatic support yet from Instana.

After you install the Instana Python package, use the following commands:

import instana

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

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

Instana is working to automate instrumentation for all major frameworks but in the meantime, check some specific quick starts for those stacks that don't have automatic support yet from Instana.

# 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'

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

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

uWSGI web server

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

Gunicorn web server

To instrument your application that runs under Gunicorn, make sure that you give --preload as an argument.

gunicorn -w 4 --preload "file:app"

bind = "0.0.0.0:8000"
workers = 4
preload_app = 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.

Filtering rules

The rules for filtering spans are as follows:

• When a span is ignored, all subsequent downstream spans are also ignored.
• Use the wildcard * to ignore all endpoints or methods.
• Endpoint values (such as Kafka topic names) remain consistent across services.
• Method names might vary depending on the programming language and technology. Refer to the Instana UI to determine the correct method and endpoint for your service.

The following Instana UI screenshot provides a visual reference for identifying the correct method and endpoint for configuration:

The ignore endpoints feature works with only exact method names. Ensure that you use the correct method name to be filtered. This documentation uses the send method from the Kafka-Python package.

Configuring endpoint exclusion

You can enable the endpoint exclusion by using any of the following options:

• Environment variables
• In-code configuration
• Agent configuration

If more than one approach is used at the same time, Python Tracer prioritizes in the following order: environment variable, in-code configuration, and agent configuration.

INSTANA_IGNORE_ENDPOINTS_PATH=/absolute/path/to/config.yaml

tracing:
  ignore-endpoints:
    redis:
      - get
      - type
    dynamodb:
      - query
    kafka:
      - send 

tracing:
  ignore-endpoints:
    kafka: 
      - methods: ["consume"]
        endpoints: ["topic1", "topic2"]

      - methods: ["consume", "send"]
        endpoints: ["topic3"]

      - methods: ["*"] # Applied to all methods
        endpoints: ["topic4"]

      - methods: ["consume"]
        endpoints: ["*"] # Applied to all endpoints

INSTANA_IGNORE_ENDPOINTS=redis:get,type

INSTANA_IGNORE_ENDPOINTS=redis

INSTANA_IGNORE_ENDPOINTS=redis:get,type;dynamodb:query,scan;kafka:send

config["tracing"]["ignore_endpoints"] = { "redis": ["get", "type"] }

config["tracing"]["ignore_endpoints"] = { "redis": [] }

config["tracing"]["ignore_endpoints"] = {
    "redis": ["get", "type"], 
    "dynamodb": ["query", "scan"], 
    "kafka": ["send"]
}

config["tracing"]["ignore_endpoints"] = {
    "kafka": [
        { methods: ["consume"], endpoints: ["topic1", "topic2"] },
        { methods: ["send"], endpoints: ["topic3"] }
    ]
}