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.