value mappings是grafana中将原始数值一对一或按范围映射为带业务含义中文标签的语义映射层，不修改数据源，仅影响显示。配置需在field options中添加value、range或special映射，支持配色，推荐优先用range覆盖大类并补特殊值，注意映射对象为原始字段值且range为闭区间。
理解Value Mappings的核心作用
Grafana 的 Value Mappings 功能不是美化工具，而是语义映射层——它把原始指标中无上下文的数值（比如 0、1、500、204）一对一或范围式地翻译成带业务含义的中文标签，比如“运行中”“离线”“服务异常”“无内容”。这个过程不修改数据源，只影响面板显示，安全、轻量、可逆。
配置步骤：从数字到中文的三步落地
在任意支持数值显示的面板（如 Stat、Gauge、Table）中：
- 进入面板编辑 → Field options → 展开 Value mappings 区域
- 点击 + Add mapping，选择映射类型：
- Value：精确匹配单个状态码（如输入 0 → 映射为 “待启动”）
- Range：覆盖连续区间（如 400–499 → “客户端错误”）
- Special：处理空值（null）、无效值（NaN）、默认未匹配项（Other），建议始终配一条 Other → “未知状态”
- 每条映射右侧可设置颜色（如 200 → “成功” → 绿色，5xx → “服务端故障” → 红色），颜色会同步作用于文字、背景或图表元素
实用技巧：让映射更准、更稳、更省心
真实监控场景中，光靠静态映射容易遗漏边缘情况：
- 优先用 Range 覆盖 HTTP 状态码大类：不必逐个写 400/401/403/404……直接设 400–499 → “请求失败”，再单独补一条 429 → “请求过载”（因需特殊提示），兼顾效率与精度
-
结合字段类型预处理：若原始字段是字符串（如
"DOWN"或"up"），先在查询中用IF或CASE WHEN统一转为整数（如 up=1, down=0），再用 Value Mappings 映射中文，避免混合类型导致映射失效 - 导出/导入映射配置：点击 Value Mappings 区域右上角 ⋯ → Export mappings，可备份或跨面板复用；导入时粘贴 JSON 即可，适合团队统一状态语义标准
常见陷阱与避坑提醒
看似简单，但几个细节常导致映射“不生效”：
- 映射对 原始字段值 生效，不是对单位转换后或阈值计算后的值——确认你在 Field options 下看到的 Values 列表里确实是原始数字
- Range 映射是闭区间，100–199 包含 100 和 199；但若存在浮点数（如 199.5），需确认数据精度是否被 Grafana 自动截断
- Table 面板中，Value Mappings 默认只影响 Cell display，如需排序仍按原始数值，这是正常行为；若需按中文语义排序，应改用 Transform → Sort by 并选原始字段
