Observing a node

A running node exposes two, complementary observability surfaces: a small in-process health view you read directly off INodusNode, and a metrics pipeline that captures rolling per-node counters and pushes them out to a collector. This page covers both, and is honest about what each one fills in today.

---

The in-process health surface

Every node exposes node.Health, an IClusterHealth, for a synchronous read of how the cluster looks from this node's vantage point:

IClusterHealth health = node.Health;

NodeHealthStatus              me    = health.Local;   // this node
IReadOnlyList<NodeHealthStatus> peers = health.Peers;   // each known peer
ClusterMetrics                cm    = health.Metrics;  // rolled-up counters

NodeHealthStatus carries NodeId, IsAlive, LastSeenUtc, and Roles — enough to render a membership table or drive a liveness probe. Local and Peers are backed by the same peer registry and heartbeat state that failure detection uses, so they track the health and gossip view.

ClusterMetrics is mostly unfilled today

ClusterMetrics declares three fields, but only one is populated in this version:

Field	Populated?	Source
ActivePeers	Yes	The current count of known peers.
TotalMessagesSent	No — reads 0	Not wired to the transport counters yet.
AvgLatencyMs	No — reads 0	Not wired yet.

Treat node.Health.Metrics.ActivePeers as the one reliable number on this struct, and read message/latency counts from the metrics pipeline below rather than from here.

---

The metrics pipeline

Richer, time-windowed telemetry lives in the Clustron.Nodus.Metrics project. It is a self-contained rolling-metrics registry — RollingMetricsRegistry, RollingCounter, MetricSample, MetricType, and the MetricsSnapshot DTO — plus the IMetricContributor / IMetricsListener / IMetricsSnapshotProvider seams that let a node produce and consume snapshots.

A MetricsSnapshot is the unit that travels between nodes and out to a collector:

public class MetricsSnapshot
{
    public string           NodeId            { get; set; }
    public DateTime         TimestampUtc      { get; set; }
    public int              ActiveConnections { get; set; }
    public List<MetricSample> Metrics         { get; set; } = new();
}

Configure the window and push target

Metrics behaviour is configured by MetricsOptions on NodusConfig.Metrics (see Configuration):

Key	Default	Role
RollingWindowSeconds	60	Width of the rolling window each node keeps.
MetricsTimeoutMilliseconds	60000	How long a collector waits for a peer's snapshot before giving up.
PushTargetUrl	null	If set, snapshots are POSTed to this endpoint (api/snapshot). Leave null to keep metrics in-process.

var config = new NodusConfig
{
    Metrics = new MetricsOptions
    {
        RollingWindowSeconds       = 60,
        MetricsTimeoutMilliseconds = 60000,
        PushTargetUrl              = "http://collector:9000",   // opt in to pushing
    },
};

The metrics-collector role

Metrics collection is role-gated, so you decide which node does the fan-out. Set the metrics-collector role (the NodusRoles.MetricsCollector constant, "metrics-collector") on a node and it actively polls every member peer for a MetricsSnapshot, honouring MetricsTimeoutMilliseconds per peer; if PushTargetUrl is set it forwards each snapshot onward. A plain member node produces and can push its own snapshot directly. Either way, PushTargetUrl is what turns capture into export — without it, snapshots are produced but never leave the process.

new NodeInfo
{
    NodeId = "collector-1",
    Roles  = { NodusRoles.MetricsCollector },   // this node polls peers and forwards snapshots
}

---

Where the numbers get charted

Nodus captures and ships metrics, but it does not store or visualize them. The PushTargetUrl posts each MetricsSnapshot to a snapshot endpoint (api/snapshot), which is the ingest shape a metrics collector serves. Point PushTargetUrl at a collector's web API and its dashboard charts your nodes' per-second rates and gauges.

---

Next steps

• Health and membership — reading node.Health and reacting to membership changes.
• Configuration — every MetricsOptions knob with its default.