Struct HealthMonitor 

pub struct HealthMonitor { /* private fields */ }

Central health monitor for all active feeds.

Implementations

impl HealthMonitor

pub fn new(default_stale_threshold_ms: u64) -> Self

Create a monitor with a default staleness threshold (milliseconds).

Individual feeds can override this with a custom threshold via HealthMonitor::register.

pub fn with_circuit_breaker_threshold(self, threshold: u32) -> Self

Configure how many consecutive stale checks open the circuit (default: 3). Set to 0 to disable circuit-breaking.

pub fn is_circuit_open(&self, feed_id: &str) -> bool

Returns true if the feed’s circuit is open (too many consecutive stale checks). An open circuit means callers should stop routing work to this feed.

pub fn register_many(&self, ids: &[&str], stale_threshold_ms: Option<u64>)

Register multiple feeds in one call.

Each feed in ids is registered with the same optional staleness threshold. Equivalent to calling register for each ID individually.

pub fn register( &self, feed_id: impl Into<String>, stale_threshold_ms: Option<u64>, )

Register a feed with optional custom staleness threshold.

pub fn deregister(&self, feed_id: &str) -> Option<FeedHealth>

Remove a previously registered feed from the monitor.

Returns the last known FeedHealth for the feed, or None if it was not registered.

pub fn heartbeat(&self, feed_id: &str, ts_ms: u64) -> Result<(), StreamError>

Record a tick heartbeat for a feed.

Errors

Returns StreamError::UnknownFeed if feed_id has not been registered via register.

pub fn check_all(&self, now_ms: u64) -> Vec<(String, StreamError)>

Check all feeds for staleness at the given timestamp.

Returns a list of (feed_id, error) pairs for stale feeds so callers can route errors to the appropriate handler without re-parsing the feed identifier out of the error message.

pub fn get(&self, feed_id: &str) -> Option<FeedHealth>

Get health state for a specific feed.

pub fn all_feeds(&self) -> Vec<FeedHealth>

All registered feeds.

pub fn feed_count(&self) -> usize

Total number of registered feeds.

pub fn check_one( &self, feed_id: &str, now_ms: u64, ) -> Result<Option<StreamError>, StreamError>

Check staleness for a single feed at now_ms.

Returns Some(StreamError::StaleFeed { .. }) if the feed is stale, None if it is healthy or has not yet received any ticks, or Err(StreamError::UnknownFeed) if feed_id is not registered.

pub fn reset_feed(&self, feed_id: &str) -> Result<(), StreamError>

Reset a feed’s stale counter and status without deregistering it.

Clears consecutive_stale, tick_count, last_tick_ms, and sets the status back to Unknown. Useful when a feed reconnects and should be treated as fresh.

Errors

Returns StreamError::UnknownFeed if feed_id is not registered.

pub fn feed_ids(&self) -> Vec<String>

Sorted list of all registered feed identifiers.

pub fn healthy_count(&self) -> usize

Number of feeds currently in the HealthStatus::Healthy state.

pub fn stale_ratio(&self) -> f64

Fraction of registered feeds that are currently stale, in [0.0, 1.0].

Returns 0.0 when no feeds are registered.

pub fn is_any_stale(&self) -> bool

Returns true if at least one registered feed is in HealthStatus::Stale state.

pub fn stale_count(&self) -> usize

Number of feeds currently in the HealthStatus::Stale state.

pub fn stale_feeds(&self) -> Vec<FeedHealth>

Clone of all feeds currently in the HealthStatus::Stale state.

Useful for bulk alerting: iterate the returned vec to log or notify on every stale feed in one call rather than checking each feed individually.

pub fn oldest_tick_ms(&self) -> Option<u64>

The oldest last_tick_ms across all registered feeds, or None if no feed has received any tick yet.

pub fn newest_tick_ms(&self) -> Option<u64>

The most recent last_tick_ms across all registered feeds, or None if no feed has received any tick yet.

pub fn total_tick_count(&self) -> u64

Sum of tick counts across all registered feeds.

Useful for throughput monitoring: the total number of heartbeats seen since the monitor was created (counts are not reset by reset_all).

pub fn lag_ms(&self) -> Option<u64>

Feed skew: newest_tick_ms - oldest_tick_ms across all registered feeds.

Returns None if fewer than two feeds have received ticks. A large lag indicates that some feeds are receiving data faster than others — useful for detecting slow feeds or feed-specific latency spikes.

pub fn most_stale_feed(&self) -> Option<FeedHealth>

The feed that has gone the longest without receiving a tick.

Among all registered feeds, returns the one with the oldest (smallest) last_tick_ms. Feeds that have never received a tick (last_tick_ms == None) are considered more stale than any feed that has. Returns None` if no feeds are registered.

pub fn stale_ratio_excluding_unknown(&self) -> f64

Fraction of known (non-unknown) feeds that are stale.

Excludes feeds in Unknown state from the denominator. Returns 0.0 when no non-unknown feeds are registered.

pub fn healthy_feeds(&self) -> Vec<String>

Feed identifiers that are currently in HealthStatus::Healthy state.

Returns a sorted list of IDs. Complement of unhealthy_feeds.

pub fn unhealthy_feeds(&self) -> Vec<String>

Feed identifiers whose status is not HealthStatus::Healthy.

Returns a sorted list of IDs that are Stale or Unknown. Complement to healthy_count; avoids caller iteration when only the unhealthy feed names are needed.

pub fn reset_all(&self)

Reset all registered feeds to Unknown status, clearing last-tick timestamps.

Useful at session boundaries (e.g. daily market open) to start fresh staleness tracking without re-registering feeds. Tick counts are preserved.

pub fn all_healthy(&self) -> bool

Returns true if every registered feed is in HealthStatus::Healthy state.

Vacuously true when no feeds are registered. Use feed_count to distinguish “all healthy” from “no feeds registered”.

pub fn ratio_healthy(&self) -> f64

Fraction of registered feeds currently in HealthStatus::Healthy state.

Returns 0.0 if no feeds are registered.

pub fn last_updated_feed_id(&self) -> Option<String>

ID of the feed whose last_tick_ms is the most recent (largest value).

Returns None if no feed has ever received a tick.

pub fn unknown_feed_ids(&self) -> Vec<String>

IDs of all feeds currently in HealthStatus::Unknown state.

pub fn status_summary(&self) -> (usize, usize, usize)

Count of feeds in each health state: (healthy, stale, unknown).

Equivalent to calling healthy_count, stale_count, and unknown_count in one pass.

pub fn stale_feed_ids(&self) -> Vec<String>

Feed identifiers whose status is exactly HealthStatus::Stale.

Unlike unhealthy_feeds, feeds with HealthStatus::Unknown are excluded. Returns a sorted list.

pub fn total_stale_count(&self) -> usize

👎Deprecated since 2.2.0:

Use stale_count instead

Count of feeds currently in Stale status.

Alias for stale_count.

pub fn feeds_needing_check(&self) -> Vec<String>

👎Deprecated since 2.2.0:

Use unhealthy_feeds instead

IDs of all feeds that are Stale or Unknown — feeds that require attention.

Alias for unhealthy_feeds.

pub fn avg_feed_age_ms(&self, now_ms: u64) -> Option<f64>

Average age in milliseconds across all feeds that have received at least one tick.

Returns None if no feed has ever received a tick.

pub fn unknown_count(&self) -> usize

Number of feeds whose status is HealthStatus::Unknown.

Feeds start in Unknown state before the first heartbeat arrives. A non-zero count indicates feeds that have never been heard from.

pub fn avg_tick_count(&self) -> f64

Average tick count per registered feed.

Returns 0.0 if no feeds are registered.

pub fn max_consecutive_stale(&self) -> u32

Maximum consecutive_stale count across all registered feeds.

Returns 0 if no feeds are registered or none have been stale yet.

pub fn unknown_feed_count(&self) -> usize

👎Deprecated since 2.2.0:

Use unknown_count instead

Number of feeds currently in the HealthStatus::Unknown state.

Alias for unknown_count.

pub fn feeds_by_status(&self, status: HealthStatus) -> Vec<FeedHealth>

All feeds whose current status exactly matches status.

Returns a Vec of cloned FeedHealth entries. Order is unspecified. Use stale_feeds as a shorthand for the common Stale case.

pub fn oldest_stale_feed(&self) -> Option<FeedHealth>

The stale feed with the oldest last_tick_ms, or None if no feeds are stale.

“Oldest” means the feed that has gone the longest without a heartbeat — i.e., the one with the smallest last_tick_ms. Feeds with last_tick_ms == None are placed last (they have never ticked).

pub fn healthy_ratio(&self) -> f64

👎Deprecated since 2.2.0:

Use ratio_healthy instead

Fraction of registered feeds that are currently Healthy: healthy / total.

Alias for ratio_healthy.

pub fn most_reliable_feed(&self) -> Option<FeedHealth>

The feed with the highest lifetime tick count, or None if no feeds are registered.

“Most reliable” is defined as the feed that has processed the greatest number of heartbeats since registration or last reset.

pub fn feeds_never_seen(&self) -> Vec<FeedHealth>

All feeds that have never received a heartbeat (last_tick_ms is None).

Useful for detecting feeds that were registered but have not yet started streaming data.

pub fn is_any_feed_stale(&self) -> bool

👎Deprecated since 2.2.0:

Use is_any_stale instead

Returns true if at least one registered feed currently has HealthStatus::Stale status.

Alias for is_any_stale.

pub fn all_feeds_seen(&self) -> bool

Returns true if every registered feed has received at least one heartbeat (last_tick_ms is Some).

Returns true vacuously when no feeds are registered.

pub fn tick_count_for(&self, feed_id: &str) -> Option<u64>

Returns the tick_count for feed_id, or None if the feed is not registered.

pub fn average_tick_count(&self) -> f64

👎Deprecated since 2.2.0:

Use avg_tick_count instead

Average tick count across all registered feeds.

Alias for avg_tick_count.

pub fn feeds_above_tick_count(&self, threshold: u64) -> usize

Count of feeds whose tick_count exceeds threshold.

pub fn oldest_feed_age_ms(&self, now_ms: u64) -> Option<u64>

Age in milliseconds of the feed with the oldest last_tick_ms (the most stale one) relative to now_ms.

Returns None if no feed has ever received a tick.

pub fn has_any_unknown(&self) -> bool

Returns true if at least one feed currently has HealthStatus::Unknown status.

pub fn is_degraded(&self) -> bool

Returns true if at least one feed is unhealthy but not all feeds are unhealthy.

A fully-healthy or fully-down monitor both return false. Returns false when no feeds are registered.

pub fn unhealthy_count(&self) -> usize

Number of feeds that are not in the HealthStatus::Healthy state.

pub fn feed_exists(&self, feed_id: &str) -> bool

Returns true if a feed with the given ID is registered.

pub fn any_unknown(&self) -> bool

👎Deprecated since 2.2.0:

Use has_any_unknown instead

Returns true if any registered feed has HealthStatus::Unknown status.

Alias for has_any_unknown.

pub fn degraded_count(&self) -> usize

👎Deprecated since 2.2.0:

Use stale_count instead

Count of feeds in HealthStatus::Stale state (degraded but not unknown).

Alias for stale_count.

pub fn time_since_last_heartbeat( &self, feed_id: &str, now_ms: u64, ) -> Option<u64>

Milliseconds since the last heartbeat for feed_id at now_ms.

Returns None if the feed is not registered or has never received a tick.

pub fn healthy_feed_ids(&self) -> Vec<String>

IDs of all feeds currently in HealthStatus::Healthy state.

pub fn register_batch(&self, feeds: &[(&str, u64)])

Register multiple feeds, each with its own staleness threshold.

feeds is a slice of (feed_id, threshold_ms) pairs. Useful when different feeds have different latency requirements.

pub fn min_healthy_age_ms(&self, now_ms: u64) -> Option<u64>

Age in milliseconds of the most recently-ticked healthy feed at now_ms.

Returns None if no healthy feeds have received a tick.