指纹文件编写指南

一、指纹是什么、为什么要有它

不同厂商、不同型号的 BMC（基板管理控制器）暴露传感器数据的 接口路径和 JSON 结构千差万别：

• 有的走标准 Redfish：/redfish/v1/Chassis/1/ThresholdSensors
• 有的走厂商私有：/sensors/allinfo、/kunlun/webui/sensor
• 有的数据是数组（Sensors[*].Name），有的是字典（data.{*}.Value）

如果把"取哪个路径、取哪个字段"写死在代码里，每换一台机器就要改代码、重新发版。指纹机制的做法是：

二、指纹文件整体结构

指纹文件默认为 uri_fingerprints.json（可在 config.ini 里改 fingerprint_file），是一个 JSON 数组，每个元素是一条指纹：

[
  {
    "id": 1,                          // 整数，全局唯一，用于 fingerprint_id 指定或日志引用
    "type": "redfish_temp_power_speed_duty", // 字符串，人类可读的类型名，仅用于日志展示
    "Uris": {                          // 对象：键=URI路径，值=该路径的字段配置
      "/redfish/v1/Chassis/1/ThresholdSensors": {
        "fields": [ /* 见第三章 */ ]
      },
      "/redfish/v1/Chassis/1/Oem/Public/Thermal": {
        "fields": [ /* 一条指纹可同时从多个 URI 聚合数据 */ ]
      }
    }
  },
  { "id": 2, "type": "...", "Uris": {/* ... */} }
]

三、fields 的三种写法（核心）

每个 URI 下 "fields" 是数组，数组里每个对象描述"一个要提取的量"。根据 path 里通配符的不同，分三种模式：

模式 A：数组模式 [*] —— 传感器是一个数组

当接口返回形如 "Sensors": [ {...}, {...} ] 的数组时使用。程序会遍历数组每个元素，从中各取一个 name 和若干 value。

[
  {"name":"name",  "path":"Sensors[*].Name"},
  {"name":"value", "path":"Sensors[*].ReadingValue"}
]

{
  "Sensors": [
    {"Name":"CPU0_Temp","ReadingValue":45},
    {"Name":"CPU1_Temp","ReadingValue":47}
  ]
}

{
  "CPU0_Temp": 45,
  "CPU1_Temp": 47
}

规则：同一 [*] 前缀的字段会按 name 配对。name 字段的值作为结果键名；其余字段作为值。若只有一个 value 字段且名为 value，结果键就是 name 本身；否则键名为 传感器名_字段名（见下文命名规则）。

模式 B：字典模式 {*} —— 传感器是一个字典

当接口返回形如 "data": { "CPU0": {...}, "CPU1": {...} } 的对象时使用。程序遍历字典每个键值对。

[
  {"name":"name",  "path":"data.{*}.@key"},
  {"name":"value", "path":"data.{*}.Value"}
]

{
  "data": {
    "CPU0": {"Value":45},
    "CPU1": {"Value":47}
  }
}

{
  "CPU0": 45,
  "CPU1": 47
}

关键点：@key 是一个特殊后缀，表示"用字典的键本身作为传感器名"。如果不写 @key，则需要再配一个 name 字段指向某个属性来取名字。

模式 C：固定字段模式 无通配符 —— 提取单个标量

当只需要从响应里取某个固定位置的值（比如设备型号、序列号、单一读数）时使用。path 直接是嵌套路径，不含 [*] 或 {*}。

[
  {"name":"model", "path":"Oem.DeviceInfo.Model"},
  {"name":"sn",    "path":"SerialNumber"}
]

{
  "SerialNumber":"ABC123",
  "Oem":{"DeviceInfo":{"Model":"X2000"}}
}

{
  "model": "X2000",
  "sn": "ABC123"
}

四、path 语法速查

五、结果键名是怎么生成的

提取出来的数据最终拼成一行 CSV，列名（键名）的生成规则：

六、程序怎么知道用哪条指纹（探测机制）

程序启动后调用 probe() 匹配指纹，有两种触发方式：

1. 自动探测（推荐）

config.ini 里 不写 fingerprint_id（或注释掉）。程序会：

1. 按指纹文件里的顺序，逐条指纹尝试；
2. 对每条指纹，逐个请求它所有的 URI；
3. 只要任一 URI 请求成功且 fields 能提取到非空数据，就认定这条指纹匹配，停止遍历。

2. 指定 id（强制）

config.ini 里写 fingerprint_id = 2。程序直接用 id=2 的指纹，但仍会验证它的所有 URI：

• 任一 URI 能提取到数据 → 通过，开始采集；
• 所有 URI 都提取不到 → 抛 DataCollectionError 并退出（避免采到空数据）。

七、采集后会自动过滤的值

提取出来的原始结果，还会过一道清洗，以下值会被整列丢弃（不出现在 CSV 里）：

八、编写注意事项

九、一个完整的多机型指纹文件示例

[
  {
    "id": 1,
    "type": "redfish_standard",
    "Uris": {
      "/redfish/v1/Chassis/1/ThresholdSensors": {
        "fields": [
          {"name":"name",  "path":"Sensors[*].Name"},
          {"name":"value", "path":"Sensors[*].ReadingValue"}
        ]
      },
      "/redfish/v1/Chassis/1/Oem/Public/Thermal": {
        "fields": [
          {"name":"name", "path":"Fans[*].Name"},
          {"name":"duty","path":"Fans[*].SpeedRatio"}
        ]
      }
    }
  },
  {
    "id": 2,
    "type": "oembmc_dict_style",
    "Uris": {
      "/sensors/allinfo": {
        "fields": [
          {"name":"name",  "path":"{*}.11"},
          {"name":"value", "path":"{*}.1"}
        ]
      }
    }
  },
  {
    "id": 3,
    "type": "kunlun_webui",
    "Uris": {
      "/kunlun/webui/sensor": {
        "fields": [
          {"name":"name",  "path":"data.{*}.@key"},
          {"name":"value", "path":"data.{*}.Value"}
        ]
      }
    }
  },
  {
    "id": 4,
    "type": "new_machine_with_nested_paths",
    "Uris": {
      "/redfish/v1/Chassis/1/Thermal": {
        "fields": [
          {"name":"name", "path":"Oem.Public.Fans[*].FanName"},
          {"name":"rpm",  "path":"Oem.Public.Fans[*].ReadingRPM"}
        ]
      },
      "/redfish/v1/Chassis/1": {
        "fields": [
          {"name":"model", "path":"Oem.DeviceInfo.Model"},
          {"name":"sn",    "path":"SerialNumber"}
        ]
      }
    }
  }
]

十、常见问题排查表