Skip to main content

​
Constructor

from respan import Respan

respan = Respan(
    api_key="your-api-key",
    instrumentations=[...],
)

​
Parameters

ParameterTypeDefaultDescription
api_keystr | NoneNoneRespan API key. Falls back to RESPAN_API_KEY env var.
base_urlstr | NoneNoneAPI base URL. Falls back to RESPAN_BASE_URL, then https://api.respan.ai/api.
app_namestr"respan"Application name for telemetry identification.
instrumentationslist | NoneNoneList of instrumentor instances to activate.
auto_instrumentbool | NoneNoneAuto-instrument LLM SDKs via OTEL. Defaults to False. Set True to enable alongside plugins.
customer_identifierstr | NoneNoneDefault customer/user ID attached to all spans.
thread_identifierstr | NoneNoneDefault conversation thread ID for all spans.
metadatadict | NoneNoneDefault metadata dict merged into all spans.
environmentstr | NoneNoneEnvironment name (e.g. "production", "staging").
**telemetry_kwargsExtra kwargs forwarded to RespanTelemetry (e.g. log_level, is_batching_enabled).

​
Environment variables

VariableDescriptionDefault
RESPAN_API_KEYRespan API key—
RESPAN_BASE_URLAPI base URLhttps://api.respan.ai/api
RESPAN_LOG_LEVELSDK log levelINFO
RESPAN_BATCHING_ENABLEDEnable batch processingtrue
Constructor parameters take precedence over environment variables.

​
Examples

​
With OpenAI Agents SDK

from respan import Respan
from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor

respan = Respan(
    api_key="your-api-key",
    instrumentations=[OpenAIAgentsInstrumentor()],
)

​
With OpenAI SDK

from respan import Respan
from respan_instrumentation_openai import OpenAIInstrumentor

respan = Respan(
    api_key="your-api-key",
    instrumentations=[OpenAIInstrumentor()],
)

​
With multiple plugins

from respan import Respan
from respan_instrumentation_openai import OpenAIInstrumentor
from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor

respan = Respan(
    api_key="your-api-key",
    instrumentations=[
        OpenAIInstrumentor(),
        OpenAIAgentsInstrumentor(),
    ],
)

​
With default attributes

Attributes set on the constructor are attached to all spans for the lifetime of the instance: 
respan = Respan(
    api_key="your-api-key",
    instrumentations=[OpenAIAgentsInstrumentor()],
    customer_identifier="user_123",
    thread_identifier="conv_abc",
    metadata={"plan": "pro", "region": "us-east"},
    environment="production",
)
For per-request attributes, use propagate_attributes() instead.

​
Minimal setup with env vars

import os
os.environ["RESPAN_API_KEY"] = "your-api-key"

from respan import Respan
from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor

respan = Respan(instrumentations=[OpenAIAgentsInstrumentor()])

​
No plugins (decorators only)

from respan import Respan, workflow, task

respan = Respan(api_key="your-api-key")

@task(name="generate")
def generate(topic: str):
    # LLM call here
    pass

@workflow(name="my_workflow")
def my_workflow():
    return generate("tracing")

​
flush()

Force flush all pending spans to exporters. Call before process exit or in serverless environments. 
respan.flush()

​
shutdown()

Deactivate all plugins and shut down the OTEL pipeline. 
respan.shutdown()