> ## Documentation Index
> Fetch the complete documentation index at: https://www.getmaxim.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# decorators.Span

> Span utilities for decorators for automatic logging and instrumentation of functions and methods.

[View module source on GitHub](https://github.com/maximhq/maxim-py/blob/main/maxim/decorators/span.py)

## \_SpanStack Objects

```python theme={null}
@dataclass
class _SpanStack()
```

Stack of spans.

#### push

```python theme={null}
def push(span: Span) -> None
```

Push a span onto the stack.

#### pop

```python theme={null}
def pop() -> Optional[Span]
```

Pop a span from the stack.

#### current

```python theme={null}
def current() -> Optional[Span]
```

Get the current span from the stack.

#### current\_span

```python theme={null}
def current_span() -> Optional[Span]
```

Get the current span from the stack.

#### span

```python theme={null}
def span(logger: Optional[Logger] = None,
         id: Optional[Union[str, Callable]] = None,
         trace_id: Optional[Union[str, Callable]] = None,
         name: Optional[str] = None,
         tags: Optional[dict] = None,
         evaluators: Optional[List[str]] = None,
         evaluator_variables: Optional[Dict[str, str]] = None)
```

Decorator for creating a span within a trace.

This decorator should be used within a function that is already decorated with @trace.
It creates a new span and injects a tracer object into the decorated function.

**Arguments**:

| Name       | Type                                              | Description                                                                                                                    |
| ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `logger`   | *[Logger](/sdk/python/references/logger/logger)*  | The [Logger](/sdk/python/references/logger/logger) instance to use for logging.                                                |
| `id`       | *Optional\[str] or Optional\[Callable], optional* | The ID for the span. If callable, it will be called to generate the ID. Defaults to None.                                      |
| `trace_id` | *Optional\[str] or Optional\[Callable], optional* | The trace ID to associate with this span. If callable, it will be called to generate the trace ID. Defaults to current\_trace. |
| `name`     | *Optional\[str], optional*                        | The name of the span. Defaults to None.                                                                                        |
| `tags`     | *Optional\[dict], optional*                       | Additional tags to associate with the span. Defaults to None.                                                                  |

**Returns**:

| Name       | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `Callable` | A decorator function that wraps the original function with span functionality. |

**Raises**:

* `ValueError` - If the decorator is used outside of a @trace decorated function.