> ## 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](/docs/reference/sdk/v2/python/classes/span) together and are buffered in the Monitor until flushed.

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

## Properties

| Property   | Type                                                                  | Description                                                                                                                                         |                                                                                               |
| ---------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `trace`    | [`CreateLogTraceRequest`](/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`](/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

<ParamField body="updates" type="dict" required>
  Dictionary of fields to update.

  | Key            | Type             | Description                                                                                                                         |
  | -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
  | `"name"`       | `str`            | Update the trace display name.                                                                                                      |
  | `"status"`     | `str`            | Update the trace status ([`TraceStatus`](/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`](/docs/reference/sdk/v2/python/types/LogAttributesValue). |
</ParamField>

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

***

### log\_span

Creates a child [Span](/docs/reference/sdk/v2/python/classes/span) 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

<ParamField body="name" type="str" required>
  Display name for the span.
</ParamField>

<ParamField body="status" type="str" optional default="unknown">
  Span status ([`SpanStatus`](/docs/reference/sdk/v2/python/types/SpanStatus)). One of: `"success"`, `"failure"`, `"aborted"`, `"cancelled"`, `"unknown"`.
</ParamField>

<ParamField body="reference_id" type="str | None" optional>
  Client-side unique identifier. If omitted, a UUID is auto-generated.
</ParamField>

<ParamField body="prompt_id" type="str | None" optional>
  Prompt identifier to associate with this span.
</ParamField>

<ParamField body="deployment_id" type="str | None" optional>
  Deployment identifier to associate with this span.
</ParamField>

<ParamField body="run_evaluation" type="bool | None" optional>
  Whether to run evaluation on this span.
</ParamField>

<ParamField body="tags" type="list[str] | None" optional>
  Optional list of string tags.
</ParamField>

<ParamField body="attributes" type="dict[str, Any] | None" optional>
  Optional key-value metadata. Values are wrapped in [`LogAttributesValue`](/docs/reference/sdk/v2/python/types/LogAttributesValue) automatically.
</ParamField>

<ParamField body="content" type="LogSpanContent | None" optional>
  Span content payload ([`LogSpanContent`](/docs/reference/sdk/v2/python/types/LogSpanContent)). Falls back to the monitor's `default_content` if not provided.
</ParamField>

**Returns:** A new [Span](/docs/reference/sdk/v2/python/classes/span) 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
```