Configuring the Python package

The instana.configurator.config object provides a Python-native alternative to environment variables for the following options. Import it with from instana.configurator import config.

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.

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

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

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

Enable tracing context propagation across asyncio.ensure_future and asyncio.create_task calls. Disabled by default.

from instana.configurator import config

config['asyncio_task_context_propagation']['enabled'] = True
 

Alternatively, set the equivalent environment variable:

export INSTANA_ASYNCIO_TASK_CONTEXT_PROPAGATION="true"
 

Setting INSTANA_DEBUG to a non-zero value enables additional logging output that is generally useful for development and troubleshooting.

export INSTANA_DEBUG="true"
 

See also the General Reference: Environment Variables for Language Sensors

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"
 

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.

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

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

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
 

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.

Make sure enable-threads is enabled for uwsgi.

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

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.

You can configure span filtering by using any of the following methods. When multiple methods are used, the filtering is applied in the following order of precedence (highest to lowest):

1. YAML configuration (INSTANA_CONFIG_PATH)
2. INSTANA_TRACING_FILTER_* environment variables
3. In-code configuration (config["tracing"]["filter"])
4. Agent configuration (configuration.yaml)

INSTANA_CONFIG_PATH=/path/to/your/configuration.yaml
 

# Exclude all HTTP spans
INSTANA_TRACING_FILTER_EXCLUDE_HTTP_ATTRIBUTES="type;http"

# Include only health check endpoints
INSTANA_TRACING_FILTER_INCLUDE_HEALTH_ATTRIBUTES="http.url;/health"

# Exclude all messaging spans
INSTANA_TRACING_FILTER_EXCLUDE_CATEGORY_ATTRIBUTES="category;messaging"

# Include only specific Kafka topic and operations
INSTANA_TRACING_FILTER_INCLUDE_KAFKA_ATTRIBUTES="kafka.topic;topic1;strict|kafka.access;consume,send"

# Exclude all exit spans
INSTANA_TRACING_FILTER_EXCLUDE_KIND_ATTRIBUTES="kind;exit"

from instana.configurator import config

config["tracing"]["filter"] = {
    "exclude": [
        {
            "name": "Exclude all health check endpoints",
            "attributes": [
                {"key": "http.url", "values": ["/health"], "match_type": "contains"}
            ],
        }
    ],
    "include": [
        {
            "name": "Include specific internal health endpoint",
            "attributes": [
                {"key": "http.url", "values": ["/internal/health"], "match_type": "strict"}
            ],
        }
    ],
}

tracing:
  filter:
    deactivate: <boolean>
    <policy>: # exclude | include
      - name: <string>
        suppression: <boolean>
        attributes:
          - key: <string> # category | kind | type | span attribute (e.g., kafka.access, http.host)
            values: <list of strings>
            match_type: <string> # strict | startswith | endswith | contains

tracing:
  filter:
    exclude:
      - name: Exclude all health check endpoints
        attributes:
          - key: http.url
            values: [/health]
            match_type: contains
      - name: Exclude all messaging spans
        attributes:
          - key: category
            values: [messaging]
            match_type: strict
    include:
      - name: Include specific internal health endpoint
        attributes:
          - key: http.url
            values: [/internal/health]
            match_type: strict

Categories are sets of libraries grouped by a common type of technology or protocol. Currently, you can disable spans for only for the logging category.

You can disable spans by using one of the following options. When multiple methods are used, the configuration is applied in the following order of precedence (highest to lowest):

1. INSTANA_CONFIG_PATH (YAML file)
2. INSTANA_TRACING_DISABLE environment variable
3. In-code configuration (config["tracing"]["disable"])
4. Agent configuration (configuration.yaml)