Agentic Data Plane

rpk ai trace list

List traces of agent runs and AI gateway calls, newest first unless --order-by says otherwise.

The filter flags build ListTraces' AIP-160 filter: values within one flag are ORed, different flags are ANDed, and --filter is ANDed with all of them. The server allows one constraint per field, so --filter must not repeat a field a flag already sets. --since is required and the window is at most 30 days, so no listing reads all of history.

--limit caps the traces printed (default 50, at most 1000), read in pages of up to 100. -o json and -o yaml print the ListTracesResponse.

This command was introduced in ai version 0.2.94.

Usage

rpk ai trace list [flags]

Examples

This section provides examples of how to use rpk ai trace list.

Failed runs and runs with a failed tool call in the last day

rpk ai trace list --since 24h --errors

One agent’s running traces

rpk ai trace list --since 24h --agent support --status running

Most expensive traces this week

rpk ai trace list --since 7d --order-by "usage.cost.total_microcents desc" --limit 10

Flags

Value Type Description

--agent

string

agent name or uid. (New in 0.2.100)

--conversation

string

conversation id. (New in 0.2.100)

--errors

bool

failed runs and runs with a failed tool call. (New in 0.2.100)

--filter

string

raw AIP-160 filter, ANDed with the flags above.

--limit

int

maximum traces to print, 1 to 1000. (New in 0.2.100)

--order-by

string

AIP-132 order_by, for example, duration desc.

--since

string

traces started at or after, as RFC 3339 or a duration ago (15m, 24h, 7d); required and at most 30d before --until. (New in 0.2.100)

--status

strings

running, completed, error or incomplete (repeatable). (New in 0.2.100)

--until

string

traces started before: RFC 3339 or a duration ago. (New in 0.2.100)

--user

strings

caller email or end-user id (repeatable). (New in 0.2.100)

Global flags

Value Type Description

--config

string

Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml.

-X, --config-opt

stringArray

Override rpk configuration settings; -X help for detail or -X list for terser detail.

--ignore-profile

bool

Ignore rpk.yaml and redpanda.yaml; use default settings.

--profile

string

rpk profile to use.

-v, --verbose

bool

Enable verbose logging.