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

# Trace

# Trace

The Trace class represents a high-level operation in your AI application, such as a user request or workflow execution. Traces group related [spans](https://www.adaline.ai/docs/reference/sdk/v2/python/classes/span.md) together and are buffered in the Monitor until flushed.

Create a Trace via [`monitor.log_trace()`](https://www.adaline.ai/docs/reference/sdk/v2/python/classes/monitor#log_trace).

## Properties

| Property | Type | Description | |
| - | - | - | - |
| `trace` | [`CreateLogTraceRequest`](https://www.adaline.ai/docs/reference/api/v2/openapi/create-log-trace) | The underlying API payload containing the trace data. Access nested fields via `trace.trace` (e.g. `trace.trace.name`, `trace.trace.reference_id`). | |
| `trace_id` | \`str | None\` | Server-assigned trace ID, populated after the trace is flushed to the API. `None` until then. |

## Status Values

Trace status ([`TraceStatus`](https://www.adaline.ai/docs/reference/sdk/v2/python/types/TraceStatus)) must be one of: `"success"`, `"failure"`, `"aborted"`, `"cancelled"`, `"pending"`, `"unknown"`.

## Methods

### update

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

```python theme={null}
trace.update({
    "status": "success",
    "tags": ["completed", "v2"],
    "attributes": {"total_tokens": 1500, "model": "gpt-4"}
})

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

#### Parameters

**updates** `dict` *required*

Dictionary of fields to update.

| Key | Type | Description |
| - | - | - |
| `"name"` | `str` | Update the trace display name. |
| `"status"` | `str` | Update the trace status ([`TraceStatus`](https://www.adaline.ai/docs/reference/sdk/v2/python/types/TraceStatus)). |
| `"tags"` | `list[str]` | Replace the trace tags. |
| `"attributes"` | `dict[str, Any]` | Replace the trace attributes. Values are auto-wrapped in [`LogAttributesValue`](https://www.adaline.ai/docs/reference/sdk/v2/python/types/LogAttributesValue). |

**Returns:** `Trace` (self, for chaining).

***

### log\_span

Creates a child [Span](https://www.adaline.ai/docs/reference/sdk/v2/python/classes/span.md) under this trace and adds it to the monitor buffer. This is a synchronous method.

```python theme={null}
span = trace.log_span(
    name="OpenAI GPT-4 Call",
    status="unknown",
    reference_id=None,
    prompt_id="prompt-123",
    deployment_id="deployment-456",
    run_evaluation=True,
    tags=["llm", "gpt-4"],
    attributes={"temperature": 0.7},
    content=None
)
```

#### Parameters

**name** `str` *required*

Display name for the span.

**status** `str` (default: unknown)

Span status ([`SpanStatus`](https://www.adaline.ai/docs/reference/sdk/v2/python/types/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.

**tags** `list[str] | None`

Optional list of string tags.

**attributes** `dict[str, Any] | None`

Optional key-value metadata. Values are wrapped in [`LogAttributesValue`](https://www.adaline.ai/docs/reference/sdk/v2/python/types/LogAttributesValue) automatically.

**content** `LogSpanContent | None`

Span content payload ([`LogSpanContent`](https://www.adaline.ai/docs/reference/sdk/v2/python/types/LogSpanContent)). Falls back to the monitor's `default_content` if not provided.

**Returns:** A new [Span](https://www.adaline.ai/docs/reference/sdk/v2/python/classes/span.md) instance.

***

### end

Marks the trace as complete and ready for flushing. Automatically ends all child spans belonging to this trace. Idempotent: subsequent calls return the reference ID without side effects.

```python theme={null}
reference_id = trace.end()
```

**Returns:** `str | None` — the trace's `reference_id`.

## Example

```python theme={null}
trace = monitor.log_trace(
    name="User Question",
    session_id="session-abc",
    tags=["chat"]
)

retrieval_span = trace.log_span(name="Document Retrieval")
# ... perform retrieval ...
retrieval_span.update({"status": "success"})
retrieval_span.end()

llm_span = trace.log_span(
    name="LLM Generation",
    prompt_id="prompt-123",
    deployment_id="deploy-456",
    run_evaluation=True
)
# ... call LLM ...
llm_span.update({"status": "success"})
# No need to call llm_span.end() — trace.end() handles it

trace.update({"status": "success"})
ref_id = trace.end()  # auto-ends llm_span
```


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