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 together and are buffered in the Monitor until flushed. Create a Trace via monitor.log_trace().

Properties

Property	Type	Description
`trace`	`CreateLogTraceRequest`	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) 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.

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`).
`"tags"`	`list[str]`	Replace the trace tags.
`"attributes"`	`dict[str, Any]`	Replace the trace attributes. Values are auto-wrapped in `LogAttributesValue`.

Returns: Trace (self, for chaining).

log_span

Creates a child Span under this trace and adds it to the monitor buffer. This is a synchronous method.

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). 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 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.

reference_id = trace.end()

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

Example

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

Get started

API

SDKs

Proxy

Trace

Trace

Properties

Status Values

Methods

update

Parameters

log_span

Parameters

end

Example

​Trace

​Properties

​Status Values

​Methods

​update

​Parameters

​log_span

​Parameters

​end

​Example

Trace

Properties

Status Values

Methods

update

Parameters

log_span

Parameters

end

Example