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.

class fleetmesh_node.channels.bus.MetaDroppedWire[source]

Bases: TypedDict

count: int
class fleetmesh_node.channels.bus.LossyWire[source]

Bases: TypedDict

lossy: bool
repr: str
error: str
class fleetmesh_node.channels.bus.WindowEvaluatedWire[source]

Bases: TypedDict

peer: str
epoch: int
severity: str
measured: Mapping[str, int] | None
claimed: Mapping[str, int] | None
closed: bool
class fleetmesh_node.channels.bus.WindowRepricedWire[source]

Bases: TypedDict

peer: str
epoch: int
was: str
now: str
class fleetmesh_node.channels.bus.SessionCompletedWire[source]

Bases: TypedDict

peer: str
role: str
status: str | None
counters: Mapping[str, int | float] | None
findings: int
class fleetmesh_node.channels.bus.GrantIssuedWire[source]

Bases: TypedDict

peer: str
cause: str
envelope: str
tier: str | None
class fleetmesh_node.channels.bus.PeerConnectedWire[source]

Bases: TypedDict

peer: str
role: str
transport: str | None
class fleetmesh_node.channels.bus.ReportAdmittedWire[source]

Bases: TypedDict

reporter: str
target: str
id: str
admissible: bool
contradicted: bool
class fleetmesh_node.channels.bus.BusEnvelope[source]

Bases: TypedDict

seq: int | None
ts: int
topic: str
data: WindowEvaluatedWire | WindowRepricedWire | SessionCompletedWire | GrantIssuedWire | PeerConnectedWire | ReportAdmittedWire | MetaDroppedWire | LossyWire | Mapping[str, Any]
class fleetmesh_node.channels.bus.BusState[source]

Bases: TypedDict

seq: int
ring: int
ring_max: int | None
subscribers: int
oldest: int | None
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:
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: object

One 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.

__init__(topics, maxsize)[source]
Parameters:
Return type:

None

topics: set[str] | None
q: Queue[BusEnvelope]
dropped: int
wants(topic)[source]
Parameters:

topic (str)

Return type:

bool

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: object

Sequence numbers, a ring of the last ring envelopes, and the live subscribers.

__init__(ring=1000, queue_size=1000, clock=None)[source]
Parameters:
Return type:

None

seq: int
ring: deque[BusEnvelope]
queue_size: int
clock: Callable[[], int]
record(topic, args, kwargs)[source]
Parameters:
Return type:

BusEnvelope

subscribe(topics=None)[source]
Parameters:

topics (set[str] | None)

Return type:

Subscriber

unsubscribe(s)[source]
Parameters:

s (Subscriber)

Return type:

None

since(seq, topics=None, last=0)[source]

Envelopes after seq still in the ring, oldest first; last keeps only that many newest.

Parameters:
Return type:

List[BusEnvelope]

state()[source]
Return type:

BusState

class fleetmesh_node.channels.bus.NodeEventBus[source]

Bases: object

Thread-safe synchronous in-process event bus.

__init__()[source]
Return type:

None

tap: Tap | None
subscribe(topic, handler)[source]

Subscribe a callable to a topic.

Parameters:
Return type:

None

unsubscribe(topic, handler)[source]

Unsubscribe a callable from a topic. Returns True if removed.

Parameters:
Return type:

bool

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.

Parameters:
Return type:

List[Any]

subscribers(topic)[source]

Return a snapshot list of subscribers for a topic.

Parameters:

topic (str)

Return type:

List[Callable[[…], Any]]

topics()[source]

Return all topics that have at least one active subscriber.

Return type:

List[str]

property counts: Counter[str]

Return emission counts by topic.

clear()[source]

Remove all subscriptions.

Return type:

None

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

fleetmesh_node.channels.journal.short(x)[source]

Long hex is unreadable in a log and its first bytes identify it.

Parameters:

x (Any)

Return type:

str

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:

str

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:

Exposition

fleetmesh_node.metrics.adapters.provider(monitors)[source]

The callable relayserver(metrics_provider=…) has always wanted.

Parameters:

monitors (Monitors)

Return type:

Callable[[], str]

class fleetmesh_node.metrics.adapters.Exposition[source]

Bases: TypedDict

The readings as data: what the control socket and the health block get.

A named record for the reason check-dicts.py enforces it - this is a row an operator reads by field name.

metrics: list[Reading]
registry: RegistryState

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.

fleetmesh_node.metrics.face.face_metrics(face)[source]

The eight the relay face has always exposed, bound to this server.

face is the RelayServer. The samplers close over it rather than being handed values, so each scrape reads the live number.

Parameters:

face (Any)

Return type:

tuple[Metric, …]