Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 83 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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 <name>` | 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

Expand All @@ -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
Expand All @@ -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
Expand Down
Loading
Loading