Relabel processor — rewrite alert event labels: drop, keep, rename, combine, or modify label values.
Overview
The Relabel event processor is an important step in Nightingale’s alert notification flow that rewrites and processes event labels. Its functionality is similar to relabeling on the ingestion side: it lets you perform various operations on alert event labels, including dropping, keeping, renaming, merging, and modifying label values.
Main Features
- Label drop: remove unwanted labels (labeldrop)
- Label keep: keep only specified labels (labelkeep)
- Label rename: rename label keys (labelmap)
- Label merge: build new labels from existing labels (replace)
- Value modify: modify the value of a label (replace)
Steps
1. Choose the processor type
On the alert rule configuration page, select Relabel as the processor type.
2. Configure the action
Pick the appropriate Action based on need:
- Drop labels:
labeldrop - Keep labels:
labelkeep - Rename labels:
labelmap - Modify / build labels:
replace
3. Configure the match condition
Set a regex match condition for the label key in the regex field.
4. Set the replacement (if needed)
Configure replacement, target_label, etc. according to the chosen action.
5. Test
After saving, new alert events will be processed according to the configured rules.
Examples and Use Cases
Case 1: drop unwanted labels
In the alert event above, there are many labels. If we don’t care about some of them, we can use labeldrop to remove them — e.g. to drop listening_10 and host:
Parameters:
- Action:
labeldrop - Regex:
listening_10|host
After saving, listening_10 and host are removed.
Case 2: keep only specific labels
The event above has many labels; to keep only the ones we care about, use labelkeep. For example, to keep only service, name, and addr:
Parameters:
- Action:
labelkeep - Regex:
service|^name$|addr
Note:
^name$is used to strict-match because other labels also contain “name”.
After saving, only service|name|addr are kept on new alert events.
Case 3: rename a label key
To rename __name__ to name, configure:
Parameters:
- Action:
labelmap - Regex:
__(name)__ - Replacement:
$1or fixed valuename
After the new name label is added, the original __name__ label is still kept. You need another labeldrop to remove it.
After saving, __name__ becomes name on new alert events.
Case 4: build a new label
To build a new label combining ident and listening_10 from the alert event above, use replace:
Parameters:
- Action:
replace - Target_label:
addr - Source_labels:
["ident", "listening_10"] - Separator:
:
After saving, the new alert event has a new addr label.
Case 5: modify a label value
To modify the addr label and drop the port part, use replace:
Parameters:
- Action:
replace - Target_label:
addr - Source_labels:
["addr"] - Regex:
([^:]+):.* - Replacement:
${1}
After saving, the port is dropped from addr on new alert events.
Common Use Cases
1. Label cleanup
Clean up redundant labels and keep only the core business-relevant labels.
2. Label normalization
Standardize label naming conventions by renaming non-standard keys to standard format.
3. Environment distinction
Combine labels to build a new label that includes environment info for easier alert classification.
4. Sensitive information handling
Remove or rewrite labels that contain sensitive information.
Notes
- Regex: all match conditions support regex — make sure the syntax is correct
- Order: multiple relabel operations execute in configured order — watch out for dependencies between them
- Label retention:
labelmapkeeps the original label; add an extralabeldropif needed - Test thoroughly: test before using in production
- Performance: complex regex can hurt performance; keep match conditions optimized
FAQ
Q1: I configured Relabel but the alert event labels did not change. How do I debug?
A: Check in this order:
- Match condition: the most likely culprit is a wrong regex — use Metric Explorer to view actual event labels and cross-check the regex;
- Wrong action:
labelmapdoes not delete the original label — configure anotherlabeldrop; - Processor order: in the “Pipeline configuration” of the alert rule, the relabel processor must be placed before the notification node;
- Timing: Relabel processes newly triggered events; existing events are not retroactively rewritten.
Q2: When labelkeep and labeldrop are both configured, which takes priority?
A: They execute in the order configured on the processor. labeldrop then labelkeep means “drop some, then keep some” — the final result is the intersection. Avoid using both — pick the one with clearer semantics.
Q3: How do I write regex when label values contain special characters ([], {}, spaces)?
A:
- Escape special characters in the regex:
\[,\{,\(spaces usually don’t need escaping); - Or use the more lenient
.*; - Use
^and$to anchor and avoid accidental matches, e.g.^name$for exact match.
Q4: Can I extract part of one label’s value into a new label?
A: Yes — use replace with a regex capture group:
Action: replace
Source_labels: [original_label]
Regex: ^([a-z]+)-(\d+)$ # 捕获前缀和数字
Target_label: prefix
Replacement: ${1} # 引用第 1 个捕获组
Effect: original_label=web-01 → new label prefix=web.
