Module Algostream_telemetry.Health

Named health checks with staleness budgets.

A monitoring dashboard needs to distinguish three things a raw counter cannot: working, working badly, and not working. Every check answers with one of those, and carries the reason as text so the UI never has to guess why something is amber.

Checks are pure functions supplied by the caller. This module deliberately knows nothing about ingestion, processors or strategies — it is handed closures, which keeps algostream.telemetry dependent on nothing but the event bus.

type status =
  1. | Ok
  2. | Degraded of string
  3. | Failed of string
val status_to_string : status -> string
val severity_rank : status -> int

Rank for aggregation: Ok < Degraded < Failed.

val worst : status list -> status

Worst status in a list; Ok for the empty list.

type check = {
  1. name : string;
  2. run : unit -> status;
}
type report = {
  1. check_name : string;
  2. status : status;
  3. checked_at_ns : int64;
}
val stale : what:string -> age_ns:int64 -> degraded_after_ns:int64 -> failed_after_ns:int64 -> status

stale ~what ~age_ns ~degraded_after_ns ~failed_after_ns is the shape almost every feed check takes: fresh is Ok, quiet is Degraded, silent is Failed.

age_ns = Int64.max_int means "nothing has ever arrived", which reports Failed rather than being treated as infinitely stale — it is a different problem and worth different wording.

val threshold : what:string -> value:float -> degraded_above:float -> failed_above:float -> unit_:string -> status

threshold ~what ~value ~degraded_above ~failed_above ~unit_ for any metric where bigger is worse — queue depth, drop rate, latency.

val run_all : check list -> ts_ns:int64 -> report list

Run every check, stamping each result with ts_ns. A check that raises is reported as Failed rather than propagating: one broken probe must not take down the health endpoint.

val overall : report list -> status

Overall status: the worst of the reports.