Span

The Span class represents a granular operation within a trace, such as an LLM call, tool execution, embedding generation, or retrieval operation. Spans can be nested to represent sub-operations. Create a Span via trace.log_span() or span.log_span() for nested spans.

Properties

Property	Type	Description
`span`	`CreateLogSpanRequest`	The underlying API payload containing the span data. Access nested fields via `span.span` (e.g. `span.span.name`, `span.span.reference_id`).
`trace`	`Trace`	The parent Trace this span belongs to.

Status Values

Span status (SpanStatus) must be one of: "success", "failure", "aborted", "cancelled", "unknown".

Methods

update

Updates span fields in place. Takes a dict with the fields to update. Only the keys "name", "status", "tags", "attributes", "run_evaluation", and "content" are applied; all other keys are silently ignored. Returns self for method chaining.

from adaline_api.models.log_span_content import LogSpanContent
from adaline_api.models.log_span_model_content import LogSpanModelContent

span.update({
    "status": "success",
    "tags": ["llm", "gpt-4"],
    "attributes": {"tokens": 1500},
    "run_evaluation": True,
    "content": LogSpanContent(
        actual_instance=LogSpanModelContent(
            type="Model",
            provider="openai",
            model="gpt-4",
            input='[{"role": "user", "content": "Hello"}]',
            output='{"role": "assistant", "content": "Hi there!"}'
        )
    )
})

# Method chaining
span.update({"status": "success"}).update({"tags": ["final"]})

Parameters

updates

dict

required

Dictionary of fields to update.

Key	Type	Description
`"name"`	`str`	Update the span display name.
`"status"`	`str`	Update the span status (`SpanStatus`).
`"tags"`	`list[str]`	Replace the span tags.
`"attributes"`	`dict[str, Any]`	Replace the span attributes. Values are auto-wrapped in `LogAttributesValue`.
`"run_evaluation"`	`bool`	Whether to run evaluation on this span.
`"content"`	`LogSpanContent`	Replace the span content payload.

Returns: Span (self, for chaining).

log_span

Creates a child Span nested under this span and adds it to the monitor buffer. The child span’s parent_reference_id is automatically set to this span’s reference_id. This is a synchronous method.

child_span = span.log_span(
    name="Tool Execution",
    status="unknown",
    prompt_id=None,
    deployment_id=None,
    run_evaluation=False,
    tags=["tool"],
    attributes={"tool_name": "search"},
    content=None
)

Parameters

name

str

required

Display name for the child span.

status

str

default:"unknown"

Span status (SpanStatus). One of: "success", "failure", "aborted", "cancelled", "unknown".

reference_id

str | None

Client-side unique identifier. If omitted, a UUID is auto-generated.

prompt_id

str | None

Prompt identifier to associate with this span.

deployment_id

str | None

Deployment identifier to associate with this span.

run_evaluation

bool | None

Whether to run evaluation on this span.

end

Marks the span as complete and ready for flushing. Automatically ends all child spans whose parent_reference_id matches this span. Idempotent: subsequent calls return the reference ID without side effects.

reference_id = span.end()

Returns: str | None — the span’s reference_id.

Span Content Types

Content is wrapped using LogSpanContent with one of the following 8 types:

LogSpanModelContent

Standard LLM inference calls.

from adaline_api.models.log_span_model_content import LogSpanModelContent

content = LogSpanContent(
    actual_instance=LogSpanModelContent(
        type="Model",
        provider="openai",
        model="gpt-4",
        input='[{"role": "user", "content": "Hello"}]',
        output='{"role": "assistant", "content": "Hi!"}'
    )
)

LogSpanModelStreamContent

Streaming LLM inference calls.

from adaline_api.models.log_span_model_stream_content import LogSpanModelStreamContent

content = LogSpanContent(
    actual_instance=LogSpanModelStreamContent(
        type="ModelStream",
        provider="openai",
        model="gpt-4",
        input='[{"role": "user", "content": "Hello"}]',
        output='{"role": "assistant", "content": "Hi!"}'
    )
)

LogSpanEmbeddingsContent

Embedding generation calls.

from adaline_api.models.log_span_embeddings_content import LogSpanEmbeddingsContent

content = LogSpanContent(
    actual_instance=LogSpanEmbeddingsContent(
        type="Embeddings",
        input='{"model": "text-embedding-3-large", "input": "search query"}',
        output='{"dimensions": 3072}'
    )
)

LogSpanFunctionContent

Custom application logic and function calls.

from adaline_api.models.log_span_function_content import LogSpanFunctionContent

content = LogSpanContent(
    actual_instance=LogSpanFunctionContent(
        type="Function",
        input='{"arg1": "value1"}',
        output='{"result": "value2"}'
    )
)

LogSpanToolContent

Tool/API invocations.

from adaline_api.models.log_span_tool_content import LogSpanToolContent

content = LogSpanContent(
    actual_instance=LogSpanToolContent(
        type="Tool",
        input='{"function": "search", "args": {"query": "weather"}}',
        output='{"results": ["sunny", "72F"]}'
    )
)

LogSpanGuardrailContent

Safety and compliance checks.

from adaline_api.models.log_span_guardrail_content import LogSpanGuardrailContent

content = LogSpanContent(
    actual_instance=LogSpanGuardrailContent(
        type="Guardrail",
        input='{"text": "user message"}',
        output='{"safe": true, "categories": []}'
    )
)

LogSpanRetrievalContent

RAG and vector database queries.

from adaline_api.models.log_span_retrieval_content import LogSpanRetrievalContent

content = LogSpanContent(
    actual_instance=LogSpanRetrievalContent(
        type="Retrieval",
        input='{"query": "How does auth work?", "top_k": 5}',
        output='{"documents": [{"id": "doc1", "score": 0.95}]}'
    )
)

LogSpanOtherContent

Catch-all for any other operation type.

from adaline_api.models.log_span_other_content import LogSpanOtherContent

content = LogSpanContent(
    actual_instance=LogSpanOtherContent(
        type="Other",
        input="{}",
        output="{}"
    )
)

Example: Nested Spans

llm_span = trace.log_span(
    name="Agent Orchestrator",
    tags=["agent"]
)

tool_span = llm_span.log_span(
    name="Web Search Tool",
    tags=["tool"]
)

tool_span.update({
    "status": "success",
    "content": LogSpanContent(
        actual_instance=LogSpanToolContent(
            type="Tool",
            input='{"query": "latest news"}',
            output='{"results": ["Article 1", "Article 2"]}'
        )
    )
})
tool_span.end()

llm_span.update({"status": "success"})
llm_span.end()  # also ends any un-ended child spans

Get started

API

SDKs

Proxy

Span

Span

Properties

Status Values

Methods

update

Parameters

log_span

Parameters

end

Span Content Types

LogSpanModelContent

LogSpanModelStreamContent

LogSpanEmbeddingsContent

LogSpanFunctionContent

LogSpanToolContent

LogSpanGuardrailContent

LogSpanRetrievalContent

LogSpanOtherContent

Example: Nested Spans

​Span

​Properties

​Status Values

​Methods

​update

​Parameters

​log_span

​Parameters

​end

​Span Content Types

​LogSpanModelContent

​LogSpanModelStreamContent

​LogSpanEmbeddingsContent

​LogSpanFunctionContent

​LogSpanToolContent

​LogSpanGuardrailContent

​LogSpanRetrievalContent

​LogSpanOtherContent

​Example: Nested Spans

Span

Properties

Status Values

Methods

update

Parameters

log_span

Parameters

end

Span Content Types

LogSpanModelContent

LogSpanModelStreamContent

LogSpanEmbeddingsContent

LogSpanFunctionContent

LogSpanToolContent

LogSpanGuardrailContent

LogSpanRetrievalContent

LogSpanOtherContent

Example: Nested Spans