AlertRule Spec

An AlertRule is a resource with three top-level keys. Everr validates it on everr apply; reads return the spec exactly as it was stored at apply time, with no re-validation. The spec holds a ClickHouse query, a threshold condition, and the notification text to send when instances start and stop firing. The query always returns its useful data; the condition decides which rows fire.

kind: AlertRule
metadata:
  name: <slug>
spec:
  { ... }

spec

Ownership is keyed by the rule's canonical name (<project>/<slug>) and its first-class Repoid. A rule under another Repoid with a name your config declares is an ownership conflict at apply time: everr apply fails fast unless run with --adopt, which transfers the rule in place. A rule owned by your Repoid is part of that config: apply updates it when the spec drifts and prunes it if no YAML file declares it.

Notification destination

By default, an alert delivers to the Organization's default destination (see set up notifications). Set notifications.channels when a rule has its own destination that should override it:

spec:
  notifications:
    channels: [team-slack, primary-on-call]

The channel names reference existing Organization channels. Configuration and secrets stay with the channels and are not copied into the alert definition. Direct notifications use the same fixed grouping: instances batch by rule and severity. Omitting notifications restores the default destination. Preview alerts remain suppressed even when they declare their own destination.

Message templating

notificationMessage.title and notificationMessage.description support ${...} placeholders, substituted per firing instance when the notification is rendered:

• ${<column>} expands to that instance's value for any column the query returns: an instanceLabels column resolves from the instance's labels, and every other column resolves from the event's evidence (the source row's remaining columns).
• ${value} expands to the matching row's required numeric value column.

Referencing a column the query does not return is an apply-time error. A missing, null, empty, or non-numeric value does not match the condition.

Evidence is capped: an event carries at most 16 non-label columns, and only while their compact JSON stays under 4096 bytes; past the caps, refs to non-label columns may render empty (apply warns when a message depends on columns beyond the 16-column cap). The query SQL itself does not support templating, placeholders work only in the notification message fields.

Manifest

The apply identity (the repoid) is inferred automatically from the repository's origin git remote, normalized to the slug host/owner/repo: scheme, credentials, port, a trailing .git, and trailing slashes are stripped and the result is lowercased. For example, git@github.com:Acme/API.git becomes github.com/acme/api. Equivalent ssh, https, and scp clone URLs collapse to the same identity, so one repo means one boundary.

No manifest file is needed when the repo has an origin remote. An optional everr.yaml (or everr.yml) at the apply root overrides the inferred identity. It accepts exactly one key:

# everr/everr.yaml
repoid: "my-explicit-id"

If there is neither an origin remote nor an everr.yaml manifest, apply errors and tells you to add a remote or create everr.yaml.

Declarations sit flat in everr/, named by kind: *.alert.yaml, *.dashboard.yaml, and *.runbook.yaml (the legacy *.notebook.yaml suffix is still recognized). everr apply ./everr discovers every kind: Dashboard, kind: AlertRule, and kind: Runbook document under the directory and makes the live resources for that repoid exactly match the tree: new documents are created, changed ones updated, and removed ones deleted. The kind suffix is a naming convention only; apply routes by the kind: field. Use --preview to stage the changes for review without touching the live state (preview rules evaluate but never notify). See the everr apply reference.

Constraints and errors

• evaluationInterval must be ≥ 1m.
• for must be a valid duration (0s is allowed).
• resolveAfter must be an integer ≥ 1.
• severity, when set, must be info, warning, or critical.
• notificationMessage.title is required and non-empty.
• notifications.channels must contain unique, non-empty names. A named channel that does not exist produces an apply warning.
• ${...} in messages must reference a column the query returns or be ${value}.
• query must return a numeric column named value.
• condition.operator must be gt, gte, lt, lte, eq, or neq; condition.threshold must be a finite number.
• instanceLabels entries must each be a column the query returns. An empty list is valid and means the whole result is one instance.
• query rejects ${...}.
• maxInterval, when set, must be a valid duration and, when evaluationInterval also parses, greater than or equal to it.
• annotations keys starting with everr., and the exact keys summary, description, link.alert, and link.runbook, are rejected: those are reserved for Everr's own generated annotations.
• Supported document kinds for apply are Dashboard, AlertRule, and Runbook.