> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnia-voice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> omnia-tracing — setup() before your LLM clients, tracing.instrumented tells you exactly what's captured; standard OpenTelemetry underneath, eject anytime.

`omnia-tracing` streams your Python app's LLM traffic to Omnia without
moving your inference. It contains
[no instrumentation code of its own](/sdks/overview): standard
OpenTelemetry, curated.

## Install

```bash theme={null}
pip install omnia-tracing
```

## Use

Call once at startup, **before constructing any LLM client**:

```python theme={null}
from omnia_tracing import setup

tracing = setup()          # reads OMNIA_API_KEY and OMNIA_TAG
print(tracing.instrumented)  # e.g. ['openai', 'anthropic'] — only what's installed
```

Short-lived scripts should call `tracing.shutdown()` before exit to flush
pending spans; long-running servers can skip it.

## Configuration

| Env var               | Meaning                                                                              | Default                                     |
| --------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------- |
| `OMNIA_API_KEY`       | Omnia API key, **required**; `setup()` raises rather than exporting nowhere silently | —                                           |
| `OMNIA_TAG`           | Population tag: one tag = one evaluation population in Omnia                         | unset                                       |
| `OMNIA_OTLP_ENDPOINT` | OTLP/HTTP traces endpoint                                                            | `https://gateway.omnia-voice.com/v1/traces` |
| `OTEL_SERVICE_NAME`   | Standard OTel service name                                                           | unset                                       |

All options can also be passed to `setup()` directly; explicit options beat
env vars.

## What gets captured

OpenAI, Anthropic, Gemini, and LangChain calls: automatically, and **only
for libraries actually installed** (the `instrumented` list tells you exactly
which). Successful calls, streamed calls, and **failed** calls (stored as
ERROR trace structure, the most valuable signal there is, and the one
status-code dashboards can't see).

Your inference does **not** move: requests keep going to your current
provider; only trace telemetry flows to Omnia.

## The eject guarantee

Remove this package and wire the same standard pieces yourself; identical
spans, same endpoint, nothing lost:

```python theme={null}
import os
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-service", "omnia.tag": "my-agent"})
)
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://gateway.omnia-voice.com/v1/traces",
            headers={"Authorization": f"Bearer {os.environ['OMNIA_API_KEY']}"},
        )
    )
)
AnthropicInstrumentor().instrument(tracer_provider=provider)
# ...and the other instrumentors for whichever libraries you use
```

Already emitting OpenTelemetry (Pydantic AI, an existing OTel setup)? You
don't need this package at all; three env vars point your existing exporter
at Omnia. See [OTLP trace ingest](/reference/otlp-ingest).

## Privacy

Span **structure** is always stored. Model-call **content**
(prompts/completions) is stored only if your Omnia workspace has
[request logging](/reference/request-logging) enabled, under your retention
window, with the same scrubbing and size caps as gateway traffic.

## Verify your setup

```bash theme={null}
OMNIA_API_KEY=sk_... sh -c "$(curl -fsSL https://platform.omnia-voice.com/setup.sh)"
```

Proves the key works, confirms traces are actually landing, and names your
one next step. A setup that isn't sending traces fails the check explicitly
instead of failing silently.