From 7b7c09b818a94be3d1493817d38404a1b208aa9e Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 13:51:40 +0000 Subject: guides: what to watch in a federated swarm Beside what every node needs watching: a version a node refused, a node without its store, the proposals and the version, the members, the events beyond the checkpoint, and the store's log lines at warn and error. --- docs/guides/federation/README.md | 2 ++ docs/guides/federation/watching.md | 45 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 docs/guides/federation/watching.md (limited to 'docs') diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 5d3538a..a4af7f7 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -32,3 +32,5 @@ by them, in its words. again after a switch, two epochs for one, and rejoining. * [`upgrades.md`](upgrades.md): upgrading the nodes of a federated swarm, and what the federation's number says. +* [`watching.md`](watching.md): what a node's API and its log say that needs an operator + or a party. diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md new file mode 100644 index 0000000..e83408f --- /dev/null +++ b/docs/guides/federation/watching.md @@ -0,0 +1,45 @@ +# What to watch + +What tells an operator, or a party, that a federated swarm needs them. Watch what every +node needs watching ([`operations.md`](../../operations.md), What to alert on), and +besides it, the node's store, through its API and its log. + +## Through the API + +* **A version the node refused** (`own` in `GET /events/refused` not empty): keys voted + twice, and nodes may be apart. Act on it at once + ([`when-things-go-wrong.md`](when-things-go-wrong.md)). +* **No store** (`404` from `GET /events` for longer than a start takes): the node can't + read its store ([`when-things-go-wrong.md`](when-things-go-wrong.md), A node doing less + than it should). +* **Proposals on the current version** (`proposals` in `GET /events/counts`): each with + the votes on it; the party's record says what it voted. +* **The version** (`.version.number` in `GET /events/counts`): a change nobody expected + is worth a look at what passed and who voted for it. +* **The members** (`members` in `GET /events/counts`): a node of your party missing + there syncs with nobody. +* **Events beyond the checkpoint** (`taken` in `GET /events`): what a move to a + checkpoint would let nodes forget; a node voting by itself proposes one at a count you + set ([`voting-by-itself.md`](voting-by-itself.md)). + +## In the log + +At warn or error: + +* `Refused an event its history takes, by what this node took before: kept so`: a version + the node refused, as above; +* `This node isn't a member of its store, as it reads now: its party doesn't list it, and + members don't sync with it`; +* `The pinned checkpoint isn't in the document (yet): holding no store until it is`; +* `The document's root is no store's: not reading it`, `Reading the store from the + document failed`; +* `Couldn't write the store file: a restart may take what this node refused`: a full or + read-only disk; +* `Couldn't vote by itself`, `Voting by itself, without its party's record: votes none`; +* `Couldn't put what it signed for its party: put again later`, `Couldn't write a version + that passed: put again later`, `Couldn't put again events the document lacks`; +* `Dropped events, as this node's operator says`: whoever may use the node's API did it. + +At info, worth knowing: `The store's members, as it reads now`, `Writing a version that +passed`, `Voting for its party`, `Proposing a checkpoint for its party`, `This node is a +member of its store`. -- cgit v1.3.1