genai-instana

The genai-instana package automatically instruments Python GenAI applications for Instana. It captures end-to-end traces for every LLM call — model identifiers, token usage, cost, latency and errors — without requiring instrumentation code.

Prefix your launch command and the wrapper instruments the LLM SDKs and frameworks your application already uses. It can set up telemetry for an application that has none, or attach alongside one that already uses Traceloop/OpenLLMetry or OpenTelemetry directly, leaving that application's own tracing, service identity and exporter intact.

Built and maintained by the Instana GenAI Observability team at IBM.

Early alpha, published for evaluation. Span names, attribute keys and metric names can change between releases. Pin an exact version if you build dashboards or alerts on them.

Installation

Install your application's own dependencies as usual, then add the wrapper to that same environment:

pip install genai-instana

The wrapper re-executes your command with the same interpreter, so it sees exactly the packages that environment has and never changes them.

Install it into the environment itself. Python does not activate a copy in a pip install --target directory or on PYTHONPATH, nor any copy when it runs with -S or -I. The wrapper checks for this before launching your command. If it cannot activate, it prints ACTIVATION FAILED with the likely cause and the fix, and your application runs without telemetry.

Quick start

Prefix your existing launch command. No code changes, no decorators, no Traceloop.init().

# Standalone script
genai-instana python my_script.py

# FastAPI service
genai-instana uvicorn app:app --port 8000

# Flask service — the wrapper detects Flask and serves the app
genai-instana python app.py

One HTTP request containing one model call arrives in Instana as:

POST /invoke                 SERVER  (HTTP entry)
└── openai.chat              CLIENT  (model call, named for the provider)

Configuration

Set the service name. Without this variable, every wrapped application on the host reports telemetry under the default service name auto_genai_service.

export OTEL_SERVICE_NAME=my-genai-service

Then point the wrapper at Instana. Choose one of the following options — the wrapper reads whichever set of variables is present.

Option A — Traceloop aliases

export TRACELOOP_BASE_URL=https://<otlp-host>:443
export TRACELOOP_HEADERS="x-instana-key=<agent-key>"

Option B — Standard OpenTelemetry variables

# Local Instana agent
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Instana SaaS or agentless OTLP
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<otlp-host>:443
export OTEL_EXPORTER_OTLP_HEADERS="x-instana-key=<agent-key>"

The wrapper exports over OTLP/HTTP: use port 4318 for a local agent and 443 for a SaaS endpoint. The x-instana-host header is set from the host name automatically; override it with OTEL_HOST_NAME. A local agent needs no agent key. A remote endpoint without one warns at startup, because the export would genuinely fail.

For each signal whose pipeline the wrapper sets up itself, it also sets OTEL_TRACES_EXPORTER or OTEL_METRICS_EXPORTER to none when that variable is unset. Frameworks that add exporters from the environment, such as FastAPI 0.142 and later, then leave that pipeline alone instead of exporting everything a second time. A value you set is kept, and a provider your application owns keeps its own configuration.

Coverage

Known limitations

Streaming responses are not supported. Gunicorn, distributed tracing across services and coexistence with the Instana Python sensor are not yet validated. A few gaps remain when an application sets up its own instrumentation. Read the current list in the documentation before relying on this anywhere that matters.

Documentation

Auto-instrumentation CLI wrapper for GenAI — setup, supported technologies, what Instana receives, and known issues.

License

MIT — see the LICENSE file included with this package.

Copyright (c) 2026 IBM Corp. Copyright (c) 2026 Instana, Inc. https://www.instana.com/