Skip to content
KloudMate Docs

Annotations & Severity

Annotations are key-value pairs you attach to an alert. They flow into notifications and incidents along with the alert itself.

Annotation values support Liquid templating, so you can pull live data from the firing alert into the notification text. The reserved key severity drives how incident-management and routing tools prioritize the alert.

Where to find annotations

Section titled “Where to find annotations”

Annotations live in the Responder context section of the alert rule editor. The pre-defined annotation keys are:

  • Severity: free-form severity string, for example sev1, critical, or p1. Plain text or a Liquid template.
  • Summary: the alert headline in notifications. Supports templates.
  • Dashboard: pick a workspace dashboard to link from the notification.
  • Panel: when a dashboard is picked, narrows the link to a specific panel.
  • Playbook URL: link to the runbook responders should follow. Supports templates.

Any other key is a custom annotation. Click Add Annotation to add one.

Add a custom annotation

Section titled “Add a custom annotation”

  1. Open the rule editor. Scroll to Responder context and expand Custom annotations.

  2. Click Add Annotation.

  3. Provide a key. Use any string, for example service_owner, region, or runbook_section.

  4. Provide a value. This can be static text (payments-team) or a Liquid template ({{ labels.service }} is degraded).

  5. Save the rule. Annotation values render at notification time, not at save time. See Failure mode below.

Using Liquid templates

Section titled “Using Liquid templates”

You can interpolate live alert data into any annotation value with the {{ }} syntax. The render context shape is:

{
  "labels": {
    "service": "checkout-api",
    "env": "prod"
    // ...plus any user-defined label keys from query dimensions or folders
  },
  "state": {
    "current_state": "Alerting",
    "resolved": false,
    "started_at": "2026-05-19T12:00:00Z",
    "value": 0.05,                          // the evaluated value of the condition node
    "values": { "A": 1000, "B": 50 }        // raw outputs of each query/expression node
  },
  "rule": {
    "id": "alm_abc123",
    "name": "High error rate",
    "description": "Error rate ratio vs request volume"
  }
}

Common references

Section titled “Common references”
  • {{ labels.service }}: the value of the service label on the firing instance.
  • {{ state.value }}: the evaluated number that crossed the threshold.
  • {{ state.values.A }}, {{ state.values.B }}: raw outputs of each query or expression node (by node ID).
  • {{ state.current_state }}: Alerting, Normal, and so on.
  • {{ state.resolved }}: boolean, useful in {% if state.resolved %}…{% endif %} branches.
  • {{ rule.name }}, {{ rule.id }}: the alert rule’s name and id. Prefer these over labels.alarm_id / labels.alarm_name, which aren’t available at render time.

Example: contextual summary

Section titled “Example: contextual summary”

If you watch CPU utilization with query A grouped by host_name, you might write:

  • Key: Description
  • Value: Host {{ labels.host_name }} is at {{ state.value }}% CPU.

When the alert fires for web-server-01 at 95%, the notification reads: Host web-server-01 is at 95% CPU.

Testing a template

Section titled “Testing a template”

Click Test template on any templated value field to preview how it renders:

  • It opens with your current template loaded.
  • Edit the sample labels, state, and rule JSON the template renders against.
  • Click Test to preview the rendered output. Any parse errors are shown so you can fix them before saving.

Testing is optional; KloudMate doesn’t validate templates on save. If a template can’t render at notification time, KloudMate falls back to the raw template string rather than dropping the notification.

Failure mode

Section titled “Failure mode”
  • A broken template stays in the value field as-is when you save.
  • At render time, a parse failure makes that single annotation surface the raw template text instead of an evaluated value.
  • Other annotations on the same alert keep rendering normally.

This fail-soft behavior is intentional: a typo shouldn’t silence a real incident.

Dynamic severity

Section titled “Dynamic severity”

Severity flows out of the reserved severity annotation. It’s a string that downstream notification channels and incident-management tools use to prioritize the alert. Combine Liquid with if / elsif to compute severity from the firing value.

Example: severity by threshold

Section titled “Example: severity by threshold”

Suppose query B is an error-rate ratio. You want:

  • Error rate > 10% → critical
  • Error rate > 5% → warning
  • Anything below that → info

Set the severity annotation value to:

{% if state.value > 0.1 %}critical{% elsif state.value > 0.05 %}warning{% else %}info{% endif %}

At notification time, KloudMate evaluates the template against the firing alert’s state and writes the resolved string into the outgoing payload.

Severity vs. tags

Section titled “Severity vs. tags”

Earlier versions of KloudMate routed by notification tags on the rule. Tags are gone now, replaced by:

  • Labels: auto-derived from query dimensions and folders. These are what Routing Rules match against.
  • Annotations: human-readable context that flows into the notification.
  • Severity: the reserved annotation key, free-form, optionally Liquid-templated.

If you used to route by tag, switch to a routing rule that matches on the equivalent label (for example, service=checkout-api).

Section titled “Related”