Skip to main content
This page explains what happens when your code executes with Cascade SDK tracing enabled; how spans are created, what attributes are attached, and how data flows to the Cascade backend.

​
Data flow overview

Your Code
    ↓
1. SDK creates spans with attributes
    ↓
2. OpenTelemetry batches spans in memory
    ↓
3. OTLP HTTP Exporter sends to Cascade API
    ↓
4. Backend receives and stores spans
    ↓
5. Dashboard queries and displays traces

​
Span attributes by type

​
Function span attributes

Created by trace_run() context manager. 
{
    "cascade.span_type": "function",
    "cascade.task_id": "123",  # from metadata parameter
    "cascade.user_id": "user-456",  # from metadata parameter
    # ... any custom metadata you pass
}
All custom metadata passed to trace_run() is automatically added as span attributes.

​
LLM span attributes

Created by wrap_llm_client() for all language model interactions. 
{
    "cascade.span_type": "llm",
    "llm.model": "claude-3-5-sonnet-20241022",
    "llm.provider": "anthropic",
    "llm.max_tokens": 1000,
    "llm.streaming": True
}

{
    "llm.prompt": "Hello",  # full user message
    "llm.system_message": "You are a helpful assistant",
    "llm.completion": "Hi! How can I help you today?",
    "llm.reasoning": "REASONING: I should greet the user..."
}

{
    "llm.input_tokens": 15,
    "llm.output_tokens": 24,
    "llm.total_tokens": 39,
    "llm.latency_ms": 847.5,
    "llm.cost_usd": 0.0013
}

​
Tool span attributes

Created by the @tool decorator for function executions. 
{
    "cascade.span_type": "tool",
    "tool.name": "search_database",
    "tool.description": "Search the database for matching records",  # from docstring
    "tool.input": '{"query": "customer data", "limit": 10}',  # JSON serialized
    "tool.output": '{"results": [...], "count": 5}',  # JSON serialized
    "tool.duration_ms": 234.5,
    "tool.error": "ConnectionError: Database unavailable"  # only if error
}
Input and output parameters are automatically serialized to JSON for structured storage.

​
Reasoning span attributes

Created by the @capture_reasoning decorator for reasoning extraction. 
{
    "cascade.span_type": "reasoning",
    "reasoning.name": "_log_reasoning",
    "reasoning.input": "Full text being analyzed...",
    "reasoning.output": "REASONING: Step 1...\nREASONING: Step 2...",
    "reasoning.duration_ms": 12.3,
    "reasoning.error": "ValueError: ..."  # only if error
}

​
Resource attributes

Set once at initialization via init_tracing() and attached to all spans in the trace.
AttributeDescriptionExample
service.nameYour project name"my_project"
cascade.projectProject identifier"my_project"
cascade.environmentDeployment environment"production"
deployment.environmentEnvironment name"production"
service.versionApplication version"1.0.0"
cascade.user_idUser identifier"user-123"
cascade.competition_idCompetition ID"comp-456"
Example initialization: 
init_tracing(
    project="my_project",
    environment="production",
    metadata={
        "version": "1.0.0",
        "user_id": "user-123",
        "competition_id": "comp-456"
    }
)

​
Span events

Events are timestamped occurrences within a span. The most common event is exception recording.

​
Exception events

When an error occurs, span.record_exception(e) creates an event with full details. Event structure: 
{
    "name": "exception",
    "time_unix_nano": 1701234567890123456,
    "attributes": {
        "exception.type": "ValueError",
        "exception.message": "Invalid input: expected string, got None",
        "exception.stacktrace": """Traceback (most recent call last):
  File "agent.py", line 42, in process
    result = parse_data(input)
  File "utils.py", line 15, in parse_data
    raise ValueError("Invalid input: expected string, got None")
ValueError: Invalid input: expected string, got None"""
    }
}
This is why you see full stack traces in the dashboard error section—they’re captured as span events.

​
Span status

Every span has a status indicating success or failure. 
status_code = 1  # StatusCode.OK
status_message = None
Set automatically when operation completes without exception.

​
OTLP export process

​
Batching

Spans are batched in memory for efficiency before being sent to Cascade.
  • Default batch size: 512 spans
  • Default timeout: 5 seconds
  • Trigger: Whichever comes first (batch size or timeout)
If your application exits before the batch is full or timeout occurs, some spans may not be exported. Use proper shutdown procedures to flush pending spans.

​
HTTP request

Spans are sent via HTTP POST to the Cascade API endpoint. 
POST https://api.runcascade.com/v1/traces
Content-Type: application/json
Authorization: Bearer cascade_your_api_key

{
  "resourceSpans": [
    {
      "resource": { ... },
      "scopeSpans": [
        {
          "scope": { ... },
          "spans": [ ... ]
        }
      ]
    }
  ]
}
The SDK handles authentication, batching, and retries automatically. You don’t need to manage the export process manually.