> ## Documentation Index
> Fetch the complete documentation index at: https://agent-observability-docs.splunk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# span_lifecycle

## Module

Shared callback-to-span construction for incremental handler telemetry.

## HandlerSpanState

Mutable ownership state for one in-flight framework callback.

## build\_handler\_step

```python theme={null}
def build_handler_step(node: Node,
                       *,
                       step_id: UUID | None=None,
                       children: list[BaseStep] | None=None,
                       openai_agents: bool=False) -> BaseStep
```

Build a schema-validated provisional or final span from a callback node.

## discard\_handler\_step

```python theme={null}
def discard_handler_step(logger: SplunkAOLogger,
                         active_steps: dict[str, HandlerSpanState],
                         node_id: str) -> None
```

Discard one failed callback step without disturbing its siblings or owner.

## finalize\_handler\_step

```python theme={null}
def finalize_handler_step(node: Node,
                          state: HandlerSpanState,
                          *,
                          openai_agents: bool=False) -> BaseStep
```

Build the final validated form while retaining the provisional UUID and children.

## release\_handler\_steps

```python theme={null}
def release_handler_steps(logger: SplunkAOLogger,
                          active_steps: dict[str, HandlerSpanState]) -> None
```

Release unfinished callback activations and identities in stack order.