ViewerService
ViewerService serves an invocation's captured output to a log viewer, resource-oriented per AIP: Get the Invocation (the run header), List its Events (paginated), Stream them (live). The offline URL-fragment path instead carries a whole Journal directly (no server).
Package magus.viewer.v1, defined in proto/magus/viewer/v1/viewer.proto. Part of the daemon API.
Methods
GetInvocation
GetInvocation returns an invocation's header: its command, lineage, and timing - what a viewer shows on top. Selected by a ref (one target) or an invocation id (a run).
POST /magus.viewer.v1.ViewerService/GetInvocation - unary.
Takes GetInvocationRequest, returns GetInvocationResponse.
ListEvents
ListEvents returns a page of an invocation's events; page through with page_token until next_page_token is empty. filter narrows them server-side (large logs).
POST /magus.viewer.v1.ViewerService/ListEvents - unary.
Takes ListEventsRequest, returns ListEventsResponse.
StreamEvents
StreamEvents streams a running invocation's events as they are produced. Reconnect with start_time set to the last seen time to resume.
POST /magus.viewer.v1.ViewerService/StreamEvents - server streaming.
Takes StreamEventsRequest, returns StreamEventsResponse.
Messages
StringMatch
StringMatch is one negatable string comparison against whatever field the composing message names it for. negate inverts the match (a leading "-" in the DSL). Matching is case-insensitive; multiple matches on one field AND together.
| Field | Type | # | Description |
|---|---|---|---|
value |
string | 1 | |
negate |
bool | 2 |
TimeRange
TimeRange bounds a query to items between since and until (inclusive); either bound may be unset for an open-ended range. since doubles as a live-stream resume cursor.
| Field | Type | # | Description |
|---|---|---|---|
since |
Timestamp | 1 | |
until |
Timestamp | 2 |
Command
Command is the invoking command line and context - what was asked of magus.
| Field | Type | # | Description |
|---|---|---|---|
arguments |
repeated string | 1 | the full argument vector, subcommand included (e.g. ["run", "build", "api"]) |
cwd |
string | 3 | directory the command was invoked in |
trigger |
Trigger | 4 |
Event
Event is one line of a structured invocation log - the atom of the stream. Most events are output or result; the first event of an invocation is KIND_STARTED and carries the command + magus_version (the run's identity), which every other event leaves unset.
| Field | Type | # | Description |
|---|---|---|---|
time |
Timestamp | 1 | when the event occurred |
project |
string | 2 | repo-relative project path |
target |
string | 3 | target name, as the CLI spells it (with charms) |
kind |
Kind | 4 | |
stream |
Stream | 5 | output events only |
level |
string | 6 | info|warn|error, for magus events |
status |
Status | 7 | result events only |
ref |
string | 8 | target-output ref, on result events |
duration |
Duration | 9 | how long the target ran, on result events |
text |
string | 10 | output line or message (raw; may contain ANSI) |
command |
Command | 11 | set only on the KIND_STARTED event |
magus_version |
string | 12 | set only on the KIND_STARTED event |
EventQuery
EventQuery filters an invocation's events server-side (for a large log). It is the viewer's OWN typed query, composed from the shared query primitives plus the viewer's event fields - log fields (target/stream/level) are not graph fields, so there is no generic shared Query. Set fields AND together; repeated values within a field OR; matching is case-insensitive. The time window (including its since resume cursor) lives here too, so one message carries the whole filter.
| Field | Type | # | Description |
|---|---|---|---|
projects |
repeated string | 1 | repo-relative project paths |
targets |
repeated string | 2 | target names |
kinds |
repeated string | 3 | event kinds: output|result|exec|scope|warn|... |
streams |
repeated string | 4 | stdout|stderr, for output events |
levels |
repeated string | 5 | info|warn|error |
status |
string | 6 | pass|fail|cached, for result events |
text |
repeated StringMatch | 7 | free-text matches against an event's text |
time |
TimeRange | 8 | event time window; since doubles as stream resume |
GetInvocationRequest
| Field | Type | # | Description |
|---|---|---|---|
selector |
Selector | 1 |
GetInvocationResponse
| Field | Type | # | Description |
|---|---|---|---|
invocation |
Invocation | 1 |
Invocation
Invocation is one magus command, launch to exit - the thing that produces a Journal of Events. It is a projection of the stream's lifecycle events (KIND_STARTED supplies the command + start; KIND_FINISHED supplies the end), offered as a parsed header so a viewer need not dig through the events for the command.
| Field | Type | # | Description |
|---|---|---|---|
id |
string | 1 | |
command |
Command | 2 | |
start_time |
Timestamp | 3 | |
end_time |
Timestamp | 4 | unset while still running |
magus_version |
string | 5 |
ListEventsRequest
| Field | Type | # | Description |
|---|---|---|---|
selector |
Selector | 1 | |
page_size |
int32 | 2 | |
page_token |
string | 3 | |
filter |
EventQuery | 4 | viewer-typed content + time filter |
ListEventsResponse
| Field | Type | # | Description |
|---|---|---|---|
events |
repeated Event | 1 | |
next_page_token |
string | 2 | set when more events remain |
Selector
Selector picks a run: one target's execution (ref) or a whole invocation.
| Field | Type | # | Description |
|---|---|---|---|
ref |
string | 1 | one of of |
invocation |
string | 2 | one of of |
StreamEventsRequest
| Field | Type | # | Description |
|---|---|---|---|
invocation |
string | 1 | |
filter |
EventQuery | 2 | viewer-typed content filter; filter.time.since resumes the stream |
StreamEventsResponse
| Field | Type | # | Description |
|---|---|---|---|
event |
Event | 1 |
Enums
Kind
Kind classifies an Event. Output events carry subprocess text; the rest carry magus's own structural events.
| Value | # | Description |
|---|---|---|
KIND_UNSPECIFIED |
0 | |
KIND_STARTED |
7 | Lifecycle events bracket the invocation: STARTED opens it (carries the command lineage + version), FINISHED closes it (carries the overall pass/fail outcome). |
KIND_FINISHED |
8 | |
KIND_EXEC |
9 | Content events, produced between the lifecycle pair. a subprocess is about to run: the command line (groups the output below it) |
KIND_OUTPUT |
1 | a subprocess stdout/stderr line |
KIND_RESULT |
2 | a target finished (pass/fail/cached), with its ref + duration |
KIND_SCOPE |
4 | the run's project scope header |
KIND_WARN |
6 | a magus warning |
KIND_SECRET |
10 | A credential was READ: the reference and the provider that served it, never the value. Distinct from WARN because it is not a problem - it is the record that a build reached for something privileged, which is what an audit answers for. |
Status
Status is a result event's outcome.
| Value | # | Description |
|---|---|---|
STATUS_UNSPECIFIED |
0 | |
STATUS_PASS |
1 | |
STATUS_FAIL |
2 | |
STATUS_CACHED |
3 |
Stream
Stream identifies which pipe an output event came from.
| Value | # | Description |
|---|---|---|
STREAM_UNSPECIFIED |
0 | |
STREAM_STDOUT |
1 | |
STREAM_STDERR |
2 |
Trigger
Trigger is how an invocation was spawned - the lineage a viewer surfaces ("this failure came from magus affected ci").