aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:51:40 +0000
committertv <tv@krebsco.de>2026-11-17 15:04:40 +0100
commit7b7c09b818a94be3d1493817d38404a1b208aa9e (patch)
tree7645182fd85452982c48a7c10e7f743cbc395d14 /docs/guides
parent439ca746d6f84686e7ebab1835b683ae689e4b81 (diff)
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.
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/watching.md45
2 files changed, 47 insertions, 0 deletions
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`.