Runtime tools

Operation events of the running system and the trace level of an element. This group has 6 tools.

Tool	Edition	Summary
get_trace	Open core	Effective trace level of an element on a host and its origin (own, inherited from an ancestor id, or methodology default).
query_runtime	Open core	Operation events of an element and all its descendants (the whole project without element), oldest to newest, in pages: pass next_cursor back as cursor for…
run_transcript_get	Open core	The recorder’s jsonl transcript records of one run, by part (system|user|response|tools|all, default all).
set_trace	Open core	Set the trace level of an element on a host.
summarize_runtime	Open core	Event counts per time bin and level, computed by the event store (no raw events), for an element and its descendants or the whole system.
trace_run	Open core	Every operation event of one run_id from the project event store, oldest first.

get_trace

Effective trace level of an element on a host and its origin (own, inherited from an ancestor id, or methodology default).

Parameters

Parameter	Type	Required	Description
element	string	yes	Element id.
host	string	yes	Host name.
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)

query_runtime

Operation events of an element and all its descendants (the whole project without element), oldest to newest, in pages: pass next_cursor back as cursor for the next older page. Filter by level (at least that severe) and a since/until time window.

Parameters

Parameter	Type	Required	Description
cursor	integer	no	next_cursor of the previous page.
element	string	no	Element id; its descendants are included.
event	string	no	Filter to one event name.
exclude_events	array of string	no	Event names to leave out, applied before paging; pass again with cursor.
level	string, one of error, warn, info, debug, trace	no	Keep events at least this severe.
limit	integer	no	Page size (default 200, max 2000).
operation	string	no	Filter to one operation.
outcome	string	no	Filter to one outcome.
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)
run_id	string	no	Filter to one run id.
signature	string	no	Filter to one warning/error log signature.
since	string	no	ISO time, inclusive lower bound.
until	string	no	ISO time, inclusive upper bound.

run_transcript_get

The recorder’s jsonl transcript records of one run, by part (system|user|response|tools|all, default all). Truncation markers are kept; falls back to trace_run when the transcript file is gone. Read-only.

Parameters

Parameter	Type	Required	Description
part	string, one of system, user, response, tools, all	no
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)
run_id	string	yes	Run id to fetch.

set_trace

Set the trace level of an element on a host. debug/trace require ttl (seconds).

Parameters

Parameter	Type	Required	Description
element	string	yes	Element id.
host	string	yes	Host name.
level	string, one of error, warn, info, debug, trace	yes
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)
ttl	number	no	Seconds; required for debug/trace.

summarize_runtime

Event counts per time bin and level, computed by the event store (no raw events), for an element and its descendants or the whole system.

Parameters

Parameter	Type	Required	Description
bin_seconds	integer	no	Bin width in seconds (default 60).
element	string	no	Element id; its descendants are included.
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)
run_id	string	no	Filter to one run id.
since	string	no	ISO time, inclusive lower bound.
until	string	no	ISO time, inclusive upper bound.

trace_run

Every operation event of one run_id from the project event store, oldest first. run_id is required.

Parameters

Parameter	Type	Required	Description
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)
run_id	string	yes	Run id to fetch.