Rules, Alarms, and Actions
How DataHub detects conditions, raises alarms, and delivers automated responses.
DataHub evaluates rules against incoming telemetry in real time. When a condition is met, the platform creates an alarm and executes configured actions.
Rule evaluation
The rule-worker maintains an in-memory cache of active rules keyed by tag path. For each telemetry event:
- Match rules bound to the event's tagPath
- Evaluate the detector for that rule type
- Track state in
RuleState(one row per rule): NORMAL, PENDING, or TRIGGERED - Create an alarm when the condition fires
- Enqueue action jobs to BullMQ
Rule changes propagate via datahub.rule.changed — no worker restart required.
Detector types
DataHub ships six rule detectors. Each rule has a ruleType and optional params object.
| Type | Purpose | Key params |
|---|---|---|
| THRESHOLD | Classic high/low trip on live value | Expression (e.g. value > 80); optional recover expression for hysteresis |
| ANOMALY_ZSCORE | Statistical outlier vs rolling window | windowSec, zThreshold (default 3), minSamples |
| RATE_OF_CHANGE | Spike/drop within a window | windowSec, maxDelta |
| FLATLINE | Stuck / dead sensor signal | windowSec, epsilon |
| GOLDEN_PROFILE | Compare to known-good envelope (p05–p95) | marginPct; requires a baseline record |
| RUL | Remaining useful life trend | windowSec, limit, horizonSec |
Windowed detectors (anomaly, rate, flatline, RUL) hold a rolling sample buffer in the rule-worker RAM — use reasonable windowSec values on high-frequency tags.
Golden profile and baselines
GOLDEN_PROFILE rules compare live telemetry to a baseline envelope recorded under Baselines (/baselines). Baselines store percentile bands (p05–p95) per tag over a historical window — not manual maintenance measurements.
Rule state
| State | Meaning |
|---|---|
| NORMAL | Condition not met |
| PENDING | Condition met but not yet sustained (duration / arming) |
| TRIGGERED | Alarm active |
The seeded demo rule MOTOR_HIGH_CURRENT uses THRESHOLD: motor.current > 20 for 5 seconds.
Alarms
When a rule fires, DataHub creates an alarm record with:
- Rule reference and tag path
- Trigger value and timestamp
- Status (active, acknowledged, cleared)
Operators view and acknowledge alarms in Alarms (/alarms). Acknowledging requires the alarms.acknowledge permission.
Actions
Each rule can have one or more actions executed when the alarm fires:
| Channel | Configuration |
|---|---|
| Slack | Incoming webhook URL |
| SMTP settings in environment | |
| Telegram | Bot token and chat ID |
| HTTP | POST URL with JSON payload |
Unconfigured channels are skipped gracefully — they do not fail the action job.
The action-worker retries failed deliveries up to 3 times with exponential backoff.