Alert Verb vs Noun Patterns

How alerts name themselves. Verbs vs nouns.

The pattern

Alert names should describe what is happening, not what is being measured. Verbs over nouns: checkout-api-down is better than checkout-api-availability; disk-filling-fast is better than disk-utilization. Verbs tell the on-call what to do; nouns tell the on-call only what to check.

• Verbs over nouns. Alert names describe what is happening, not what is being measured.
• Action over observation. Verbs tell the on-call what to do; nouns tell the on-call only what to check.
• Concrete examples. checkout-api-down beats checkout-api-availability; disk-filling-fast beats disk-utilization.
• Per-team naming convention. The verb-over-noun rule committed to the alerting style guide; supports consistency.

Naming rules

The naming rules are simple and worth enforcing. Subject-verb structure, no obscure abbreviations, lowercase kebab-case with a 5-word ceiling. The name appears in 30 places (PagerDuty, Slack, JIRA, postmortems), and brevity at every reading site compounds.

• Subject-verb structure. checkout-latency-high, queue-depth-growing, replication-lag-breaking-rpo.
• No obscure abbreviations. Well-known terms only (RPO, SLO, p99); db-conn-exh is not faster than db-connection-pool-exhausted.
• Lowercase kebab-case, max 5 words. Brevity matters; the name appears in 30 places.
• Per-name lint rule. CI checks new alerts against the naming convention; catches violations at PR time.

Why this matters

Verb-named alerts are searchable, self-documenting, and unambiguous in postmortems. Engineers searching for "high checkout latency" find the right alert; a new on-call reading replication-lag-breaking-rpo learns what the team cares about without opening a runbook.

• Searchable. Engineers searching for "high checkout latency" find the right alert when names use verbs.
• Self-documenting. A new on-call reading replication-lag-breaking-rpo learns what the team cares about without opening a runbook.
• Postmortem clarity. "Alert: queue-depth-growing" is clearer than "alert on queue depth".
• Per-incident comprehension. The on-call reading the page understands the situation in 5 seconds; supports faster response.

Anti-patterns

Common anti-patterns survive for years if not caught. Generic names like alert1 or REVIEW THIS; names containing threshold values that rot when thresholds change; names coupled to org structure that changes more often than the alert itself.

• Generic placeholders. alert1, my-cool-alert, REVIEW THIS; they survive for years if not caught.
• Threshold in name. cpu-above-80 rots when the threshold changes; use cpu-above-threshold.
• Team name in alert. platform-team-disk-alert couples the alert to org structure that changes more often than the alert itself.
• Per-anti-pattern lint. CI catches the common anti-patterns; the discipline lives in the linter, not just the style guide.

How to apply

Apply the rule by audit, by convention, and by careful migration. Rename anything that describes a metric instead of a problem; add the convention to the style guide and block non-conforming PRs; rename in batches and preserve old aliases for 30 days so dashboards keep working.

• Audit existing catalog. Rename anything that describes a metric instead of a problem.
• Convention in style guide. Add the naming rule to the alerting style guide; block PRs that don’t follow it.
• Batch renames with aliases. Rename in batches; preserve old aliases for 30 days so dashboards keep working.
• Per-rename communication. Slack message to consumers when an alert renames; supports the dashboard owners on the other side.