Traces | Respan Docs

Set up Respan

Sign up — Create an account at platform.respan.ai
Create an API key — Generate one on the API keys page
Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page

Use AI

Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.

1 {
2   "mcpServers": {
3     "respan-docs": {
4       "url": "https://mcp.respan.ai/mcp/docs"
5     }
6   }
7 }

The Respan tracing SDK provides decorators and wrappers to instrument your code. This page covers the detailed features.

Quickstart

If you want traces as fast as possible, install Respan, pick your framework, run one request, then open the Traces page.

1. Set your API key

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$ export RESPAN_BASE_URL="https://api.respan.ai/api"

If your framework calls the provider directly instead of going through Respan Gateway, also set the provider key such as OPENAI_API_KEY or ANTHROPIC_API_KEY.

2. Choose your framework

OpenAI SDK

OpenAI Agents SDK

Claude Agent SDK

Vercel AI SDK

Full guide: OpenAI SDK

$ pip install respan-ai respan-instrumentation-openai openai python-dotenv

1 import os
2 from dotenv import load_dotenv
3 
4 load_dotenv()
5 
6 from openai import OpenAI
7 from respan import Respan
8 from respan_instrumentation_openai import OpenAIInstrumentor
9 
10 respan = Respan(instrumentations=[OpenAIInstrumentor()])
11 
12 client = OpenAI(
13     api_key=os.getenv("RESPAN_API_KEY"),
14     base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
15 )
16 
17 response = client.chat.completions.create(
18     model="gpt-4.1-nano",
19     messages=[{"role": "user", "content": "Say hello in three languages."}],
20 )
21 print(response.choices[0].message.content)
22 respan.flush()

3. Need raw OTLP instead?

If you already have OpenTelemetry set up, skip the framework SDKs and send spans directly to the OTLP endpoint or follow the manual ingestion guide.

Decorators & span types

Use decorators (Python) or wrapper methods (JS/TS) to create spans. Each decorator creates a different span type in the trace tree.

Decorator	Span type	Use for
`@workflow` / `withWorkflow`	Workflow	Top-level parent span
`@task` / `withTask`	Task	Individual steps within a workflow
`@agent` / `withAgent`	Agent	Agent-level operations
`@tool` / `withTool`	Tool	Tool/function calls

1 from openai import OpenAI
2 from respan_tracing.decorators import workflow, task
3 from respan_tracing.main import RespanTelemetry
4 
5 k_tl = RespanTelemetry()
6 client = OpenAI()
7 
8 @task(name="joke_creation")
9 def create_joke():
10     completion = client.chat.completions.create(
11         model="gpt-3.5-turbo",
12         messages=[{"role": "user", "content": "Tell me a joke about opentelemetry"}],
13         temperature=0.5,
14         max_tokens=100,
15     )
16     return completion.choices[0].message.content
17 
18 @task(name="pirate_joke_translation")
19 def translate_joke_to_pirate(joke: str):
20     completion = client.chat.completions.create(
21         model="gpt-3.5-turbo",
22         messages=[{"role": "user", "content": "translate to pirate language:\n\n" + joke}],
23     )
24     return completion.choices[0].message.content
25 
26 @workflow(name="joke_workflow")
27 def joke_workflow():
28     joke = create_joke()
29     pirate_joke = translate_joke_to_pirate(joke)
30     return pirate_joke
31 
32 result = joke_workflow()
33 print(result)

For the full SDK API reference, see the Python SDK or TypeScript SDK.

Class-based workflows

Apply @workflow to a class with method_name to designate the entry point. Use @task on individual methods.

1 from openai import OpenAI
2 from respan_tracing import RespanTelemetry
3 from respan_tracing.decorators import workflow, task
4 
5 k_tl = RespanTelemetry()
6 client = OpenAI()
7 
8 @workflow(name="joke_agent", method_name="run")
9 class JokeAgent:
10     @task(name="joke_creation")
11     def create_joke(self):
12         completion = client.chat.completions.create(
13             model="gpt-3.5-turbo",
14             messages=[{"role": "user", "content": "Tell me a joke"}],
15         )
16         return completion.choices[0].message.content
17 
18     def run(self):
19         return self.create_joke()
20 
21 agent = JokeAgent()
22 result = agent.run()

Override span input & output

Control what appears as a span’s input/output in the trace UI using OpenTelemetry attributes:

Python

1 import json
2 from opentelemetry.semconv_ai import SpanAttributes
3 from respan_tracing.main import RespanTelemetry
4 from respan_tracing.decorators import workflow
5 
6 k_tl = RespanTelemetry()
7 client = k_tl.get_client()
8 
9 @workflow(name="update_attributes_test")
10 def update_attributes_test(input: str):
11     force_set_attributes = {
12         SpanAttributes.TRACELOOP_ENTITY_INPUT: json.dumps({
13             "args": [],
14             "kwargs": {"text": "custom input"}
15         }),
16     }
17 
18     client.update_current_span(
19         attributes=force_set_attributes,
20         name="update_attributes_test",
21         respan_params={"metadata": {"test": "test"}},
22     )
23 
24     return "Some desired output"
25 
26 if __name__ == "__main__":
27     update_attributes_test("Some input")

Use update_current_span(attributes=...) for overriding displayed input/output. Values must be JSON-serializable strings via json.dumps(...).

Integration frameworks

Respan supports 90+ integrations with popular AI frameworks. See the Integrations overview for the full list, or jump to:

Manual ingestion

Use manual ingestion when you have existing log data, custom telemetry pipelines, or OpenTelemetry setups that need to send traces to Respan without using a framework SDK.

OTLP endpoint

If you have an existing OpenTelemetry setup, send traces directly to Respan’s OTLP-compatible endpoint. This works with any OpenTelemetry SDK or collector.

POST https://api.respan.ai/api/v2/traces
Authorization: Bearer {RESPAN_API_KEY}
Content-Type: application/json  (or application/x-protobuf)

Environment variable configuration

.env

$ OTEL_EXPORTER_OTLP_ENDPOINT="https://api.respan.ai/api"
$ OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_RESPAN_API_KEY"
$ OTEL_EXPORTER_OTLP_PROTOCOL="http/json"

SDK configuration

Python

JS/TS

cURL

1 from opentelemetry import trace
2 from opentelemetry.sdk.trace import TracerProvider
3 from opentelemetry.sdk.trace.export import BatchSpanProcessor
4 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
5 
6 exporter = OTLPSpanExporter(
7     endpoint="https://api.respan.ai/api/v2/traces",
8     headers={"Authorization": "Bearer YOUR_RESPAN_API_KEY"},
9 )
10 
11 provider = TracerProvider()
12 provider.add_span_processor(BatchSpanProcessor(exporter))
13 trace.set_tracer_provider(provider)
14 
15 tracer = trace.get_tracer("my-service")
16 with tracer.start_as_current_span("my-operation") as span:
17     span.set_attribute("gen_ai.request.model", "gpt-4")
18     # Your code here

Respan automatically parses OTel spans, extracts Gen AI semantic conventions and Respan-specific attributes, and maps them to the Respan data model. For the full OTLP schema and recognized attributes, see the OTLP ingest API reference.

Legacy JSON ingest API

Example project: Ingest traces example

Use this endpoint when you already have span-shaped JSON and need the legacy v1 ingest path. For new OpenTelemetry integrations, prefer the OTLP endpoint at /api/v2/traces.

Construct traces by posting spans as JSON. Every span is a JSON object. Spans with the same trace_unique_id are grouped into a single trace. Parent-child relationships are defined via span_parent_id.

Endpoint

POST {RESPAN_BASE_URL}/v1/traces/ingest
Authorization: Bearer {RESPAN_API_KEY}

Request body shapes

This legacy endpoint accepts either of these JSON payloads:

1 [
2   {
3     "trace_unique_id": "a-trace-id",
4     "span_unique_id": "root-span-id"
5   }
6 ]

1 {
2   "data": [
3     {
4       "trace_unique_id": "a-trace-id",
5       "span_unique_id": "root-span-id"
6     }
7   ]
8 }

Response

Returns 200 OK with a message like:

1 {
2   "message": "Processed 2 Vercel spans"
3 }

Span fields

Field	Type	Required	Description
`trace_unique_id`	string	Yes	Groups spans into a single trace
`span_unique_id`	string	Yes	Unique ID for the span
`span_parent_id`	string		Parent span ID; omit or `null` for root spans
`span_name`	string		Name of the span (e.g. `"openai.chat"`)
`start_time`	string		Span start time (RFC3339 UTC)
`timestamp`	string		Span end time (RFC3339 UTC)
`model`	string		Model used
`input`	string / object		Span input data
`output`	string / object		Span output data
`metadata`	object		Custom key-value pairs

For the full list, see Span fields reference.

Example

$ curl -X POST "$RESPAN_BASE_URL/v1/traces/ingest" \
>   -H "Authorization: Bearer $RESPAN_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '[
>     {
>       "trace_unique_id": "a-trace-id",
>       "span_unique_id": "root-span-id",
>       "span_name": "workflow.start",
>       "span_parent_id": null,
>       "timestamp": "2025-09-08T07:46:14.007279Z",
>       "start_time": "2025-09-08T07:46:14.007279Z"
>     },
>     {
>       "trace_unique_id": "a-trace-id",
>       "span_unique_id": "child-span-id",
>       "span_name": "openai.chat",
>       "span_parent_id": "root-span-id",
>       "timestamp": "2025-09-08T07:46:19.041835Z",
>       "start_time": "2025-09-08T07:46:18.037942Z"
>     }
>   ]'