Instana Python Sensor

3.14.0 verified Fri May 01 auth: no python

Automatic distributed tracing and metrics collection for Python applications, designed to work with the Instana observability platform. Version 3.14.0 requires Python >=3.9. Active development with frequent releases every few weeks.

pip install instana

Common errors

error ModuleNotFoundError: No module named 'instana' ↓

cause Package not installed or imported incorrectly.

fix

Install with 'pip install instana' and 'import instana' in your code.

error instana.collector.Collector: Failed to report spans to agent at http://localhost:42699/com.instana.plugin.python.spans ↓

cause Instana agent is not running or unreachable on the default host/port.

fix

Start the Instana agent, or set INSTANA_AGENT_HOST environment variable to the correct agent endpoint.

error AttributeError: module 'instana' has no attribute 'span' ↓

cause Incorrect use of the API; the library does not expose a public 'span' attribute. Use instana.current_span() or instana.span_context.

fix

Use 'instana.current_span()' to get the active span, or read the documentation for custom spans.

Warnings

gotcha The Instana sensor auto-instruments many frameworks (Django, Flask, etc.). If you see unexpected spans or performance overhead, check the list of supported frameworks. You can disable instrumentation for specific frameworks via environment variables. ↓

fix Set INSTANA_DISABLE_<FRAMEWORK>=true to disable auto-instrumentation for that framework.

gotcha The agent host must be reachable; otherwise the sensor will buffer spans locally until timeout. Spans may be lost if agent is unreachable for too long. ↓

fix Ensure INSTANA_AGENT_HOST is set correctly and network connectivity exists. For Kubernetes, use the agent's DNS or IP.

deprecated Older Python versions (3.7, 3.8) are no longer supported as of v3.0.0+. ↓

fix Upgrade to Python >=3.9.

Imports

instana
```
import instana
```
No common mistake; the package auto-instruments supported frameworks upon import.

Quickstart

Importing the module auto-starts the sensor. Set INSTANA_AGENT_HOST environment variable to point to your Instana agent.

import instana
import os
# Agent host can be set via env var INSTANA_AGENT_HOST
os.environ.get('INSTANA_AGENT_HOST', '')
# The sensor starts automatically when imported
print('Instana sensor initialized')