monitor.alert-mute

export function muteAlert(kind: string, underMaintenance: boolean, firingKinds: readonly string[], policy: MutePolicy): AlertMute

/** What holds an alert back. */
export interface MutePolicy {
  /** the kinds held back while their component is under maintenance */
  readonly maintenance: readonly string[];
  /** checked in order; the first that applies names the inhibitor */
  readonly inhibit: readonly Inhibition[];
}

/** While an alert of kind source fires on a component, alerts of kind target on the same component are held back. */
export interface Inhibition {
  readonly source: string;
  /** not the same as source */
  readonly target: string;
}

export type MuteReason = "maintenance" | "inhibited";

/** Whether to hold the alert back, and why. */
export interface AlertMute {
  readonly muted: boolean;
  /** maintenance wins over inhibited; null when not muted */
  readonly reason: MuteReason | null;
  /** the firing kind that inhibits it; null unless inhibited */
  readonly by: string | null;
}

import { muteAlert } from "#fune/monitor.alert-mute@^1";

import { type AlertMute, type MutePolicy } from "./monitor_alert_mute_types.ts";

/**
 * Hold an alert back, as Alertmanager's silences and inhibit rules do: during
 * its component's maintenance if its kind is one maintenance mutes, or while
 * an alert that inhibits it fires on the same component. The whole policy is
 * checked every time, so a mistake in it fails loudly rather than silently
 * never muting. The caller passes `condition && !muted` to monitor.alert-state.
 */
export function muteAlert(kind: string, underMaintenance: boolean, firingKinds: readonly string[], policy: MutePolicy): AlertMute {
  if (kind === "") throw new RangeError("kind must not be empty");
  for (const k of policy.maintenance) {
    if (k === "") throw new RangeError("maintenance kinds must not be empty");
  }
  for (const rule of policy.inhibit) {
    if (rule.source === "") throw new RangeError("inhibition source must not be empty");
    if (rule.target === "") throw new RangeError("inhibition target must not be empty");
    if (rule.source === rule.target) throw new RangeError(`an alert kind cannot inhibit itself: ${rule.source}`);
  }
  if (underMaintenance && policy.maintenance.includes(kind)) return { muted: true, reason: "maintenance", by: null };
  for (const rule of policy.inhibit) {
    // source !== target, so an alert listed among firingKinds never inhibits itself.
    if (rule.target === kind && firingKinds.includes(rule.source)) return { muted: true, reason: "inhibited", by: rule.source };
  }
  return { muted: false, reason: null, by: null };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add monitor.alert-mute

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./monitor.alert-mute-1.0.0-typescript.fune, or fetch it from a terminal with fune pull monitor.alert-mute@1.0.0:typescript.

The whole function, every language, is one file too: monitor.alert-mute-1.0.0.fune, 17,962 bytes, sha256 2ff913849ec88695dff7947db041136c9efcfe0adce2756ea7e73ae57951391b. It installs into a project of any language.

// fune: before monitor.alert-mute

// fune: after monitor.alert-mute

// fune: step monitor.alert-mute after <n|label>

More from the author

Pass the result on as the condition of `monitor.alert-state`: `condition and not muted`. A muted alert behaves as if its condition were false: it never fires, and one already firing resolves after its `clearForSeconds`, as the down alert does when a component goes into maintenance.

## Why it is shaped this way

- **Kinds are strings the caller chooses** (`down`, `latency`, `burn-rate`, `cert-critical`), matched exactly. The policy is data, usually read from the project's config, so a new kind of alert needs no new version. - **Maintenance lists what it mutes**, rather than muting everything: a certificate that is about to expire is not planned work, and should still alert during a database upgrade. - **Maintenance wins over inhibition** and `by` stays null, since the maintenance window is the reason that holds for the whole period. - **Inhibitions are checked in policy order**, not in the order the firing kinds arrive, so the answer does not depend on how the caller collected them. - **An alert never inhibits itself**: `source` and `target` must differ, so a kind listed in `firingKinds` for itself changes nothing. - **The whole policy is checked on every call**, even when the first maintenance kind already decides it. A mistake in the policy fails loudly instead of silently never muting. - Inhibition is per component (Alertmanager's `equal: [component]`): the caller passes only the kinds firing on the alert's own component.

## Errors

- `kind must not be empty` - `maintenance kinds must not be empty` - `inhibition source must not be empty` - `inhibition target must not be empty` - `an alert kind cannot inhibit itself: X`

## Sources

Prometheus Alertmanager: silences and inhibition (https://prometheus.io/docs/alerting/latest/alertmanager/#inhibition) and `inhibit_rules` in the configuration reference (https://prometheus.io/docs/alerting/latest/configuration/#inhibit_rule).

Files