[PLUS] Label Mapping is a feature exclusive to Nightingale Enterprise (PLUS).

Overview

Label Mapping = a mapping table that “injects external dimension information into event labels”.

Sidebar path: Integration Center → Label Mapping, URL /label-mappings.

Why is it needed? Alert events typically only carry machine/container hard IDs like ident=10.99.1.106 or pod=pay-svc-7f8d9-xkqzm. But the on-call group really wants to see:

• Which business/department does this machine belong to?
• Which cluster/environment is this pod in?
• Who is the owner of this alert?

By configuring dimension information maintained in external CMDB / Excel / CloudWatch (department / owner / cluster / environment, etc.) into a “label mapping”, Nightingale will automatically match by primary label and inject the corresponding fields into the alert event labels. Notification templates and dashboards can then reference them with {{.TagsMap.dept}}.

Example:

• Mapping source: the Prometheus metric node_meta{instance, dept, owner, env};
• Primary label set to instance;
• When an alert event fires with instance=10.99.1.106, the mapping auto-injects dept=infra, owner=Zhang San, env=test into the event labels.

Create / Edit a Label Mapping

The form has 2 sections:

① Basic Configuration

Field	Required	Description
Name	Yes	Recognizable name, e.g. cmdb-host-dept, k8s-pod-owner
Authorized teams	Yes (multi-select)	Which teams can manage / view this mapping, for permission isolation
Enabled	Default on	When off, the mapping content stops updating; labels already injected into events are unaffected
Notes	No	Write more — successors can understand after the mapping is paused

② Data Source

Field	Required	Description
Type	Yes	3 types: Prometheus (from metrics + labels), CSV (upload csv file), CloudWatch (AWS resource tags)
Update frequency	Yes	cron expression, default @every 10m; slow-changing CMDB data can be set to @every 1h
Configuration mode	Yes	“Use existing data source” reuses a Prometheus instance from /datasources directly; “Direct configuration” enters connection details separately (suitable for mapping data sources not in the data source list)
Data source	Yes	Shown when “Use existing” is selected
PromQL	Yes (Prometheus type)	Query statement; the returned series must carry all labels you want to map. e.g. node_meta{job="cmdb"} returns a label set {instance, dept, owner, env, ...}
Mapping label extraction	No	Pick labels to retain from query results (allowlist). All retained by default
Primary label (for mapping lookup)	Yes	Which label to use as the “lookup key” to match events. e.g. selecting instance means any event with instance=... will trigger a match

After filling, click Mapping Preview to query the data source with the current config and show the “primary label value → other labels” list — always preview before saving to confirm the results are what you want.

Key constraint for Prometheus type: PromQL must return labeled series (typically meta-info metrics like Categraf’s node_meta or cAdvisor’s kube_pod_info). If only {value=...} without labels is returned, the mapping will be empty.

CSV / CloudWatch Types

• CSV: upload a .csv file; first column is the primary label value, subsequent columns are labels to inject (first row as label names). Suitable when CMDB has no API and you temporarily maintain an Excel.
• CloudWatch: pulls from AWS resource tags, mainly for AWS environments using EC2/RDS Tags for mapping. Requires CloudWatch integration in Data Sources first.

Using in Alerts and Dashboards

After saving and the mapping takes effect (first fetch governed by “Update frequency”, at most one cycle), all subsequently triggered alert events automatically carry the injected labels. Common usage:

• Notification templates: {{.TagsMap.dept}} references the department, {{.TagsMap.owner}} displays the owner. e.g. add a line at the start of the message: On-call contact: {{.TagsMap.owner}} ({{.TagsMap.dept}}).
• Alert rule label filters: add dept = infra in the alert rule “event labels” for team-level rule isolation.
• Dashboard variables: dashboard label variables can also recognize labels injected by the mapping, for slicing/grouping displays.
• Aggregation rules: aggregation rule templates of Active Alerts can use {{.TagsMap.dept}} to consolidate all platform alerts by department.

FAQ

Q1: After saving the mapping, alert labels are not auto-injected. Why?

A: Troubleshoot in this order:

1. Timing: the mapping fetches on the “Update frequency” schedule. Just-saved configurations may not have fetched the first time yet; wait one cycle (10 min by default).
2. Primary label match: the event’s label key must exactly match the mapping’s “primary label”. If the event has only ident not instance, and the mapping is configured for instance, there’s no match.
3. PromQL really has labels: go to the data source page and run the PromQL manually to confirm the returned series have the expected labels.
4. Enable switch: the mapping must be enabled.

Q2: Mapping data updates slowly — can I manually trigger a refresh?

A: There’s no “manual refresh” button in the current UI. The only way to accelerate is to change “Update frequency” to a shorter cron. For temporary needs, set to @every 1m, refresh, then change back to normal.

Q3: With multiple mappings existing simultaneously, how does overwriting work?

A: Labels are injected by unique key. If two mappings both inject the owner key, the later-processed one overrides the earlier (by mapping ID order). Recommend designing different mappings to inject different label keys to avoid ambiguity.

Q4: How to update a CSV-type mapping? Re-upload?

A: Yes, CSV is a static snapshot. After changes in CMDB, export a new csv and re-upload. For frequently changing data, recommend Prometheus type + expose CMDB data as a metric.

References

• Data Sources (the underlying data source label mapping depends on)
• Alert Rules
• Aggregation Rules in Active Alerts