Skip to main content

​
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. 
from respan_tracing import RespanTelemetry

telemetry = RespanTelemetry(
    api_key="your-api-key",
    app_name="my-app",
)
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

ParameterTypeDefaultDescription
app_namestr"respan"Application name attached to all spans.
api_keystr | NoneNoneRespan API key. Falls back to RESPAN_API_KEY env var.
base_urlstr | NoneNoneAPI base URL. Falls back to RESPAN_BASE_URL env var, then https://api.respan.ai/api.
log_levelstr"INFO"SDK logging level. One of DEBUG, INFO, WARNING, ERROR, CRITICAL.
is_batching_enabledbool | NoneNoneEnable batch span processing. Falls back to RESPAN_BATCHING_ENABLED env var, then True.
instrumentsSet[Instruments] | NoneNoneSpecific instruments to enable. None enables all available. Pass set() to disable all.
block_instrumentsSet[Instruments] | NoneNoneInstruments to explicitly disable.
headersDict[str, str] | NoneNoneAdditional HTTP headers sent with span exports.
resource_attributesDict[str, str] | NoneNoneOpenTelemetry resource attributes added to all spans.
span_postprocess_callbackCallable | NoneNoneCallback invoked on each span before export.
is_enabledboolTrueSet to False to disable telemetry entirely (no-op mode).

​
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

​
Minimal setup with env vars

import os
from respan_tracing import RespanTelemetry

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

telemetry = RespanTelemetry()

​
Full configuration

from respan_tracing import RespanTelemetry, Instruments

telemetry = RespanTelemetry(
    app_name="production-app",
    api_key="your-api-key",
    log_level="WARNING",
    is_batching_enabled=True,
    instruments={Instruments.OPENAI, Instruments.ANTHROPIC},
    resource_attributes={"service.version": "1.2.0"},
)

​
Suppress noisy instrumentation

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

telemetry = RespanTelemetry(
    api_key="your-api-key",
    block_instruments={Instruments.REQUESTS, Instruments.URLLIB3},
)

​
Disabled mode

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. 
add_processor(
    exporter: SpanExporter,
    name: str | None = None,
    filter_fn: Callable | None = None,
    is_batching_enabled: bool | None = None,
) -> None
ParameterTypeDescription
exporterSpanExporterAn OpenTelemetry span exporter instance.
namestr | NoneProcessor name. When set, only spans with a matching processors decorator param are routed here.
filter_fnCallable | NoneCustom filter function. Receives a span, returns True to export.
is_batching_enabledbool | NoneOverride batching for this processor.

​
Route spans to multiple exporters

from respan_tracing import RespanTelemetry
from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult, ConsoleSpanExporter

telemetry = RespanTelemetry(api_key="your-api-key")

# Add a debug console exporter — only spans with processors="debug"
telemetry.add_processor(
    exporter=ConsoleSpanExporter(),
    name="debug",
)
Then use processors on decorators to route spans: 
from respan_tracing import workflow, task

@task(name="debug_task", processors="debug")
def debug_task():
    return "only goes to debug processor"

@task(name="all_task")
def all_task():
    return "goes to all processors (default Respan + debug)"

​
flush()

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