Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.
{
  "mcpServers": {
    "respan-docs": {
      "url": "https://respan.ai/docs/mcp"
    }
  }
}

​
What is Respan Tracing?

The Respan tracing SDK is a Python library built on OpenTelemetry that captures telemetry for LLM applications. Add @workflow, @task, @agent, and @tool decorators to your code to get full trace visibility with auto-instrumented LLM calls.

​
Setup

1

Install the SDK

pip install respan-tracing
Python Requirement: This package requires Python 3.9 or later.
2

Set environment variables

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export RESPAN_BASE_URL="https://api.respan.ai/api"  # optional, this is the default
3

Initialize and run a workflow

from respan_tracing import RespanTelemetry, workflow, task
from openai import OpenAI

telemetry = RespanTelemetry()
client = OpenAI()

@task(name="joke_creation")
def create_joke():
    completion = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Tell me a joke about AI"}],
        temperature=0.7,
        max_tokens=100,
    )
    return completion.choices[0].message.content

@workflow(name="simple_joke_workflow")
def joke_workflow():
    return create_joke()

if __name__ == "__main__":
    result = joke_workflow()
    print(result)
4

View your trace

Open the Traces page in the Respan dashboard.
Agent tracing visualization

​
Configuration

​
Python SDK

ParameterTypeDefaultDescription
app_namestr"respan"Application name attached to all spans.
api_keystr | NoneNoneAPI key. Falls back to RESPAN_API_KEY env var.
base_urlstr | NoneNoneAPI URL. Falls back to RESPAN_BASE_URL, then https://api.respan.ai/api.
log_levelstr"INFO"SDK log level: DEBUG, INFO, WARNING, ERROR, CRITICAL.
is_batching_enabledbool | NoneTrueEnable batch span processing.
instrumentsSet[Instruments] | NoneNone (all)Specific instruments to enable. Pass set() to disable all.
block_instrumentsSet[Instruments] | NoneNoneInstruments to explicitly disable.
is_enabledboolTrueSet False for no-op mode.
See RespanTelemetry reference for the full parameter list.

​
JavaScript SDK

ParameterTypeDefaultDescription
apiKeystring—API key.
appNamestring"respan"Application name.
baseURLstring"https://api.respan.ai"API base URL.
disableBatchbooleanfalseDisable batch processing (useful for testing).
logLevelstring"warn"SDK log level: "debug", "info", "warn", "error".
instrumentModulesobject—Modules to auto-instrument (e.g., { openAI: OpenAI }).

​
Attributes

Attach Respan-specific attributes to spans for filtering and grouping in the dashboard.
AttributeTypeDescription
customer_identifierstrUser or customer identifier.
customer_emailstrCustomer email address.
customer_namestrCustomer display name.
trace_group_identifierstrGroup related traces (e.g., by experiment or session).
metadataDictCustom key-value pairs for analytics.
from respan_tracing import get_client, workflow

@workflow(name="my_workflow")
def my_workflow(user_id: str):
    client = get_client()
    client.update_current_span(
        respan_params={
            "customer_identifier": user_id,
            "trace_group_identifier": "pipeline-v2",
            "metadata": {"env": "production"},
        }
    )
    return "done"