RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

The alert interface: an application raises an alert, and every enabled channel it binds whose severity threshold the alert meets delivers it.

robohub-alert

The alert interface. An application raises an alert; every channel it binds
delivers it, unless the channel is disabled or the alert is below the channel's
severity threshold. The channels are providers: robohub-provider-log,
-email, -telegram and -webhook.

deps:
  robohub:
    robohub-alert: ">=1.1.0"
    robohub-provider-telegram: ">=0.2.0"
    robohub-provider-log: ">=0.2.0"
bind:
  robohub.alert:
    providers: [robohub-provider-telegram, robohub-provider-log]
import robohub.alert

let delivered: u32 = alert.raise("WARNING", "Tank too warm", "{\"tank\":\"main\"}")

The interface only is a dependency of a shared module such as rules; the
application chooses the channels. An application that binds none raises alerts
that reach no channel (raise answers 0) — rules writes them to the journal
either way.

Settings every channel has

Besides its own settings (listed on each provider's page), every channel
accepts two the interface reads:

SettingWhat it does
enabled"false" stops the channel receiving alerts; anything else, or nothing, leaves it on
severity_thresholdThe lowest level the channel receives: INFO, WARNING, ERROR or CRITICAL. Empty receives everything

Levels are compared by name, in capitals: INFO < WARNING < ERROR <
CRITICAL, and a level the interface does not know ranks with INFO.

A channel's settings are its bind: values, and the application's bind.conf
(<provider>.<key>=value lines in its workspace) wins over them, so
configure(provider, key, value) changes a setting on a running installation
without a rebuild.

What an application calls

FunctionWhat it does
raise(level, message, metadata)delivers an alert to every enabled channel it meets the threshold of; answers how many accepted it
test(provider, message)sends through one channel whatever its settings, for a settings page to show the channel works
providers()the channels the application binds, one per line
enabled(provider)whether a channel receives alerts: unless its enabled setting says false
config(provider, key), configure(provider, key, value)one of a channel's settings, read or changed on the running installation

What a channel implements

send(level: string, message: string, metadata: string) u32

The calls to the channels are generated from the application's binding, so
neither the interface nor the application names a provider's internals.

The alert state machine

alert_rule_new(id, name, threshold, hysteresis, pending_seconds, cooldown_seconds, max_per_window, window_seconds) makes a rule, and
alert_rule_evaluate(rule, value, now) advances it by one sample, answering an
AlertEvaluation: the next rule, and whether it fired or cleared. A rule is
a value; the caller keeps the one it is given back.

  • normal → pending when the value reaches the threshold;
  • pending → triggered once it has stayed there pending_seconds (at once
    when that is 0), and back to normal if it does not;
  • triggered → cooldown when it falls below the threshold less the
    hysteresis;
  • cooldown → normal or pending after cooldown_seconds.

A rule fires at most max_per_window times in window_seconds (0: no limit).
Times are seconds from any monotonic source the application chooses.

Release history

All notable changes to the alert interface are recorded here, one section per release.

[0.1.1] - 2026-11-12

A plugin's kind and transport are read where the plugins declare them (module.plugin_kind, module.plugin_transport), with a plugin: block still accepted. Before, every plugin fell back to the log transport, so e-mail, Telegram and webhook alerts were written to the log instead of sent. The plugin list comes from the registry rather than placeholder rows, and nothing is written into the plugins folder to make it.

[1.0.0] - 2026-11-12

The alert contract is the alert interface, robohub-alert (import robohub.alert), and the plugin manager is gone. An application declares the interface and the providers it uses under deps, binds the providers in its module.yml, and calls alert.raise(level, message, metadata); the alert reaches every bound channel that is enabled and whose severity_threshold it meets. alert.test, alert.providers, alert.enabled, alert.config and alert.configure are what a settings page uses, and a setting changed through configure is kept in the application's bind.conf, so it holds on a running installation without a rebuild. Only the bound providers are compiled in. The alert rules moved to src/rule.rho with their tests, which the interface runs itself (rho test), and string comparisons in them compare contents on C.

[1.1.0] - 2026-11-12

AlertRule and AlertEvaluation are exported, so an application that keeps a rule names its type, as alert.AlertRule or, when no other module declares one, AlertRule.

[1.1.1] - 2026-11-14

A severity is read in any case: the rules module raises warning, and a channel whose threshold is WARNING dropped every one of those alerts.