monitor.alert-mute

def mute_alert(kind: str, under_maintenance: bool, firing_kinds: Sequence[str], policy: MutePolicy) -> AlertMute

@dataclass(frozen=True)
class MutePolicy:
    """What holds an alert back."""

    #: the kinds held back while their component is under maintenance
    maintenance: List[str]
    #: checked in order; the first that applies names the inhibitor
    inhibit: List[Inhibition]

@dataclass(frozen=True)
class Inhibition:
    """While an alert of kind source fires on a component, alerts of kind target on the same component are held back."""

    source: str
    #: not the same as source
    target: str

MuteReason = Literal["maintenance", "inhibited"]

@dataclass(frozen=True)
class AlertMute:
    """Whether to hold the alert back, and why."""

    muted: bool
    #: maintenance wins over inhibited; null when not muted
    reason: Optional[MuteReason]
    #: the firing kind that inhibits it; null unless inhibited
    by: Optional[str]

from fune.monitor.alert_mute import mute_alert  # monitor.alert-mute@^1

from typing import Sequence

from .monitor_alert_mute_types import AlertMute, MutePolicy


def mute_alert(kind: str, under_maintenance: bool, firing_kinds: Sequence[str], policy: MutePolicy) -> AlertMute:
    """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 and not muted` to
    monitor.alert-state."""
    if kind == "":
        raise ValueError("kind must not be empty")
    for k in policy.maintenance:
        if k == "":
            raise ValueError("maintenance kinds must not be empty")
    for rule in policy.inhibit:
        if rule.source == "":
            raise ValueError("inhibition source must not be empty")
        if rule.target == "":
            raise ValueError("inhibition target must not be empty")
        if rule.source == rule.target:
            raise ValueError("an alert kind cannot inhibit itself: %s" % (rule.source,))
    if under_maintenance and kind in policy.maintenance:
        return AlertMute(muted=True, reason="maintenance", by=None)
    for rule in policy.inhibit:
        # source != target, so an alert listed among firingKinds never inhibits itself.
        if rule.target == kind and rule.source in firing_kinds:
            return AlertMute(muted=True, reason="inhibited", by=rule.source)
    return AlertMute(muted=False, reason=None, by=None)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./monitor.alert-mute-1.0.0-python.fune, or fetch it from a terminal with fune pull monitor.alert-mute@1.0.0:python.

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