Loading

Tags and runbooks in the experimental alerting system (Alert mode only)

Tags and runbooks are optional artifacts for Alert-mode rules in the experimental alerting system.

  • Tags: Free-form labels for filtering and organization. A rule can have up to 20 tags, each up to 128 characters.
  • Runbooks: An investigation guide stored with the rule so responders have context when alerts are generated.

Configure tags when:

  • You want to filter episodes by team, environment, or severity tier on the Alerts page (find Alerting V2 Preview in the navigation menu or global search, then go to Alerts) without writing a custom KQL query each time.
  • You are using action policies and want to match episodes by ownership or category rather than by rule name. Tags are inherited by alert episodes, so any tag you add to a rule is available as a KQL matcher in action policies.
  • You manage many rules and need a consistent labeling scheme to track which team owns which alerts.

Configure a runbook when:

  • Responders who aren't familiar with the service might need to triage the alert. A runbook surfaces triage steps directly alongside the alert without requiring a separate search.
  • The alert requires a consistent response process that you want encoded and version-controlled alongside the rule.

Skip tags and runbooks when:

  • The rule is in Signal mode. Tags and runbooks are Alert-mode-only artifacts and have no effect on signal document output.
  • The rule is experimental or not yet part of a monitored production system.

Tags let you filter alerts by team, environment, or severity tier. For a checkout service rule, you might add tags like:

  • team:payments
  • env:production
  • sev:p1

On-call engineers can then narrow the Alerts page to rules their team owns without scanning every active episode.

A runbook gives responders immediate context when an alert fires. Write it as markdown so it renders correctly in the rule detail view. Include enough detail that an engineer unfamiliar with the service can triage without asking for help.

Fires when checkout error rate exceeds 10% for 3 consecutive evaluations.

Triage steps:
1. Check the checkout service deployment history in the last 30 minutes.
2. Review the error breakdown dashboard: https://kibana.example.com/dashboards/checkout-errors
3. If errors are concentrated in one region, escalate to the infra team.
4. If errors are global, page the payments on-call lead.