Skip to content
Metrana Docs

Agentic traces

A trace is one complete agent invocation — in post-training, one rollout. It is stored as spans: the trace itself is span 0, the root, and every other span hangs off it. Spans are anchored to a run, or to the project alone for inference traces, and that anchor is what every list is scoped by: a run’s spans live on one shard, keyed by (root or not, op_name, step), which is what filtering on those narrows by.

The read path: ListSpans finds traces (root spans) or spans by name, step, outcome and attributes; ListTraceSpans reads one trace’s tree; GetSpanPayload reads one body a window at a time.

ListTracingAttributeDefinitions

Section titled “ListTracingAttributeDefinitions”

Discovers the attribute definitions logged on spans, across a run or the project’s own spans.

ListTracingAttributeDefinitionsRequest

Section titled “ListTracingAttributeDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run optional string If set, attributes logged on the run’s spans; if unset, on the project’s own (inference) spans.
attr_filter attrFilter ListAttrFilter Controls which attributes are included in the response. If unset, all attributes are returned.
limit limit optional int64 How many attributes to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified.
resume_token resumeToken optional string If specified, resumes from last request. Other params must still be included in the request.

ListTracingAttributeDefinitionsResponse

Section titled “ListTracingAttributeDefinitionsResponse”
Field JSON Type Description
attribute_defs attributeDefs repeated AttributeDef
resume_token resumeToken optional string Optional resume token if more results are there

ListTracingOpNames

Section titled “ListTracingOpNames”

Discovers the operation names logged on spans — the values attr(op_name) takes — across a run or the project’s own spans.

ListTracingOpNamesRequest

Section titled “ListTracingOpNamesRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run optional string If set, names on the run’s spans; if unset, on the project’s own (inference) spans.
include_children includeChildren bool Unset: the names of traces (root spans) only. Set: those and the names of the spans below them.
limit limit optional int64 1..10000; the server applies a default when unset.
resume_token resumeToken optional string If specified, resumes from last request. Other params must still be included in the request.

ListTracingOpNamesResponse

Section titled “ListTracingOpNamesResponse”
Field JSON Type Description
op_names opNames repeated TracingOpName Distinct names, ascending.
resume_token resumeToken optional string Optional resume token if more results are there

ListSpans

Section titled “ListSpans”

Searches spans — or only traces, i.e. root spans — of a run or a project, with a filter and an ordering over the span’s own fields and its logged attributes. See resource filter format and resource order by format.

ListSpansRequest

Section titled “ListSpansRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
runs runs repeated string The runs whose spans to search, at most 10; empty searches the project’s own (inference) spans. Each run is searched on its own and the pages merge into one ordering, so across several runs limit + offset may not exceed 1000 and order_by names a span field, not a logged attribute.
include_children includeChildren bool Unset: traces (root spans) only, the trace list. Set: every span, roots included, and then filter must name the ops: attr(op_name) == “…” or attr(op_name) IN […] as a top-level AND term. Storage is keyed by op name, so a search either stays within the roots or within named ops; it never walks every op.
filter filter optional string See resource filter format. Supports the span’s logged attributes via attr(<path>) and these reserved special fields, backed by the span’s own columns (users cannot log span attributes under these names, so there is no ambiguity):
• attr(op_name) (string)
• attr(step) (integer)
• attr(status) (string: RUNNING, OK, ERROR, TRUNCATED, CANCELLED)
• attr(kind) (string: THOUGHT, ITERATION, LLM_CALL, TOOL_CALL, SUB_AGENT, ARTIFACT, FUNCTION)
• attr(start_time), attr(end_time) (timestamp)
• attr(duration_ms) (integer)
• attr(token_count) (integer)
• attr(span_count), attr(iteration_count) (integer; root only)
Narrowing on attr(op_name) and attr(step) is what the storage is keyed for; prefer it to paging deeply. attr(start_time) is applied before grouping too, but scans the whole key range; express a time window as attr(step) bounds where possible. Required to name the ops when include_children is set (see there).
order_by orderBy optional string See resource order by format. Same attributes and special fields as filter. Default: attr(step) DESC, then newest trace first, then span id.
limit limit optional int64 0..1000; the server applies a default when unset.
offset offset optional int64 Spans to skip. Must be >= 0.
attribute_names attributeNames repeated string Attributes to return on each span. Span attributes are flat names, not a tree.

ListSpansResponse

Section titled “ListSpansResponse”
Field JSON Type Description
spans spans repeated Span
total_count totalCount int64 Spans matching the filter, before limit and offset.

ListTracingAttributeValues

Section titled “ListTracingAttributeValues”

The distinct values one attribute takes on the spans a ListSpans search would return: the session ids under an agent, the models a tier was served by. A search with the same filter returns one span per value occurrence; this returns each value once.

ListTracingAttributeValuesRequest

Section titled “ListTracingAttributeValuesRequest”

The spans searched are exactly those ListSpansRequest with the same runs, include_children and filter would return; see there for every field’s rules. Of those spans, the ones that logged attribute_name contribute their value, and each distinct value comes back once.

Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
runs runs repeated string As in ListSpansRequest: at most 10 runs, each searched on its own and the values united; empty searches the project’s own (inference) spans.
include_children includeChildren bool As in ListSpansRequest: unset searches traces (root spans) only; set, every span, and then filter must name the ops.
filter filter optional string As in ListSpansRequest.
attribute_name attributeName string The logged attribute whose values to list. Its type is the one it was logged with; a name never logged under the owner yields no values.
limit limit optional int64 0..1000; the server applies a default when unset. Values are ordered ascending by their value, so a page is stable across requests.
offset offset optional int64 Values to skip. Must be >= 0.

ListTracingAttributeValuesResponse

Section titled “ListTracingAttributeValuesResponse”
Field JSON Type Description
values values repeated Attribute Each distinct value once, ascending, as an attribute whose path is the request’s attribute_name.
total_count totalCount int64 Distinct values matching, before limit and offset. Across several runs the count is exact while every run’s values fit its first 1000; past that a value two runs share cannot be told apart and the runs’ counts are summed, an upper bound.

ListTraceSpans

Section titled “ListTraceSpans”

Every span of one trace, ordered for tree assembly. A span’s children are those naming it as parent; parent_span_id 0 means the root.

ListTraceSpansRequest

Section titled “ListTraceSpansRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run optional string The run the trace is anchored to; unset for a trace anchored to the project alone. The trace’s rows are stored by it, so it is stated rather than searched for.
trace_id traceId string From ListSpans.
limit limit optional int64 0..10000; the server applies a default when unset.
offset offset optional int64
attribute_names attributeNames repeated string Attributes to return on each span. Span attributes are flat names, not a tree.

ListTraceSpansResponse

Section titled “ListTraceSpansResponse”
Field JSON Type Description
spans spans repeated Span Ordered by span id, root first, which is also creation order within the trace.
total_count totalCount int64 Spans in the trace, before limit and offset.

GetSpanPayload

Section titled “GetSpanPayload”

One span payload — a body, or the span’s attributes as JSON — read a window of it at a time.

GetSpanPayloadRequest

Section titled “GetSpanPayloadRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
trace_id traceId string From ListSpans.
span_ids spanIds repeated uint64 The spans whose payloads to read, 1 to 100 of them; duplicates are ignored. 0 asks for the root’s payloads — the task input, the final output and the trace’s own attributes.
run run optional string The run the trace is anchored to; unset for a trace anchored to the project alone. Every span is checked to exist under it before any payload is read; if one does not, nothing is returned.
payload_kinds payloadKinds repeated TracePayloadKind Which payloads to read. Empty means every kind the spans logged.
max_data_length maxDataLength optional uint32 Payloads are read as one window over the spans’ payloads ordered by (span id, kind, offset), budgeted in bytes of body for every span and kind — an attribute costs its JSON entry. At most this many bytes come back per response (1 MiB by default, 16 MiB at most), rounded up to one whole character of text or one attribute when the budget would otherwise end a window empty. One large payload can fill a window, and the spans after it follow in later ones. A chunk not ingested yet ends the window, spans after it included.
resume_token resumeToken optional string Continues an earlier response from where its window ended. Every other field must be the same as in that request.

GetSpanPayloadResponse

Section titled “GetSpanPayloadResponse”
Field JSON Type Description
payloads payloads repeated SpanPayloadPart In (span id, kind, offset) order; a span’s kind appears at most once per response, and not at all once an earlier window returned all of it.
returned_data_length returnedDataLength uint32 Bytes returned across payloads, in the same measure as max_data_length.
resume_token resumeToken optional string Set when more follows: a kind’s remaining chunks, chunks not ingested yet, or further kinds.