NAME
bi-alert - check the measures of saved Database::BI canvases against thresholds
SYNOPSIS
bi-alert --analysis <id> [--analysis <id> ...]
[--threshold <alias>:<op>:<value>] [--threshold <analysis>:<alias>:<op>:<value> ...]
[--suppress <duration>] [--state-file <path>] [--recovery]
[--notify-cmd <command>]
[--model-dir <dir>] [--data-dir <dir>] [--dry-run]
DESCRIPTION
Works out the measures of one or more saved canvases (analyses), prints a digest of each to STDOUT, and exits 1 when a threshold is crossed. It sends nothing anywhere unless told to: pipe STDOUT into mail or a webhook, or give --notify-cmd. Scheduling is cron's.
Each (analysis, threshold) pair is a check of its own, with its own line, its own throttle and its own recovery. --suppress announces a crossing at most once a period; --recovery announces the end of one too. Their memory is a small JSON file in the model folder, written only when either is used.
bi-alert --analysis abc123 --threshold count:gt:1000 --suppress 1h \
--notify-cmd 'mail -s "$BI_ALERT_SUBJECT" oncall@example.com'
--notify-cmd runs through the shell once per run, only when something is announced, with the run's text on STDIN and BI_ALERT_EVENT (crossed or recovery), BI_ALERT_SUBJECT and BI_ALERT_MESSAGE_FILE in its environment. bi-alert --help lists every detail.
OPTIONS
- --analysis, -a id
-
A saved canvas. Required, and repeatable.
- --threshold, -t measure:op:value
-
A measure alias, an operator (
gt ge lt le eq ne) and a value. Repeatable; prefix it with<analysis>:to check an analysis other than the first. - --suppress, -s duration
-
Announce a threshold at most once per period (
30,30s,15m,6h,2d,1w). - --state-file path
-
Where the throttle keeps its memory (default: <model-dir>/alerts-state.json).
- --recovery, -r
-
Announce the end of a crossing as well as its start (exit 3).
- --notify-cmd command
-
Run this when something is announced.
- --model-dir, -m dir
-
The folder holding analyses.json (default: .bi).
- --data-dir, -d dir
-
The data folder (default: data).
- --dry-run, -n
-
Report only: record nothing and run no command.
- --help, -h
-
Show the full usage.
EXIT STATUS
0 when nothing is announced, 1 when a crossing is announced, 2 on an error, 3 when only a recovery is announced (1 wins when a run announces both).
AUTHOR
Nigel Horne <njh@nigelhorne.com>
LICENCE AND COPYRIGHT
Copyright 2026 Nigel Horne.
Usage is subject to the GPL2 licence terms. If you use it, please let me know.