Metadata-Version: 2.4
Name: genai-instana
Version: 0.1.0a3
Summary: Auto-instrumentation CLI wrapper that adds GenAI traces and metrics to Python applications for Instana, with no code changes
Author-email: Kartik Hiremath <kartik.hiremath001@ibm.com>, Madhu Tadiparthi <madhu.tadiparthi@ibm.com>, Amit Madhabhavi <amit.madhabhavi1@ibm.com>
License-Expression: MIT
Project-URL: Homepage, https://www.ibm.com/products/instana
Project-URL: Documentation, https://www.ibm.com/docs/en/instana-observability/saas?topic=guides-auto-instrumentation-cli-wrapper-genai
Keywords: opentelemetry,genai,llm,tracing,observability,instana,traceloop,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-sdk>=1.42.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.42.0
Requires-Dist: opentelemetry-instrumentation-requests>=0.63b0
Requires-Dist: opentelemetry-instrumentation-httpx>=0.63b0
Requires-Dist: httpx>=0.27
Requires-Dist: opentelemetry-instrumentation-urllib3>=0.63b0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.63b0
Requires-Dist: opentelemetry-instrumentation-asgi>=0.63b0
Requires-Dist: opentelemetry-instrumentation-flask>=0.63b0
Requires-Dist: opentelemetry-instrumentation-wsgi>=0.63b0
Requires-Dist: opentelemetry-semantic-conventions-ai>=0.5.1
Requires-Dist: traceloop-sdk>=0.61.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: psutil>=7.2.2
Requires-Dist: autowrapt>=1.0
Provides-Extra: fastapi
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.63b0; extra == "fastapi"
Requires-Dist: opentelemetry-instrumentation-asgi>=0.63b0; extra == "fastapi"
Provides-Extra: flask
Requires-Dist: opentelemetry-instrumentation-flask>=0.63b0; extra == "flask"
Requires-Dist: opentelemetry-instrumentation-wsgi>=0.63b0; extra == "flask"
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: langchain-core>=0.3; extra == "test"
Requires-Dist: flask>=2.0; extra == "test"
Dynamic: license-file

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

```bash
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.

## Quick start

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

```bash
# 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:

```text
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`.

```bash
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**

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

**Option B — Standard OpenTelemetry variables**

```bash
# 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.

## Coverage

| Category | Covered |
|---|---|
| LLM providers | OpenAI and OpenAI-compatible gateways, LiteLLM, IBM watsonx, Groq, and OpenRouter |
| Frameworks | LangChain, LangGraph, and CrewAI |
| Web servers | FastAPI (uvicorn) and Flask |

## 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](https://www.ibm.com/docs/en/instana-observability/saas?topic=guides-auto-instrumentation-cli-wrapper-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/
