From d4eea233229e2d920850bd2cee5d6c44bf62941f Mon Sep 17 00:00:00 2001 From: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:03:36 -0800 Subject: [PATCH 1/2] Document the V1 commands, flags and exit rules Signed-off-by: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com> --- README.md | 107 ++++++++++++++++++------ docs/cli.md | 191 ++++++++++++++++++++++++++----------------- example.config.yaml | 17 ++-- example.overlay.yaml | 13 +++ 4 files changed, 219 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 3e546e9..c7aa6cc 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ What Vigil does: - Combines the verdicts of named **authorities** (Simplex today, Augur once its Vigil fields land) into one `overall` severity. Vigil re-derives nothing: an authority owns its rules, Vigil owns the combination. -- Queries named **backends** (Prometheus, Grafana health) through names in its +- Queries named **backends** (Prometheus, Grafana) through names in its config. No command or route takes a URL, a selector or PromQL. - Accepts ephemeral **signals** from authenticated callers. A signal is information, never a verdict. @@ -23,10 +23,10 @@ Augur ──verdict document (file)──────▶ Vigil ◀──vigi prom (lathe) · grafana (lathe) ──named──▶ Cubit / Scry ──▶ informational blocks ``` -## Reading a summary +## Reading a summary (V2) -The document is a single JSON object with an `apiVersion`. Consumers refuse an -unknown major version; fields are additive within `v0`. +The summary document is a single JSON object with an `apiVersion`. Consumers +refuse an unknown major version; fields are additive within `v0`. - `overall` is the worst severity among the readable verdicts in `verdicts[]`, after two caps and nothing else. Stale cap: a stale verdict @@ -63,19 +63,35 @@ Two presentation rules hold everywhere (CLI table, Facet, agents): ## Commands -| Command | Since | What it does | +| Command | Pack | What it does | | --- | --- | --- | | `vigil version` | V0 | version, commit, Go runtime | -| `vigil prom targets` | V1 | scrape targets of the named prom backend: slug, health, last scrape only | +| `vigil prom targets` | V1 | scrape targets of the named prom backend | | `vigil prom query ` | V1 | run a named query from config; host slug is the only variable | | `vigil grafana health` | V1 | health of the named grafana backend; never gates `overall` | -| `vigil sources` | V1 | configured authorities, backends and informational sources with their reachability | -| `vigil simplex summary` | V2 | build `vigil.summary/v0`; human table, or the document alone with `--json` | -| `vigil serve` | V3 | loopback HTTP listener for the same document | +| `vigil sources` | V1 | one row per configured backend with its reachability | +| `vigil serve` | V3 | loopback HTTP listener for the summary document | -Every command: `--json` prints the document alone on stdout; errors are one -JSON line on stderr (`vigil.error/v0` with a stable `code`). `--now` pins the -clock for tests. Details in [docs/cli.md](docs/cli.md). +## Flags + +| Flag | Commands | Meaning | +| --- | --- | --- | +| `--config PATH` | all | path to the vigil.config/v0 file | +| `--overlay PATH` | all | path to the vigil.overlay/v0 file (backend addresses) | +| `--json` | all | print the document alone on stdout | +| `--now RFC 3339` | all | pin the clock; used by tests and deterministic renders | +| `--host SLUG` | `prom query` | host slug for the `{{.host}}` placeholder | + +`--help` text is taken from the binary; see [docs/cli.md](docs/cli.md). + +## Output contract + +Every command renders the same document two ways: the human table (default) +and the document alone with `--json`. `--json` is one line and byte-stable — +the same document always produces the same bytes. A failure prints one +`vigil.error/v0` JSON line on stderr and nothing on stdout. A table never +prints a field the document lacks; a value the document carries as null or +absent renders as a dash. ## Exit codes @@ -94,11 +110,46 @@ Vigil's own. | 5 | auth, startup or bind failure | | 6 | internal error (panic recovered) | +For the V1 backend commands, the mapping per command: + +| Command | 0 | 3 | 4 | +| --- | --- | --- | --- | +| `prom targets` | answered | usage or config | unreachable, HTTP error, body cap, timeout | +| `prom query` | answered | usage, config, or a rejected query (`query_rejected`, `missing_host`, `unexpected_host`) | unreachable, `series_cap`, `query_warnings`, timeout, body cap | +| `grafana health` | healthy (`database: ok`) | usage or config | unhealthy or unreachable (`not_health`, `http_status`, timeout) | +| `sources` | rendered — row states are data | usage or config | never | + +Two query rules sit on exit 3: the config's `{{.host}}` placeholder needs +`--host` (`missing_host`), and `--host` is refused when the expr has no +placeholder (`unexpected_host`) — neither fans out to the backend. An empty +query result is exit 0 with `series: []`, not an error. A wildcard `listen` +in the config is exit 5 for every command. + +## Backend command rules (V1) + +- `prom targets` publishes only what may be published: the mapped host slug, + the job, the health word and the last scrape. An instance the overlay + cannot map prints as `unmapped`; a job without a publishable shape prints + as `redacted`. A scrape URL, a last error or discovered labels never reach + the output. +- `prom query` runs exactly one named query from the config. The host slug is + the only template variable and `--host` must be a mapped or public slug. + The request asks for one series more than the cap, so more results fail + with `series_cap` instead of a truncated answer; any backend warning fails + with `query_warnings` instead of a partial answer. Every result carries the + backend and the vantage that answered, and Vigil never fails over silently. +- `grafana health` is healthy only on a 200 whose body says the database is + ok; a login page or any other non-health body is `not_health`. It is a + source, never a verdict: when it is unhealthy the command exits 4 with no + stdout and nothing else moves. +- `sources` renders rows; a down backend is a row state, never a command + failure. + ## Security model - The listener binds `127.0.0.1:10082` by default. A wildcard address is - rejected in every spelling; a non-loopback bind needs an explicit flag and - one explicit address. A bracketed IPv6 `listen` value must be quoted in + rejected in every spelling; a non-loopback bind needs `--allow-nonloopback` + and one explicit address. A bracketed IPv6 `listen` value must be quoted in YAML: `listen: "[::1]:10082"`. - A read token (`VIGIL_READ_TOKEN_FILE`) is required on every `/v0/*` route on any bind, so a proxy in front of loopback cannot bypass it. A separate @@ -112,23 +163,31 @@ Vigil's own. ## Configuration `example.config.yaml` is a valid starting point: slugs only, token paths by -environment reference. Backend addresses live in an overlay -(`example.overlay.yaml` is the tracked example; a real overlay is never -committed). Both examples validate against the JSON Schemas under `schema/`. - -With one authority and no cap in play, `overall` is that authority's -published severity; a stale GREEN gives YELLOW. Adding a configured -authority can keep `overall` or make it worse, never better. +environment reference, and an optional `vantage` label on the prom backend. +Backend addresses live in an overlay (`example.overlay.yaml` is the tracked +example; a real overlay is never committed); the overlay's `hosts[]` maps the +instance labels a backend reports onto public slugs. Both examples validate +against the JSON Schemas under `schema/`. + +`overall` is the worst severity among the readable verdicts in `verdicts[]`, +after two caps and nothing else; with one authority and no cap in play, +`overall` is that authority's published severity, and a stale GREEN gives +YELLOW. Adding a configured authority can keep `overall` or make it worse, +never better. Vigil adds no second opinion of its own. ## Documents | Document | File | Role | | --- | --- | --- | -| `vigil.summary/v0` | `schema/vigil.summary.v0.schema.json` | the single produced document | -| `vigil.signal/v0` | `schema/vigil.signal.v0.schema.json` | ephemeral, authenticated POST only | +| `vigil.summary/v0` | `schema/vigil.summary.v0.schema.json` | the single produced document (V2) | +| `vigil.sources/v0` | `schema/vigil.sources.v0.schema.json` | one row per configured backend | +| `vigil.targets/v0` | `schema/vigil.targets.v0.schema.json` | the prom backend's scrape targets | +| `vigil.query/v0` | `schema/vigil.query.v0.schema.json` | one named query's answer | +| `vigil.health/v0` | `schema/vigil.health.v0.schema.json` | the grafana backend's health | +| `vigil.signal/v0` | `schema/vigil.signal.v0.schema.json` | ephemeral, authenticated POST only (V3) | | `vigil.error/v0` | `schema/vigil.error.v0.schema.json` | every non-200 response | | `vigil.config/v0` | `schema/vigil.config.v0.schema.json` | YAML config, strict decode | -| `vigil.overlay/v0` | `schema/vigil.overlay.v0.schema.json` | off-repo addresses | +| `vigil.overlay/v0` | `schema/vigil.overlay.v0.schema.json` | off-repo addresses and host mapping | See [docs/cli.md](docs/cli.md) for the command surface and [docs/semantics.md](docs/semantics.md) for the field meanings and verdict diff --git a/docs/cli.md b/docs/cli.md index ec2a0f5..abd8da3 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,17 +1,48 @@ -# Vigil CLI (v0) +# Vigil CLI (V1) -One command surface, one document. `--json` prints the document alone on -stdout; errors are one JSON line on stderr. The human tables are renderers of -the same document — no command invents a second shape. +One command surface, one document per command. `--json` prints the document +alone on stdout; every failure prints one JSON line on stderr and nothing on +stdout. The human tables are renderers of the same document — no command +invents a second shape, and a table never prints a field the document lacks. + +The `--help` texts below are drafted from the command tree; they are +refreshed from the real binary once the command wiring merges. ## Global flags | Flag | Meaning | | --- | --- | +| `--config PATH` | path to the vigil.config/v0 file | +| `--overlay PATH` | path to the vigil.overlay/v0 file (backend addresses) | | `--json` | print the document alone on stdout (no table, no decoration) | | `--now ` | pin the clock; used by tests and deterministic renders | -Errors from any command are one JSON line on stderr: +`--help` output (draft, from the binary's command tree): + +``` +Vigil reads named backends (Prometheus, Grafana) through names in its +config. No command takes a URL, a selector or PromQL. + +Flags: + --config string path to the vigil.config/v0 file + --overlay string path to the vigil.overlay/v0 file (backend addresses) + --json print the document alone on stdout + --now string pin the clock to an RFC 3339 time (tests and deterministic renders) + +Commands: + prom Query the named Prometheus backend + grafana Check the named Grafana backend + sources List the configured backends and their reachability + version Print the version, the commit and the Go runtime +``` + +A path value must be a path: a URL-shaped `--config` or `--overlay` value is +a usage error (exit 3). A malformed `--now` is also exit 3. + +## Errors + +Every failure — usage errors included — is one `vigil.error/v0` JSON line on +stderr: ```json {"apiVersion":"vigil.error/v0","error":{"code":"backend_unreachable"}} @@ -19,41 +50,53 @@ Errors from any command are one JSON line on stderr: `code` is a stable machine code; `message` is optional human text and never carries a URL, a token or anything that distinguishes a missing credential -from a wrong one. Codes seen on the wire include `unauthorized`, -`not_found`, `method_not_allowed`, `payload_too_large`, `query_warnings`, -`series_cap` and `backend_unreachable`. Startup and configuration failures -print a plain line on stderr and exit 5 or 3; see the exit table in the -README. +from a wrong one. Codes on the V1 surface include `unreachable`, `timeout`, +`body_cap`, `redirect_refused`, `http_status`, `series_cap`, +`query_warnings`, `query_rejected`, `not_health`, `missing_host`, +`unexpected_host` and `usage`. Stdout stays empty on every failure. ## vigil version (V0) -Prints the binary version, the commit and the Go runtime. Available now. +Prints the binary version, the commit and the Go runtime. ``` $ vigil version -vigil v0-dev (commit 1a2b3c4d5e6f, go1.27.3) +vigil v0-dev (commit 1a2b3c4d5e6f, go1.27.4) ``` ## vigil prom targets (V1) -Lists the active scrape targets of the named prom backend. Columns, in order: +Lists the active scrape targets of the named prom backend. Table columns, in +order: | Column | Content | | --- | --- | -| `TARGET` | scrape slug (the configured slug for the instance) | -| `HEALTH` | the backend's own health for the target | -| `LAST SCRAPE` | when the backend last scraped it | +| `TARGET` | scrape slug: the overlay-mapped instance | +| `JOB` | the job label when it has a publishable shape, `redacted` otherwise | +| `HEALTH` | the backend's own health word: `up`, `down` or `unknown` | +| `LAST_SCRAPE` | when the backend last scraped it; `-` when it never did | -An instance Vigil cannot map to a slug prints as `unmapped`. The output never -includes a scrape URL, a last error or discovered labels: addresses do not -belong in CLI output. +The header block above the table carries `BACKEND`, `VANTAGE` and +`GENERATED_AT` from the document. An instance the overlay's `hosts[]` cannot +map prints as `unmapped`. The decoder never reads a scrape URL, a last error +or discovered labels, so an address in those fields cannot reach the output +even by accident. -## vigil prom query (V1) +## vigil prom query (V1) -Runs one named query from `vigil.config/v0`. There is no free-form path over -HTTP or on the CLI — the name is the only handle, and the host slug +Runs one named query from `vigil.config/v0`. The name is the only handle: +there is no free-form path over HTTP or on the CLI, and the host slug (`{{.host}}`) is the only template variable. +| Flag | Meaning | +| --- | --- | +| `--host SLUG` | fills `{{.host}}`; must be a mapped or public slug | + +Placeholder rules, both exit 3 with no backend call: + +- the expr has `{{.host}}` and `--host` is absent → `missing_host`; +- `--host` is given and the expr has no placeholder → `unexpected_host`. + Bounds the config enforces, so the docs can promise them: - instant queries only; a per-query deadline (default 5s, at most 10s) is @@ -61,64 +104,65 @@ Bounds the config enforces, so the docs can promise them: - a series cap (default 200; the request asks for one more than the cap) — more results fail with `series_cap`, never a truncated answer; - any warning the backend reports fails with `query_warnings` — never a - partial answer presented as whole. + partial answer presented as whole; +- a query the backend rejects (`bad_data` on a configured expr) is + `query_rejected` and exits 3. -Every result carries the `backend` and the `vantage` that answered. Vigil -never fails over silently: if the configured backend cannot be reached the -command exits 4 and says so. +An empty result is not an error: exit 0 with `series: []`. + +Table columns, in order: + +| Column | Content | +| --- | --- | +| `HOST` | the series' mapped host slug | +| `JOB` | the publishable job label; the column exists only when some series carries one | +| `VALUE` | the sample exactly as Prometheus reports it: a decimal, an exponent, `NaN` or an infinity | + +The header block carries `BACKEND`, `VANTAGE`, `NAME`, `HOST` (only when the +query was run for one host) and `EVALUATED_AT`. Every result is answered by +the backend and vantage the config named; Vigil never fails over silently — +if the configured backend cannot be reached the command exits 4 and says so. ## vigil grafana health (V1) -Calls `GET /api/health` on the named grafana backend. A login page is not -health. Grafana is a source, never an authority: when it is down, -`sources[]` shows it down and nothing else moves — not `overall`, not the -chip, not the exit code of a summary. +Calls `GET /api/health` on the named grafana backend with a 2s timeout, a +16 KiB body cap and no redirects. Healthy means a 200 whose body reports the +database ok; a login page or any other non-health body is `not_health`, and +a non-200 is `http_status`. -## vigil sources (V1) +The document is printed only when the backend is healthy: an unhealthy check +is exit 4 with one error line on stderr and empty stdout. Grafana is a +source, never an authority — when it is down, nothing else moves: not +`overall`, not the chip, not any other command. -Lists the configured authorities, backends and informational sources with -their reachability and the last time each was read. Same columns as the -`sources[]` table above. +Output (a key-value block; the `DETAIL_CODE` line appears only when the +document carries the field): -## vigil simplex summary (V2) +``` +BACKEND grafana +STATE ok +CHECKED_AT 2026-11-14T09:00:00Z +``` -Builds `vigil.summary/v0` from the configured authorities and renders it. -Default output is the human table; `--json` prints the document alone. The -bytes `--json` prints are the same bytes `vigil serve` serves — one document, -two renderers, test-pinned. +## vigil sources (V1) -Table columns, in order: +Lists one row per configured backend with its reachability. Table columns, +in order: -| Table | Columns | +| Column | Content | | --- | --- | -| header | `OVERALL`, `AGE` (of `generated_at`) | -| verdicts | `SOURCE`, `STATE`, `SEVERITY`, `AGE`, `REASONS` | -| hosts | `HOST`, `SEVERITY`, `REASONS` | -| sources | `SOURCE`, `KIND`, `STATE`, `AGE`, `DETAIL` | - -Reading the table: - -- The `SOURCE` column is the authority's name (`simplex`, later `augur`); - that is how a reader tells "Simplex says" from "Augur says". A verdict whose - document could not be read still appears, as `unavailable` with no - severity. -- `STATE` is `ok`, `stale` or `unavailable`. A stale row shows its age and is - never presented as current; an unavailable row shows `unavailable`. Neither - ever shows the last GREEN as current. -- `SEVERITY` in the verdicts table is the severity as published by the - authority; `overall` carries the capped combination. When they differ, the - age column and the `REASONS` column say why: verdict reasons are Vigil's - own codes, such as `authority_unavailable` (the authority could not be - read) and `source_stale` (the document is older than the freshness bound). - The cause of an unreadable source — `schema_major`, `source_unavailable` — - shows in that source's `DETAIL` cell, as its `detail_code`. -- `hosts[]` comes from Simplex alone; a clean host may have an empty reasons - cell. -- Signals do not appear here: the summary has no signals field by contract. - They are read only from `GET /v0/signals` (see `vigil serve`), where their - severity vocabulary is `info` and `notice` — deliberately not - GREEN/YELLOW/RED — and they never touch `overall`, the chip or the exit - code. +| `ID` | the backend id from the config | +| `KIND` | `prom` or `grafana` | +| `STATE` | `ok`, `stale` or `unavailable` | +| `OBSERVED_AT` | when the backend was last checked; `-` when never | +| `LAST_OK` | the last time the check succeeded; `-` when it never has | +| `DETAIL_CODE` | why a row is down; the column exists only when some row carries one | +| `VANTAGE` | the prom vantage that answered; the column exists only when some row carries one | + +A prom row is checked through `/-/ready` and carries its vantage; a grafana +row uses the health check. Rows are data: a down backend is a row state, and +the command still exits 0. `last_ok` stays null in V1 — no state is kept +between runs. Authority rows arrive at V2 and informational rows at V5. ## vigil serve (V3) @@ -159,7 +203,8 @@ them. ## Configuration Commands read `vigil.config/v0` (strict: unknown keys are errors). See -`example.config.yaml` for a valid starting point and `example.overlay.yaml` -for where addresses live — an overlay is never committed; the tracked example -uses only documentation placeholders. Token files are referenced by -environment variable or path, never a value. +`example.config.yaml` for a valid starting point — it shows the optional +`vantage` label on the prom backend — and `example.overlay.yaml` for where +addresses and the `hosts[]` instance mapping live. An overlay is never +committed; the tracked example uses only documentation placeholders. Token +files are referenced by environment variable or path, never a value. diff --git a/example.config.yaml b/example.config.yaml index c7ef2c2..57ae022 100644 --- a/example.config.yaml +++ b/example.config.yaml @@ -14,28 +14,21 @@ apiVersion: vigil.config/v0 listen: "127.0.0.1:10082" # Named backends. An id declared here is the only way to reach an address; -# the address itself lives in the overlay. +# the address itself lives in the overlay. The vantage label names the +# Prometheus vantage this backend represents; it rides on every answer. backends: - id: prom kind: prom + vantage: lathe - id: grafana kind: grafana # Authorities publish their own verdict documents; Vigil combines them into -# overall and derives none of the severity itself. +# overall and derives none of the severity itself. The example names the +# Simplex document the family already produces. authorities: - id: simplex path_ref: env:VIGIL_SIMPLEX_DOC - stale_after: 180s - - id: augur - path_ref: env:VIGIL_AUGUR_DOC - -# Informational documents. They never colour overall. -sources: - - id: scry - path_ref: env:VIGIL_SCRY_DOC - - id: cubit - path_ref: env:VIGIL_CUBIT_DOC # Named queries for the prom backend. The host slug is the only template # variable (see the CLI doc); there is no free-form path over HTTP or on the diff --git a/example.overlay.yaml b/example.overlay.yaml index dd046e9..76060ca 100644 --- a/example.overlay.yaml +++ b/example.overlay.yaml @@ -12,3 +12,16 @@ backends: address: http://prom.example.invalid:9090 - id: grafana address: http://198.51.100.10:3000 +# The hosts[] mapping turns the instance labels a backend reports into the +# public slugs the output prints. An instance no mapping claims prints as +# unmapped. An instance is a bare host or a host with a port, exactly as the +# backend reports it; brackets hold an IPv6 literal. +hosts: + - slug: castle + instances: + - "198.51.100.10:9100" + - castle.example.invalid + - slug: lathe + instances: + - "198.51.100.20:9100" + - lathe.example.invalid From 286ffa92182e9e75470100fb1a554678843e8418 Mon Sep 17 00:00:00 2001 From: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:13:26 -0800 Subject: [PATCH 2/2] Refresh the help text from the real binary Signed-off-by: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com> --- docs/cli.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index abd8da3..d0dc84e 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -5,9 +5,6 @@ alone on stdout; every failure prints one JSON line on stderr and nothing on stdout. The human tables are renderers of the same document — no command invents a second shape, and a table never prints a field the document lacks. -The `--help` texts below are drafted from the command tree; they are -refreshed from the real binary once the command wiring merges. - ## Global flags | Flag | Meaning | @@ -17,25 +14,33 @@ refreshed from the real binary once the command wiring merges. | `--json` | print the document alone on stdout (no table, no decoration) | | `--now ` | pin the clock; used by tests and deterministic renders | -`--help` output (draft, from the binary's command tree): +`vigil --help` output, captured from the binary: ``` Vigil reads named backends (Prometheus, Grafana) through names in its config. No command takes a URL, a selector or PromQL. - +Usage: + vigil [flags] + vigil [command] +Available Commands: + grafana Check the named Grafana backend + help Help about any command + prom Query the named Prometheus backend + sources List the configured backends and their reachability + version Print the version, the commit and the Go runtime Flags: - --config string path to the vigil.config/v0 file - --overlay string path to the vigil.overlay/v0 file (backend addresses) - --json print the document alone on stdout - --now string pin the clock to an RFC 3339 time (tests and deterministic renders) - -Commands: - prom Query the named Prometheus backend - grafana Check the named Grafana backend - sources List the configured backends and their reachability - version Print the version, the commit and the Go runtime + --config string path to the vigil.config/v0 file + -h, --help help for vigil + --json print the document alone on stdout + --now string pin the clock to an RFC 3339 time (tests and deterministic renders) + --overlay string path to the vigil.overlay/v0 file (backend addresses) +Use "vigil [command] --help" for more information about a command. ``` +Every subcommand accepts the four global flags as global flags and `-h, +--help`; `prom query` adds `--host`. Use `vigil --help` for each +command's own text. + A path value must be a path: a URL-shaped `--config` or `--overlay` value is a usage error (exit 3). A malformed `--now` is also exit 3.