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

# Span Service

> Span Service API methods in the Galtea SDK

> [!WARNING]
>
> You are reading the docs of Galtea 5.11. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/span/service.md).

The Span Service in the Galtea SDK allows you to collect, manage, and persist [spans](https://docs.galtea.ai/v5.11/concepts/product/version/session/span.md) that capture the internal operations of your AI agents during inference.

This Service is exposed by the `galtea.spans` object.

> [!NOTE]
>
> Remember that we will be using the `galtea` object. More information [here](https://docs.galtea.ai/v5.11/sdk/api/galtea.md).

## Two Approaches to Span Collection

The SDK provides two ways to collect spans:

### 1. Automatic Collection with with `generate()`

When using `galtea.traces.generate()`, span collection is handled automatically:

```python theme={"system"}
@traced(type=SpanType.TOOL)
def fetch_user_data(user_id: str) -> dict:
    return {"name": "John Doe", "email": "john@example.com"}


@traced(type=SpanType.GENERATION)
def generate_response(prompt: str) -> str:
    return "Generated response..."


def my_overview_agent(input_data: AgentInput) -> AgentResponse:
    user = fetch_user_data("user_123")
    response = generate_response("Hello")
    return AgentResponse(content=response)


# Use generate() for automatic span context management
trace = galtea.traces.generate(
    agent=my_overview_agent,
    session=session,
    input="Show me user data",
)
```

### 2. Manual Collection with Context Management

For full control over the span lifecycle, use `set_context()` and `clear_context()`:

Set context before running traced functions:

```python theme={"system"}
span_context = set_context(trace_id=trace_id)
```

Then run your traced functions within this context set/open.

Once done, clear the context to [flush](https://docs.galtea.ai/v5.11/sdk/api/span/clear-context.md#param-flush) and detach:

```python theme={"system"}
clear_context(span_context)
```

> [!TIP]
>
> Use `galtea.traces.generate()` for automatic span collection instead of manual collection.

## Service Methods

### Context Management

* [@traced Decorator](https://docs.galtea.ai/v5.11/sdk/api/span/traced-decorator.md)
* [start\_span](https://docs.galtea.ai/v5.11/sdk/api/span/start-span.md)
* [set\_context](https://docs.galtea.ai/v5.11/sdk/api/span/set-context.md)
* [clear\_context](https://docs.galtea.ai/v5.11/sdk/api/span/clear-context.md)

### Direct API Methods

* [Create Span](https://docs.galtea.ai/v5.11/sdk/api/span/create.md)
* [Create Span Batch](https://docs.galtea.ai/v5.11/sdk/api/span/create-batch.md)
* [List Spans](https://docs.galtea.ai/v5.11/sdk/api/span/list.md)
* [Get Span](https://docs.galtea.ai/v5.11/sdk/api/span/get.md)
* [Delete Span](https://docs.galtea.ai/v5.11/sdk/api/span/delete.md)

## Related

> [card] [Span](https://docs.galtea.ai/v5.11/concepts/product/version/session/span.md)
>
> Understand how spans capture the internal operations of your AI agents.


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