> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Labels Annotations
> Explains Prometheus alert labels versus annotations and best practices for routing, grouping, and human readable notification content
Labels and annotations are two distinct parts of a Prometheus alert definition. Use labels to identify, group, and route alerts in Alertmanager. Use annotations to attach human-readable details (descriptions, runbooks, links) that appear in notifications.
## Labels
Labels are key/value pairs that become part of an alert's identity. Alertmanager uses labels for routing, grouping, deduplication, and inhibition. To assign labels to an alert, include a `labels` block in the rule and add the relevant key/value pairs.
Example — adding severity labels to rule definitions:
```yaml theme={null}
groups:
- name: node
rules:
- alert: NodeDown
expr: up{job="node"} == 0
labels:
severity: warning
- alert: MultipleNodesDown
expr: avg_without(instance)(up{job="node"}) <= 0.5
labels:
severity: critical
```
Labels affect alert identity, deduplication, grouping, and routing in Alertmanager. Use them for any matching or routing logic.
## Annotations
Annotations are intended for human-readable information included in notifications. They do not change an alert’s identity and therefore cannot be used for routing or matching in Alertmanager. Typical uses are descriptions, runbook links, and diagnostic hints.
Annotations support templating using the Go template language. When writing templates, reference alert fields via the `alert` object. Because MDX and other processors can misinterpret template braces, always wrap template expressions in inline code or fenced code blocks.
Common template fields:
* `{{ .Labels }}` — the full labels map
* `{{ .Labels.instance }}` — the `instance` label value
* `{{ .Value }}` — the firing sample value (the metric value that caused the alert to fire)
Example — using an annotation to provide a human-readable description:
```yaml theme={null}
groups:
- name: node
rules:
- alert: node_filesystem_free_percent
expr: 100 * node_filesystem_free_bytes{job="node"} / node_filesystem_size_bytes{job="node"} < 70
annotations:
description: "filesystem {{ .Labels.device }} on {{ .Labels.instance }} is low on space, current available space is {{ .Value }}"
```
When this alert fires the `description` will be rendered with concrete values, for example:
filesystem `/dev/sda3` on `10.0.0.5:9100` is low on space, current available space is `20.40345`.
Remember: use `{{ .Labels }}` (capital L) and `{{ .Value }}` (capital V) in templates. Labels are used by Alertmanager for routing; annotations are only for notification content and will not affect routing or matching.
## Labels vs Annotations — Quick Comparison
| Concept | Purpose | Example |
| ----------: | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Labels | Used for alert identity, routing, grouping, deduplication in Alertmanager | `severity: critical` |
| Annotations | Human-readable notification content (descriptions, runbooks, links); templated with Go templates | `description: "disk {{ .Labels.device }} on {{ .Labels.instance }} is low"` |
## Best Practices
* Keep labels stable and meaningful (e.g., `severity`, `team`, `service`) so routing rules remain predictable.
* Avoid putting large or frequently-changing text in labels — use annotations for verbose or dynamic content.
* Template annotations to include contextual details (`instance`, `device`, metric value) so notifications are actionable.
* Test templates with sample alerts to ensure correct rendering and escaping.
## Links and References
* [Alertmanager — Prometheus Alerting](https://prometheus.io/docs/alerting/latest/alertmanager/)
* [Prometheus Alerting Rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
* [Go text/template package](https://pkg.go.dev/text/template)
* [MDX Documentation](https://mdxjs.com/)