Respan() | Respan Docs

Constructor

1 from respan import Respan
2 
3 respan = Respan(
4     api_key="your-api-key",
5     instrumentations=[...],
6 )

Parameters

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Respan API key. Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	API base URL. Falls back to `RESPAN_BASE_URL`, then `https://api.respan.ai/api`.
`app_name`	`str`	`"respan"`	Application name for telemetry identification.
`instrumentations`	`list \| None`	`None`	List of instrumentor instances to activate.
`auto_instrument`	`bool \| None`	`None`	Auto-instrument LLM SDKs via OTEL. Defaults to `False`. Set `True` to enable alongside plugins.
`customer_identifier`	`str \| None`	`None`	Default customer/user ID attached to all spans.
`thread_identifier`	`str \| None`	`None`	Default conversation thread ID for all spans.
`metadata`	`dict \| None`	`None`	Default metadata dict merged into all spans.
`environment`	`str \| None`	`None`	Environment name (e.g. `"production"`, `"staging"`).
`**telemetry_kwargs`			Extra kwargs forwarded to `RespanTelemetry` (e.g. `log_level`, `is_batching_enabled`).

Environment variables

Variable	Description	Default
`RESPAN_API_KEY`	Respan API key	—
`RESPAN_BASE_URL`	API base URL	`https://api.respan.ai/api`
`RESPAN_LOG_LEVEL`	SDK log level	`INFO`
`RESPAN_BATCHING_ENABLED`	Enable batch processing	`true`

Constructor parameters take precedence over environment variables.

Examples

With OpenAI Agents SDK

1 from respan import Respan
2 from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
3 
4 respan = Respan(
5     api_key="your-api-key",
6     instrumentations=[OpenAIAgentsInstrumentor()],
7 )

With OpenAI SDK

1 from respan import Respan
2 from respan_instrumentation_openai import OpenAIInstrumentor
3 
4 respan = Respan(
5     api_key="your-api-key",
6     instrumentations=[OpenAIInstrumentor()],
7 )

With multiple plugins

1 from respan import Respan
2 from respan_instrumentation_openai import OpenAIInstrumentor
3 from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
4 
5 respan = Respan(
6     api_key="your-api-key",
7     instrumentations=[
8         OpenAIInstrumentor(),
9         OpenAIAgentsInstrumentor(),
10     ],
11 )

With default attributes

Attributes set on the constructor are attached to all spans for the lifetime of the instance:

1 respan = Respan(
2     api_key="your-api-key",
3     instrumentations=[OpenAIAgentsInstrumentor()],
4     customer_identifier="user_123",
5     thread_identifier="conv_abc",
6     metadata={"plan": "pro", "region": "us-east"},
7     environment="production",
8 )

For per-request attributes, use propagate_attributes() instead.

Minimal setup with env vars

1 import os
2 os.environ["RESPAN_API_KEY"] = "your-api-key"
3 
4 from respan import Respan
5 from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor
6 
7 respan = Respan(instrumentations=[OpenAIAgentsInstrumentor()])

No plugins (decorators only)

1 from respan import Respan, workflow, task
2 
3 respan = Respan(api_key="your-api-key")
4 
5 @task(name="generate")
6 def generate(topic: str):
7     # LLM call here
8     pass
9 
10 @workflow(name="my_workflow")
11 def my_workflow():
12     return generate("tracing")

flush()

Force flush all pending spans to exporters. Short-lived Python scripts drain pending spans automatically on normal process exit; call flush() only when you need an explicit export checkpoint before the process continues, or in serverless environments that may freeze before process-exit hooks run.

1 respan.flush()

shutdown()

Deactivate all plugins and shut down the OTEL pipeline.

1 respan.shutdown()