Monitors

A monitor is Muster's record of one task: how often it is expected to report in, how much lateness to tolerate, and where to send alerts. Monitors come from two places. A connected Laravel application creates one automatically for each scheduled command on its first run. You can also create one by hand for anything else that can send an HTTP request.

States

A disabled monitor shows Disabled in the list instead of its status.

monitors:evaluate runs every minute on the scheduler. It looks at every enabled monitor that has a due time and moves it to late once the due time has passed, then to missed once the grace period has passed too. A monitor can go straight through late into missed in a single pass if both thresholds are already behind it. Muster records a late and a missed event in the monitor's history as it goes.

A check-in that arrives after a monitor went missed brings it back. Muster records a recovered event and sends the recovery alert to any channel that alerted for the incident.

Cadence and grace

Two numbers control a monitor:

• Cadence: how many seconds between expected check-ins. The form defaults to 300.
• Grace period: how many extra seconds to tolerate before calling it missed. The form defaults to 60. A job that usually takes four minutes needs a grace period longer than four minutes.

Both accept whole seconds up to one year (31,536,000).

For a monitor registered by a connected application, Muster derives the cadence from the command's cron expression and timezone every time the command starts, and computes the next due time from the expression. You never set a cadence by hand for a connected command; any value you type is replaced on the next run. The grace period starts at 60 seconds and is yours to change.

For a monitor you created by hand, each heartbeat sets the next due time to the check-in time plus the cadence.

The monitors list

/monitors lists every monitor by name. Each row shows the cron expression for a connected command, or Every Ns + Ns grace for a hand-made monitor, and the current status.

Creating a monitor

Select New monitor. Give it a name, a cadence and a grace period, and optionally configure email and webhook alerts (see Alerts and the weekly digest). After saving you land on the monitor's page. Note its id from the address bar: the heartbeat route uses it.

A new monitor is pending until its first check-in. See Connecting your apps for how to send one.

The monitor page

A monitor's page shows its status, expected cadence, grace period, last check-in, next due time, last exit code and last runtime, and its alert settings. For a connected command it also shows the command, cron expression and timezone, and any runs that have started and not finished, under Open executions.

Activity history lists the recorded events, newest first: check_in, started, finished, non_zero_exit, skipped, late, missed and recovered, with exit code and runtime where the run reported them.

Muster keeps roughly the last hundred events per monitor, plus failures from the current and previous week, and prunes older ones. It is a monitor, not an archive.

Editing, enabling and disabling

Edit monitor opens the same form as creation. Disable monitor stops Muster evaluating the monitor and stops it accepting heartbeats; Enable monitor turns it back on.

There is no delete. When you no longer want a monitor, disable it.

How a connected command is identified

A connected command's monitor is identified by the exact command string alone. Changing only the schedule updates the existing monitor. Changing the command itself, including its arguments, makes it a new task as far as Muster is concerned: it gets a new monitor and the old one stays behind. Disable the old one.

Because the command string is how Muster recognises a task, Muster stores it and shows it in the UI and in the weekly digest. Do not put passwords or API keys in the command-line arguments of scheduled commands you connect.