RespanTelemetry() | Respan Docs

Initialize

RespanTelemetry is the main entry point for the SDK. It initializes the OpenTelemetry tracer, configures span processors/exporters, and enables auto-instrumentation for supported libraries.

1 from respan_tracing import RespanTelemetry
2 
3 telemetry = RespanTelemetry(
4     api_key="your-api-key",
5     app_name="my-app",
6 )

When api_key is provided (or set via RESPAN_API_KEY env var), the SDK automatically adds a default processor that exports spans to Respan.

Constructor parameters

Parameter	Type	Default	Description
`app_name`	`str`	`"respan"`	Application name attached to all spans.
`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` env var, then `https://api.respan.ai/api`.
`log_level`	`str`	`"INFO"`	SDK logging level. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
`is_batching_enabled`	`bool \| None`	`None`	Enable batch span processing. Falls back to `RESPAN_BATCHING_ENABLED` env var, then `True`.
`instruments`	`Set[Instruments] \| None`	`None`	Specific instruments to enable. `None` enables all available. Pass `set()` to disable all.
`block_instruments`	`Set[Instruments] \| None`	`None`	Instruments to explicitly disable.
`headers`	`Dict[str, str] \| None`	`None`	Additional HTTP headers sent with span exports.
`resource_attributes`	`Dict[str, str] \| None`	`None`	OpenTelemetry resource attributes added to all spans.
`span_postprocess_callback`	`Callable \| None`	`None`	Callback invoked on each span before export.
`is_enabled`	`bool`	`True`	Set to `False` to disable telemetry entirely (no-op mode).
`auto_instrument`	`bool`	`True`	Enable OTEL auto-instrumentation for supported libraries. Set to `False` when using instrumentation plugins to avoid duplicate spans.

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

Minimal setup with env vars

1 import os
2 from respan_tracing import RespanTelemetry
3 
4 os.environ["RESPAN_API_KEY"] = "your-api-key"
5 
6 telemetry = RespanTelemetry()

Full configuration

1 from respan_tracing import RespanTelemetry, Instruments
2 
3 telemetry = RespanTelemetry(
4     app_name="production-app",
5     api_key="your-api-key",
6     log_level="WARNING",
7     is_batching_enabled=True,
8     instruments={Instruments.OPENAI, Instruments.ANTHROPIC},
9     resource_attributes={"service.version": "1.2.0"},
10 )

Suppress noisy instrumentation

Use block_instruments to disable HTTP-level tracing (e.g., requests, urllib3) that can clutter traces when using multiple LLM providers:

1 from respan_tracing import RespanTelemetry
2 from respan_tracing.instruments import Instruments
3 
4 telemetry = RespanTelemetry(
5     api_key="your-api-key",
6     block_instruments={Instruments.REQUESTS, Instruments.URLLIB3},
7 )

Disabled mode

1 telemetry = RespanTelemetry(is_enabled=False)  # No-op, no spans exported

add_processor()

Add a custom span processor with optional filtering. This lets you route spans to multiple destinations (file, console, external services) alongside the default Respan exporter.

1 add_processor(
2     exporter: SpanExporter,
3     name: str | None = None,
4     filter_fn: Callable | None = None,
5     is_batching_enabled: bool | None = None,
6 ) -> None

Parameter	Type	Description
`exporter`	`SpanExporter`	An OpenTelemetry span exporter instance.
`name`	`str \| None`	Processor name. When set, only spans with a matching `processors` decorator param are routed here.
`filter_fn`	`Callable \| None`	Custom filter function. Receives a span, returns `True` to export.
`is_batching_enabled`	`bool \| None`	Override batching for this processor.

Route spans to multiple exporters

1 from respan_tracing import RespanTelemetry
2 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult, ConsoleSpanExporter
3 
4 telemetry = RespanTelemetry(api_key="your-api-key")
5 
6 # Add a debug console exporter — only spans with processors="debug"
7 telemetry.add_processor(
8     exporter=ConsoleSpanExporter(),
9     name="debug",
10 )

Then use processors on decorators to route spans:

1 from respan_tracing import workflow, task
2 
3 @task(name="debug_task", processors="debug")
4 def debug_task():
5     return "only goes to debug processor"
6 
7 @task(name="all_task")
8 def all_task():
9     return "goes to all processors (default Respan + debug)"

flush()

Force flush all pending spans to exporters. Useful before process exit or in serverless environments.

1 telemetry.flush()