Respan Tracing

Respan's library for sending telemetries of LLM applications in OpenLLMetry format.

Integrations

Configuration

1. Install

Python

pip install respan-ai openai

TypeScript/JavaScript

npm install @respan/respan openai

Replace openai with the provider SDK your application uses. The facade supplies the eligible first-party instrumentation adapters; TypeScript users should not install with --omit=optional because those adapters are optional dependencies of @respan/respan.

2. Set Environment Variables

The quickstart below routes OpenAI through the Respan gateway, so RESPAN_API_KEY authenticates both inference and telemetry export. When calling a provider directly, configure that provider's credentials and endpoint normally; Respan still uses RESPAN_API_KEY for telemetry.

Quickstart

3. Run Script

Python

import os
from openai import OpenAI
from respan import Respan

# Omit `instrumentations` to auto-discover the matching bundled adapter.
respan = Respan()

# Respan API key authenticates both proxy and tracing
respan_api_key = os.environ["RESPAN_API_KEY"]
respan_base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api")

client = OpenAI(api_key=respan_api_key, base_url=respan_base_url)

response = client.chat.completions.create(
    model="gpt-4.1-nano",
    messages=[{"role": "user", "content": "Say hello in three languages."}],
)
print(response.choices[0].message.content)
respan.shutdown()

TypeScript/JavaScript

import OpenAI from "openai";
import { Respan } from "@respan/respan";

const respanBaseURL =
  process.env.RESPAN_BASE_URL ?? "https://api.respan.ai/api";

// Omit `instrumentations` to auto-discover the matching bundled adapter.
const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: respanBaseURL,
});
await respan.initialize();

const client = new OpenAI({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: respanBaseURL,
});

const response = await client.chat.completions.create({
  model: "gpt-4.1-nano",
  messages: [{ role: "user", content: "Say hello in three languages." }],
});
console.log(response.choices[0].message.content);
await respan.shutdown();

4. View Dashboard

See your traces in the Respan platform.

Further Reading

Examples

• Python OpenAI SDK examples — hello world, decorators, attributes, batch, streaming, tool calls
• Python OpenAI Agents SDK examples — hello world, handoffs, routing, guardrails
• TypeScript OpenAI SDK examples — hello world, decorators, attributes

Automatic Direct LLM Integrations

Install the facade and the provider SDK, omit the instrumentations option, and initialize Respan before the first provider call. Missing provider SDKs are skipped without failing startup and are visible through the instrumentation status API.

respan-ai bundles the seven eligible Python adapters. A normal @respan/respan install includes the nine TypeScript adapters as optional dependencies.

Inspect the result after construction in Python with respan.get_auto_instrumentation_status(), or after await respan.initialize() in TypeScript with respan.getInstrumentationStatus().

Explicit Framework and Wrapper Integrations

LLM wrappers, agent frameworks, application frameworks, protocol/tooling integrations, observability bridges, and vector databases remain explicit opt-ins to prevent duplicate spans. Supplying instrumentations selects explicit mode and disables automatic discovery by default.

Python can intentionally combine explicit plugins with direct-SDK automatic discovery by setting is_auto_instrument=True. Use Respan(is_auto_instrument=False) to disable automatic discovery entirely.

In TypeScript, use disabledInstrumentations: ["openrouter"] to disable one automatic adapter, or instrumentations: [] to disable all automatic discovery. TypeScript explicit mode is currently exclusive and cannot be combined with automatic discovery.

Workflow and Task Decorators

Structure traces with @workflow / @task (Python) or withWorkflow / withTask (TypeScript). See the decorators example for details.

Propagate Attributes

Attach customer_identifier, thread_identifier, and metadata to all spans in scope. See the attributes example.

Respan Collector (at-least-once delivery)

The SDKs batch spans in memory and retry, but never write to disk, so spans still queued during a long outage or a process crash are lost. For long-running agents that must not lose spans, run the packaged Respan Collector next to the application — the upstream OpenTelemetry Collector with a persistent, bounded queue — and point RESPAN_BASE_URL at it (respan collector start or docker compose -f collector/docker-compose.yaml up -d).

Star us

Please star us if you found this helpful!