标签词表

[PLUS] 标签词表是夜莺企业版（PLUS）独有功能。

概述

标签词表 = 一份"外部维度信息注入到事件标签"的映射表。

侧栏路径：集成中心 → 标签词表，URL /label-mappings。

为什么需要它？告警事件里通常只能看到 ident=10.99.1.106、pod=pay-svc-7f8d9-xkqzm 这种机器/容器维度的硬 ID。但发到值班群里大家想看的是：

• 这台机器属于哪个业务/部门？
• 这个 pod 在哪个集群/环境？
• 这条告警的负责人是谁？

把外部 CMDB / Excel / CloudWatch 维护的维度信息（部门 / owner / 集群 / 环境等）配成"标签词表"，夜莺会自动按主标签匹配，把对应的字段注入到告警事件标签里。最终通知模板和仪表盘里都能用 {{.TagsMap.dept}} 这种引用。

举例：

• 词表来源 node_meta{instance, dept, owner, env} 这个 Prometheus 指标；
• 主标签设为 instance；
• 一条告警事件触发时 instance=10.99.1.106 ，词表自动把 dept=基础平台、owner=张三、env=test 注入到事件标签里。

新建 / 编辑标签词表

表单分为 2 个区域：

① 基础配置

字段	必填	说明
名称	是	词表辨识名，建议见名知意，如 cmdb-host-dept、k8s-pod-owner
授权团队	是（多选）	哪些团队可以管理 / 查看这份词表，做权限隔离
启用	默认开	关掉后不再更新词表内容，已注入到事件里的标签不受影响
备注	否	多写一点 — 词表关停后接手人能看懂

② 数据来源

字段	必填	说明
类型	是	3 种：Prometheus（从指标 + label 中取）、CSV（上传 csv 文件）、CloudWatch（AWS 资源标签）
更新词表频率	是	cron 表达式，默认 @every 10m；CMDB 数据更新慢的可以放到 @every 1h
配置方式	是	“使用已有数据源” 直接复用 /datasources 里的 Prometheus 实例；“直接配置” 单独填一份连接信息（适用于词表数据源不进数据源列表的场景）
数据源	是	配置方式选"使用已有"时显示
PromQL	是（Prometheus 类型）	查询语句，要让返回的时序带有你要做映射的所有 label。例：node_meta{job="cmdb"} 返回标签集合 {instance, dept, owner, env, ...}
词表标签提取	否	选要从查询结果里保留的标签（白名单）。不选默认全部保留
主标签（用于查词表）	是	用哪个标签当"查询键"匹配事件。例：选 instance，则事件里只要有 instance=... 就会触发匹配

填好后点 词表预览 按钮，会用当前配置去查一次数据源，把"主标签值 → 其他标签"的映射列表展示出来 — 保存前一定先预览，确认结果是不是你想要的。

Prometheus 类型的关键约束：PromQL 必须返回有标签的时序（一般是元信息指标，如 Categraf 的 node_meta 或 cAdvisor 的 kube_pod_info）。如果只返回 {value=...} 没有标签，词表会是空的。

CSV / CloudWatch 类型

• CSV：上传一份 .csv 文件，第一列是主标签值，后续列是要注入的标签（首行作为标签名）。适合 CMDB 没接口、临时维护一份 Excel 的情况。
• CloudWatch：从 AWS 资源标签拉取，主要适合 AWS 环境下用 EC2/RDS Tag 做映射。需要先在 数据源 里配好 CloudWatch 接入。

在告警和仪表盘里使用

词表保存并生效后（首次抓取由"更新词表频率"决定，最长等一个周期），所有后续触发的告警事件都会自动带上注入的标签。常见用法：

• 通知模板：{{.TagsMap.dept}} 引用部门、{{.TagsMap.owner}} 显示负责人。例：消息开头加一行 值班联系：{{.TagsMap.owner}} ({{.TagsMap.dept}})。
• 告警规则的标签过滤：在告警规则的"事件标签"里加 dept = 基础平台，可以做团队级别的规则隔离。
• 仪表盘变量：仪表盘的 label 变量也能识别词表注入的标签，用于切片/分组展示。
• 聚合规则：活跃告警 的聚合规则模板可以用 {{.TagsMap.dept}} 把整个平台告警按部门收敛。

常见问题

Q1：词表保存后告警标签没自动注入，为什么？

A：按这个顺序排查：

1. 时机：词表是按"更新词表频率"定时抓取的。刚保存可能还没抓第一次，等一个周期再看（默认 10 分钟）。
2. 主标签匹配：告警事件里的标签 key 要和词表的"主标签"完全一致。如果事件里只有 ident 没有 instance，词表是按 instance 配的，就匹配不上。
3. PromQL 是否真的有标签：进数据源页面手工跑一下 PromQL，确认返回时序带有期望的标签。
4. 启用开关：词表必须是启用状态。

Q2：词表数据更新慢，能不能手工触发立刻刷新？

A：当前 UI 没有"手工刷新"按钮，只能改"更新词表频率"为更短的 cron 来加速一次。临时需求建议改成 @every 1m，刷新后再改回正常频率。

Q3：多个词表同时存在，覆盖关系怎么算？

A：标签按 key 唯一注入。如果两个词表都注入了 owner 这个 key，后处理的覆盖先处理的（按词表 ID 顺序）。建议设计上让不同词表注入不同的标签 key，避免歧义。

Q4：CSV 类型的词表怎么更新？要重新上传吗？

A：是的，CSV 是静态快照。改了 CMDB 后导出新 csv 重新上传即可。如果是高频变化的数据，推荐用 Prometheus 类型 + 把 CMDB 数据 expose 成一个 metric。

参考资料

• 数据源（标签词表依赖的底层数据源）
• 告警规则
• 活跃告警的聚合规则