11. Channels & Metrics (fleetmesh_node.channels / fleetmesh_node.metrics)
Fleetmesh uses an in-memory publish-subscribe channel bus for inter-compartment decoupling, and an explicit Prometheus metrics registry for operational telemetry.
11.1. Channel Bus
Internal publish/subscribe event bus for decoupled node communication.
Replaces cyclic cross-subsystem dependencies and monkey-patching with an in-process event bus. Standard library only.
The bus is synchronous and in-process. The Tap is how it reaches outside: every emit is also serialised through the topic’s wire function in WIRE and appended to a ring buffer with a sequence number, and each Subscriber holds a bounded queue the control socket drains. The emitting thread never waits on a reader: a full queue drops its oldest entry and the subscriber is told how many went by. Nothing here is durable across a restart and nothing claims to be - a reader that needs every event replays the relays.
- fleetmesh_node.channels.bus.register_wire(topic, fn)[source]
A plugin’s own topic, with how it goes on the wire. Adds, never replaces.
- Parameters:
topic (str)
fn (Callable[[...], WindowEvaluatedWire | WindowRepricedWire | SessionCompletedWire | GrantIssuedWire | PeerConnectedWire | ReportAdmittedWire | MetaDroppedWire | LossyWire | Mapping[str, Any]])
- Return type:
None
- fleetmesh_node.channels.bus.to_wire(topic, args, kwargs)[source]
- Parameters:
- Return type:
WindowEvaluatedWire | WindowRepricedWire | SessionCompletedWire | GrantIssuedWire | PeerConnectedWire | ReportAdmittedWire | MetaDroppedWire | LossyWire | Mapping[str, Any]
- class fleetmesh_node.channels.bus.Subscriber[source]
Bases:
objectOne reader’s bounded queue. next(timeout) blocks for one envelope or returns None; dropped is how many were pushed out by a full queue since the last one the reader took, reported to it as a meta.dropped envelope.
- q: Queue[BusEnvelope]
- push(env)[source]
- Parameters:
env (BusEnvelope)
- Return type:
None
- next(timeout)[source]
- Parameters:
timeout (float)
- Return type:
BusEnvelope | None
- class fleetmesh_node.channels.bus.Tap[source]
Bases:
objectSequence numbers, a ring of the last ring envelopes, and the live subscribers.
- ring: deque[BusEnvelope]
- unsubscribe(s)[source]
- Parameters:
s (Subscriber)
- Return type:
None
- class fleetmesh_node.channels.bus.NodeEventBus[source]
Bases:
objectThread-safe synchronous in-process event bus.
- emit(topic, *args, **kwargs)[source]
Emit an event to all subscribers of the topic.
Exceptions in handlers are caught and isolated so other subscribers still run. Returns a list of handler return values.
11.2. Channel Event Journal
How a node says things to its journal.
These two lived in app.py, where a compartment could not reach them without importing the node that imports the compartment. They are not the node’s: they are how anything in the node writes a line an operator will read.
- fleetmesh_node.channels.journal.line(*parts)[source]
One timestamped line on stderr, flushed.
A node runs under systemd, where both streams are the journal, and the first deployment of two of these found them completely silent: journalctl -u meshnode held one line, the one systemd wrote itself. An operator could not tell whether the node had peered, pulled, been declined or crashed without reading a JSON file it had never been told about. A daemon that does work says what it did.
It says it on stderr, and that is not cosmetic. It used to go to stdout, which is also where meshnode <cmd> –json writes its answer, and a node busy enough to say something while a command was answering put a line like
2026-09-05T21:56:24Z < acked-out 67dd799a6be0… accepted [{“epoch”: 496527, …}]
on one stream. The reader got Extra data: line 1 column 5. fleetmesh_node/README.md offers –json and the control socket to “a dashboard, a metrics exporter, a fleet script”; a stream that is usually parseable is not an API. So stdout is the answer to what was asked, stderr is the running commentary, and systemd captures both exactly as before.
- Parameters:
parts (Any)
- Return type:
None
11.3. Metrics Adapters
Rendering readings for whoever is asking.
An adapter turns Monitors.read() into one wire format. They are separate from the registry for the reason the log’s backends are separate from the channels: what a compartment measures is not a decision about who scrapes it, and a second consumer must not mean a second set of declarations.
- prometheus the text exposition format, which is also OpenMetrics-
compatible enough for a Prometheus server to scrape
- json the same readings as data, for the control socket and the
health block
relayserver already accepts a metrics_provider callable and nothing ever passed one, so provider(monitors) is the function to hand it. The relay face’s hand-written exposition then becomes the fallback it already is rather than the only path.
- fleetmesh_node.metrics.adapters.prometheus(monitors)[source]
The text exposition format.
HELP and TYPE are emitted once per metric name and before its samples, which the format requires: a repeated TYPE line makes a scrape fail, and a scrape that fails is monitoring that is absent rather than wrong.
- Parameters:
monitors (Monitors)
- Return type:
- fleetmesh_node.metrics.adapters.json_readings(monitors)[source]
The readings as data, for the control socket and the health block.
The same readings the exposition is built from, so a dashboard reading the socket and a Prometheus server scraping the face cannot see different numbers - which is the failure the log had before Channel.
- Parameters:
monitors (Monitors)
- Return type:
- fleetmesh_node.metrics.adapters.provider(monitors)[source]
The callable relayserver(metrics_provider=…) has always wanted.
11.4. Metrics Face & Prometheus Exposition
The relay face’s metrics, as declarations.
relayserver.render_metrics built these eight by hand, with the names, HELP and TYPE typed inline and every reading wrapped in hasattr plus a bare except: pass. They were the only metrics the node exposed.
Declaring them changes nothing an operator scrapes, and that is the point. Every exposed name and every TYPE is reproduced exactly, because a metric name is an interface: a dashboard, an alert rule and a recording rule are all written against it, and renaming one to suit a convention breaks them silently. Two of these are not what their names suggest - fleetmesh_blobs_total is a gauge despite the counter suffix, and fleetmesh_events_stored_total counts what is in the store now and can go down - and both are kept as they are rather than corrected. The place to fix an exposition name is a release note, not a refactor.
What does change: the readings come through Monitors, so a sampler that raises is counted rather than swallowed by except: pass, and the face’s numbers sit in the same census as every compartment’s.