> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Span

> Span attributes, common span names, and OpenTelemetry attribute conventions.

A `Span` represents a single operation within an agent execution. Spans form a parent-child hierarchy within a trace, allowing you to understand the execution flow.

## Span Attributes

| Attribute | Type | Default | Description |
| - | - | - | - |
| `span_id` | `str` | Required | Unique span identifier |
| `trace_id` | `str` | Required | Unique identifier of the trace that contains this span |
| `parent_span_id` | `Optional[str]` | Required | Parent span ID (`None` for root spans) |
| `name` | `str` | Required | Operation name (e.g., `OpenAIChat.invoke`, `get_weather`) |
| `span_kind` | `str` | Required | Span kind (e.g., `INTERNAL`, `CLIENT`) |
| `status_code` | `str` | Required | Status: `OK`, `ERROR`, or `UNSET` |
| `status_message` | `Optional[str]` | Required | Status message (typically error details, `None` when there is none) |
| `duration_ms` | `int` | Required | Execution time in milliseconds |
| `start_time` | `datetime` | Required | When the span started |
| `end_time` | `datetime` | Required | When the span completed |
| `attributes` | `Dict[str, Any]` | Required | OpenTelemetry attributes (tokens, params, etc.) |
| `created_at` | `datetime` | Required | When the span record was created |

## Common Span Names

Spans are automatically created for various operations:

| Span Name Pattern | Description |
| - | - |
| `{AgentName}.run` | Agent execution |
| `{TeamName}.run` | Team execution |
| `{ModelName}.invoke` | LLM model call |
| `{tool_name}` | Tool execution |

## Attributes by Operation Type

The `attributes` field contains OpenTelemetry semantic attributes that vary by operation:

### LLM Spans

| Attribute | Description |
| - | - |
| `llm.token_count.prompt` | Input token count |
| `llm.token_count.completion` | Output token count |
| `llm.model_name` | Model identifier |
| `llm.provider` | Model provider name |

### Tool Spans

| Attribute | Description |
| - | - |
| `tool.name` | Tool function name |
| `tool.parameters` | Tool input parameters (JSON) |

## Methods

### `to_dict()`

Convert the span to a dictionary.

```python theme={null}
span_dict = span.to_dict()
```

**Returns:** `dict`

### `from_dict()`

Create a span from a dictionary.

```python theme={null}
span = Span.from_dict(data)
```

**Parameters:**

* `data` (`dict`): Dictionary containing span data

**Returns:** `Span`

## Usage

```python theme={null}
from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="tmp/traces.db")

# Get the most recent trace, then load its spans
traces, _ = db.get_traces(limit=1)
if not traces:
    raise RuntimeError("No traces found")

trace_id = traces[0].trace_id
spans = db.get_spans(trace_id=trace_id)

for span in spans:
    print(f"Span: {span.name}")
    print(f"  Duration: {span.duration_ms}ms")
    print(f"  Status: {span.status_code}")
    
    # Check for token usage (LLM spans)
    if span.attributes:
        tokens = span.attributes.get("llm.token_count.completion")
        if tokens:
            print(f"  Tokens: {tokens}")
```

## Building a Span Tree

```python theme={null}
def print_span_tree(spans, parent_id=None, indent=0):
    """Recursively print spans as a tree."""
    for span in spans:
        if span.parent_span_id == parent_id:
            prefix = "  " * indent + ("└─ " if indent > 0 else "")
            print(f"{prefix}{span.name} ({span.duration_ms}ms)")
            print_span_tree(spans, span.span_id, indent + 1)

# Print the spans loaded above
print_span_tree(spans)
```

## See Also

* [Trace Reference](https://agno-v2.mintlify.site/reference/tracing/trace.md) - Complete execution trace
* [DB Functions](https://agno-v2.mintlify.site/tracing/db-functions.md) - Query functions for traces and spans


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.