monitor

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 17, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

The ack vocabulary (v0.5 W4.6) — the two argument names mast fills in when it forwards an operator's acknowledgement.

They live here, beside the transition records, because they are the same contract read backwards. A cycle learns a subject's key from the producer's classification and hands it to the model and the chat; an ack arrives naming one of those keys and goes back to the producer. mast never parses the key in either direction — see Transition.

So these are not k8s spellings and are not lookout's to change unilaterally: they are the monitor contract's, and the k8s-shaped arguments (cluster, namespace, how long a suppression lasts) stay where domain facts have always gone, in the bundle's args map.

Package monitor carries what an unattended monitoring cycle learned between one run and the next (v0.5 W4.4).

What this package deliberately does not know

It does not know what a transition MEANS. The tool that classified the run — `k8s_findings_diff` for a Kubernetes workload, anything with the same output contract for anything else — owns that vocabulary, and mast passes its answer through verbatim. There is no enum here, no `const TransitionEscalated`, no comparison of two severities to decide whether something got worse, and no fingerprinting to decide whether two findings are the same subject. Every one of those would be a second source of truth for a question something else already answered, and the second source is the one that will disagree at 3am.

The rule to apply when extending this package: mast may check that a record is WELL FORMED, and may not check that it is RIGHT. A missing subject key is malformed — nothing downstream can ack or de-duplicate a subject it cannot name. A transition class mast has never seen is not malformed; it is lookout shipping a new class, and it rides through untouched.

The wire contract

One record per line, either logfmt or a flat JSON object, detected per line — the same leniency lookout's own `--report` reader offers, for the same reason: the producer's `format` is a caller's choice and a consumer that only speaks one of them fails on a config change it has no part in.

The stream is terminated by a mandatory summary line carrying `scanned=<n> findings=<n>`. A result without one is VOID and is an error here, not an empty set. That distinction is the whole reason the summary exists: a truncated read, a killed process or a half written pipe all produce a prefix of a healthy answer, and a prefix of "nothing changed" is indistinguishable from "nothing changed" unless somebody insists on the terminator. `findings=<n>` is checked against the records actually parsed for the same reason — the count comes from the producer's own writer and cannot drift from what it emitted, so a disagreement means bytes went missing in transit.

Index

Constants

View Source
const (
	// AckSubjectArg is the argument carrying WHAT was acked: the
	// producer's own subject key, verbatim from the classification.
	AckSubjectArg = "subject_key"

	// AckByArg is the argument carrying WHO acked. mast fills it from
	// the authenticated caller and from nowhere else — never from the
	// request body, and never from the bundle, both of which are
	// attributions a caller writes about itself.
	AckByArg = "ack_by"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Set

type Set struct {
	// Transitions are the records, in the order the producer emitted
	// them. Order is preserved rather than sorted: the producer chose
	// it, and a notifier that re-orders is inventing an emphasis.
	//
	// Serialized as `records` because the field this Set lands in is
	// itself called `transitions` in the wake-up envelope, and
	// `transitions.transitions` reads like a mistake. Never omitted:
	// an explicit empty list is "we classified and nothing changed",
	// and a missing key is "we do not know", which are the two answers
	// a monitor most needs to keep apart.
	Transitions []Transition `json:"records"`

	// Scanned is the summary's `scanned=` — the subjects considered,
	// which is almost always much larger than the transitions. It is
	// the difference between "quiet" and "not looking": a cycle with
	// zero transitions and 400 scanned is healthy, and a cycle with
	// zero of both is a monitor that has stopped monitoring.
	Scanned int `json:"scanned"`
}

Set is one cycle's classification: what changed, and how much was looked at to find out.

func Parse

func Parse(output string) (Set, error)

Parse reads a record stream into a Set. See the package doc for the contract; the errors below are all "the bytes are not a whole answer", never "the answer is wrong".

func ParseResult

func ParseResult(result map[string]any) (Set, error)

ParseResult reads a transition set out of a tool result as mast's direct-run seam returns it.

The `output` key is ADK's, not the producer's: its MCP tool adapter files a server's text content under that name (and a server's structured content under the same one). A tool that answers with structured content instead of the line contract is an error rather than something to coerce — the contract is a stream of records with a terminator, and a JSON blob shaped some other way is a different tool than the one the bundle meant to name.

func (Set) Classes

func (s Set) Classes() []string

Classes tallies the set by class as `<class>=<n>`, sorted by class so the rendering is stable between cycles.

Built from the classes actually present rather than from a list mast keeps: a tally that enumerated a vocabulary would silently drop the first record of a class lookout added after this was written, which is precisely the failure this package is arranged to make impossible.

func (Set) Empty

func (s Set) Empty() bool

Empty reports whether nothing changed. Note that this is not the same question as "did the cycle work" — see Scanned.

type Transition

type Transition struct {
	// SubjectKey is the producer's instance-grain key for the thing
	// that changed. mast treats it as an opaque identifier: it is what
	// an ack is keyed by (W4.6) and what two cycles are joined on, and
	// nothing here parses its internal structure.
	SubjectKey string `json:"subject_key"`

	// Class is the transition class, verbatim as the classifying tool
	// wrote it — `new`, `ongoing`, `escalated`, `resolved`,
	// `suppressed` in lookout's current vocabulary, and whatever it
	// adds next without a change here.
	//
	// Named Class rather than Transition to keep call sites readable;
	// the JSON tag is the producer's own spelling, because the envelope
	// the model reads should say what lookout says.
	Class string `json:"transition"`

	// Fields is every other key on the record, unread. severity,
	// prev_severity, first_seen, message, the lot — carried so the
	// model and the notifier have the full record, and deliberately not
	// promoted to typed fields, because typing them here is how a
	// consumer starts having opinions about them.
	Fields map[string]string `json:"fields,omitempty"`
}

Transition is one subject's change since the previous run.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL