node_exporter 0.16 指标重命名升级指南从 node_cpu 到 node_cpu_seconds_total 的完整迁移方案【免费下载链接】node_exporterExporter for machine metrics项目地址: https://gitcode.com/GitHub_Trending/no/node_exporternode_exporter 从 0.16.0 起对大量指标进行了重命名以符合 Prometheus 官方命名最佳实践counter 类型加_total后缀、数值统一携带_seconds/_bytes等单位这直接导致既有 Grafana 仪表盘与告警规则中引用的旧指标名失效。本文基于仓库中的官方升级文档 docs/V0_16_UPGRADE_GUIDE.md 及其配套的两份 recording rules 兼容文件系统讲解新旧指标名的映射关系、三种平滑升级路径并结合当前仓库源码验证新指标名的真实定义与数据来源帮助你无痛完成迁移。读完本文你将能够理解 0.16.0 指标重命名的动因与映射全貌掌握更新仪表盘、录制规则、双版本并行三种升级方案的适用场景与完整配置直接复制仓库提供的新旧指标双向转换规则文件投入生产。一、为什么 0.16.0 要大改指标名Prometheus 命名最佳实践升级指南开宗明义node_exporter0.16.0 及更新版本重命名了大量指标目的是让指标命名与 Prometheus 官方推荐的命名规范对齐。其核心约定有三点Counter 计数器指标必须带_total后缀旧指标node_context_switches上下文切换次数、node_forks进程 fork 次数是不符合规范的计数类指标名新版本统一改为node_context_switches_total、node_forks_total。单位必须显式写入指标名时间类指标使用_seconds字节类指标使用_bytes。例如旧的node_boot_time开机时间Unix 时间戳改为node_boot_time_seconds旧的node_memory_MemTotal改为node_memory_MemTotal_bytes磁盘 I/O 时间node_disk_io_time_ms改为node_disk_io_time_seconds_total并从毫秒换算为秒。量级与类型一目了然命名后的指标可以直接从名字读出是什么、什么单位、什么类型方便聚合、查询与告警。这一改动对下游用户的影响是任何在 Grafana 仪表盘、Prometheus 告警规则或第三方采集配置中硬编码了旧指标名的查询都会在升级后返回空数据。二、升级路径总览三种平滑迁移方案升级指南给出了三种并行可行的方案你可以根据环境灵活组合方案适用场景主要成本更新 Grafana 仪表盘仪表盘数量少、团队有维护精力需要人工修改每个面板的查询使用 recording rules希望自动保留旧/新两套指标名无需改仪表盘产生额外存储数据时间戳会被重对齐新旧版本双跑需要严格对比新旧数据、分阶段验证多占用一个端口与一份抓取任务下面逐一展开。三、方案一更新 Grafana 仪表盘多查询并行展示新旧数据对于 Grafana 用户升级指南给出的最直接方案是在仪表盘面板中添加多个查询Query让新旧数据在同一面板中同时展示从而在迁移期间对比验证、平滑过渡。具体做法以编辑 Grafana 面板的 Query 为例为面板新增一个查询Add Query将旧指标名替换为新指标名如把node_cpu换成node_cpu_seconds_total通过面板图例Legend或查询别名区分新旧两条序列例如旧序列标注old、新序列标注new待新指标数据稳定可信后再删除旧查询并保存面板。这个方案适合仪表盘维护成本可控的场景其优点是不引入额外的数据存储缺点是每块仪表盘、每个面板都要人工改一遍且新旧曲线混在同一面板中需要仔细设置图例与颜色。四、方案二使用 recording rules 自动翻译指标名推荐升级指南提供了仓库内配套的两份录制规则文件可以让 Prometheus 在抓取阶段之外自动生成翻译后的指标从而让旧查询或新查询都能继续工作docs/example-16-compatibility-rules.yml把新格式指标翻译成旧格式旧查询无需改动即可继续用docs/example-16-compatibility-rules-new-to-old.yml把旧格式指标翻译成新格式用于旧版 exporter 数据兼容新查询。注意文件名new-to-old指新指标格式 → 旧指标格式即上文第一份文件的功能方向实际使用时请以文件内容为准核对方向。使用方式很简单把对应规则文件内容放入 Prometheus 配置中的rule_files例如rule_files: - example-16-compatibility-rules.yml - example-16-compatibility-rules-new-to-old.yml然后对 Prometheus 执行配置重载SIGHUP 或调用/-/reload即可生效。升级指南同时明确指出了该方案的缺点需要你在选型时权衡产生大量额外数据每条规则都会把原指标复制为一份新指标存储开销成倍增加重新对齐时间戳录制规则由 Prometheus 周期性求值生成其时间戳是规则求值时刻而非原始抓取时刻可能导致曲线出现轻微的锯齿或与原始序列不完全对齐。4.1 旧→新方向example-16-compatibility-rules.yml完整规则这份文件将旧版指标名翻译为新版覆盖 bcache、buddyinfo、stat、cpu、diskstats、filesystem、infiniband、interrupts、memory、network、nfs、textfile 共 12 个采集器族。以下是完整规则内容已按文件原样整理groups: - name: node_exporter-16-bcache rules: - record: node_bcache_cache_read_races expr: node_bcache_cache_read_races_total - name: node_exporter-16-buddyinfo rules: - record: node_buddyinfo_blocks expr: node_buddyinfo_count - name: node_exporter-16-stat rules: - record: node_boot_time_seconds expr: node_boot_time - record: node_time_seconds expr: node_time - record: node_context_switches_total expr: node_context_switches - record: node_forks_total expr: node_forks - record: node_intr_total expr: node_intr - name: node_exporter-16-cpu rules: - record: node_cpu expr: label_replace(node_cpu_seconds_total, cpu, $1, cpu, cpu(.)) - name: node_exporter-16-diskstats rules: - record: node_disk_read_bytes_total expr: node_disk_bytes_read - record: node_disk_written_bytes_total expr: node_disk_bytes_written - record: node_disk_io_time_seconds_total expr: node_disk_io_time_ms / 1000 - record: node_disk_io_time_weighted_seconds_total expr: node_disk_io_time_weighted - record: node_disk_reads_completed_total expr: node_disk_reads_completed - record: node_disk_reads_merged_total expr: node_disk_reads_merged - record: node_disk_read_time_seconds_total expr: node_disk_read_time_ms / 1000 - record: node_disk_writes_completed_total expr: node_disk_writes_completed - record: node_disk_writes_merged_total expr: node_disk_writes_merged - record: node_disk_write_time_seconds_total expr: node_disk_write_time_ms / 1000 - name: node_exporter-16-filesystem rules: - record: node_filesystem_free_bytes expr: node_filesystem_free - record: node_filesystem_avail_bytes expr: node_filesystem_avail - record: node_filesystem_size_bytes expr: node_filesystem_size - name: node_exporter-16-infiniband rules: - record: node_infiniband_port_data_received_bytes_total expr: node_infiniband_port_data_received_bytes - record: node_infiniband_port_data_transmitted_bytes_total expr: node_infiniband_port_data_transmitted_bytes - name: node_exporter-16-interrupts rules: - record: node_interrupts_total expr: node_interrupts - name: node_exporter-16-memory rules: - record: node_memory_Active_bytes expr: node_memory_Active # ……其余内存指标同构见原文件 - name: node_exporter-16-network rules: - record: node_network_receive_bytes_total expr: node_network_receive_bytes - record: node_network_receive_compressed_total expr: node_network_receive_compressed - record: node_network_receive_drop_total expr: node_network_receive_drop - record: node_network_receive_errs_total expr: node_network_receive_errs - record: node_network_receive_fifo_total expr: node_network_receive_fifo - record: node_network_receive_frame_total expr: node_network_receive_frame - record: node_network_receive_multicast_total expr: node_network_receive_multicast - record: node_network_receive_packets_total expr: node_network_receive_packets - record: node_network_transmit_bytes_total expr: node_network_transmit_bytes - record: node_network_transmit_compressed_total expr: node_network_transmit_compressed - record: node_network_transmit_drop_total expr: node_network_transmit_drop - record: node_network_transmit_errs_total expr: node_network_transmit_errs - record: node_network_transmit_fifo_total expr: node_network_transmit_fifo - record: node_network_transmit_frame_total expr: node_network_transmit_frame - record: node_network_transmit_multicast_total expr: node_network_transmit_multicast - record: node_network_transmit_packets_total expr: node_network_transmit_packets - name: node_exporter-16-nfs rules: - record: node_nfs_connections_total expr: node_nfs_net_connections - record: node_nfs_packets_total expr: node_nfs_net_reads - record: node_nfs_requests_total expr: label_replace(label_replace(node_nfs_procedures, proto, $1, version, (.)), method, $1, procedure, (.)) - record: node_nfs_rpc_authentication_refreshes_total expr: node_nfs_rpc_authentication_refreshes - record: node_nfs_rpcs_total expr: node_nfs_rpc_operations - record: node_nfs_rpc_retransmissions_total expr: node_nfs_rpc_retransmissions - name: node_exporter-16-textfile rules: - record: node_textfile_mtime_seconds expr: node_textfile_mtime其中值得重点解释的两条CPU 的label_replace新指标node_cpu_seconds_total的cpu标签值是0、1这种纯数字而旧指标node_cpu的标签值是cpu0、cpu1格式。规则用label_replace(node_cpu_seconds_total, cpu, $1, cpu, cpu(.))把形如cpu0的标签值剥离前缀cpu还原成0从而构造出旧格式序列。磁盘 I/O 时间的单位换算新指标以秒为单位node_disk_io_time_seconds_total、node_disk_read_time_seconds_total、node_disk_write_time_seconds_total旧指标以毫秒为单位node_disk_io_time_ms等因此规则中执行了/ 1000的换算保证新旧两条序列量纲一致、可以直接对比。memory 组的其余规则如node_memory_AnonPages_bytes、node_memory_Buffers_bytes、node_memory_Cached_bytes、node_memory_MemFree_bytes、node_memory_SwapTotal_bytes等 30 余条均为_bytes后缀的机械补全与已列出的条目结构完全相同完整内容请直接查阅 docs/example-16-compatibility-rules.yml。4.2 新→旧方向example-16-compatibility-rules-new-to-old.yml完整规则这份文件是反向翻译当数据源还是旧版 exporter 时用它将旧指标翻译成新指标名供已经迁移到新查询的仪表盘使用。与上一份文件相比核心差异有两点CPU 方向反转label_replace(node_cpu_seconds_total, cpu, cpu$1, cpu, (.))把纯数字0还原为cpu0用于构造旧序列node_cpu磁盘时间单位反转node_disk_io_time_seconds_total * 1000、node_disk_read_time_seconds_total * 1000、node_disk_write_time_seconds_total * 1000把新格式的秒换算回毫秒NFS 标签方向反转label_replace(label_replace(node_nfs_requests_total, proto, $1, version, (.)), method, $1, procedure, (.))把新格式的version/procedure标签还原为旧格式的proto/method标签输出node_nfs_procedures。该文件完整内容如下同样省略了 memory 组同构条目groups: - name: node_exporter-16-bcache rules: - expr: node_bcache_cache_read_races record: node_bcache_cache_read_races_total - name: node_exporter-16-buddyinfo rules: - expr: node_buddyinfo_blocks record: node_buddyinfo_count - name: node_exporter-16-stat rules: - expr: node_boot_time_seconds record: node_boot_time - expr: node_time_seconds record: node_time - expr: node_context_switches_total record: node_context_switches - expr: node_forks_total record: node_forks - expr: node_intr_total record: node_intr - name: node_exporter-16-cpu rules: - expr: label_replace(node_cpu_seconds_total, cpu, cpu$1, cpu, (.)) record: node_cpu - name: node_exporter-16-diskstats rules: - expr: node_disk_read_bytes_total record: node_disk_bytes_read - expr: node_disk_written_bytes_total record: node_disk_bytes_written - expr: node_disk_io_time_seconds_total * 1000 record: node_disk_io_time_ms - expr: node_disk_io_time_weighted_seconds_total record: node_disk_io_time_weighted - expr: node_disk_reads_completed_total record: node_disk_reads_completed - expr: node_disk_reads_merged_total record: node_disk_reads_merged - expr: node_disk_read_time_seconds_total * 1000 record: node_disk_read_time_ms - expr: node_disk_writes_completed_total record: node_disk_writes_completed - expr: node_disk_writes_merged_total record: node_disk_writes_merged - expr: node_disk_write_time_seconds_total * 1000 record: node_disk_write_time_ms - name: node_exporter-16-filesystem rules: - expr: node_filesystem_free_bytes record: node_filesystem_free - expr: node_filesystem_avail_bytes record: node_filesystem_avail - expr: node_filesystem_size_bytes record: node_filesystem_size - name: node_exporter-16-infiniband rules: - expr: node_infiniband_port_data_received_bytes_total record: node_infiniband_port_data_received_bytes - expr: node_infiniband_port_data_transmitted_bytes_total record: node_infiniband_port_data_transmitted_bytes - name: node_exporter-16-interrupts rules: - expr: node_interrupts_total record: node_interrupts - name: node_exporter-16-memory rules: - expr: node_memory_Active_bytes record: node_memory_Active # ……其余内存条目同构见原文件 - name: node_exporter-16-network rules: - expr: node_network_receive_bytes_total record: node_network_receive_bytes - expr: node_network_receive_compressed_total record: node_network_receive_compressed - expr: node_network_receive_drop_total record: node_network_receive_drop - expr: node_network_receive_errs_total record: node_network_receive_errs - expr: node_network_receive_fifo_total record: node_network_receive_fifo - expr: node_network_receive_frame_total record: node_network_receive_frame - expr: node_network_receive_multicast_total record: node_network_receive_multicast - expr: node_network_receive_packets_total record: node_network_receive_packets - expr: node_network_transmit_bytes_total record: node_network_transmit_bytes - expr: node_network_transmit_compressed_total record: node_network_transmit_compressed - expr: node_network_transmit_drop_total record: node_network_transmit_drop - expr: node_network_transmit_errs_total record: node_network_transmit_errs - expr: node_network_transmit_fifo_total record: node_network_transmit_fifo - expr: node_network_transmit_frame_total record: node_network_transmit_frame - expr: node_network_transmit_multicast_total record: node_network_transmit_multicast - expr: node_network_transmit_packets_total record: node_network_transmit_packets - name: node_exporter-16-nfs rules: - expr: node_nfs_connections_total record: node_nfs_net_connections - expr: node_nfs_packets_total record: node_nfs_net_reads - expr: label_replace(label_replace(node_nfs_requests_total, proto, $1, version, (.)), method, $1, procedure, (.)) record: node_nfs_procedures - expr: node_nfs_rpc_authentication_refreshes_total record: node_nfs_rpc_authentication_refreshes - expr: node_nfs_rpcs_total record: node_nfs_rpc_operations - expr: node_nfs_rpc_retransmissions_total record: node_nfs_rpc_retransmissions - name: node_exporter-16-textfile rules: - expr: node_textfile_mtime_seconds record: node_textfile_mtime五、方案三新旧版本同时运行双端口并行抓取升级指南给出的最后一种方案是让旧版与新版 exporter 同时在不同端口上运行并在 Prometheus 中额外增加一个抓取任务scrape job来采集旧实例数据从而在不中断监控的前提下完成验证与切换。操作要点不同端口旧实例保持原端口如默认 9100新实例使用新端口如--web.listen-address:9101运行新增抓取任务在 Prometheusscrape_configs中追加一个 job指向新端口与原 job 并行抓取按需启用采集器升级指南特别建议只启用你真正关心的、指标名发生变化的那部分采集器例如stat、cpu、diskstats、filesystem、network、memory、nfs等以降低双跑期间的资源开销与数据冗余。node_exporter 通过--collector.name与--no-collector.name开关控制单个采集器的启停例如# 旧版实例9100 端口仅启用关心的采集器 node_exporter --web.listen-address:9100 \ --collector.stat --collector.cpu --collector.diskstats \ --collector.filesystem --collector.netdev --collector.meminfo # 新版实例9101 端口同样只启用关心采集器 node_exporter --web.listen-address:9101 \ --collector.stat --collector.cpu --collector.diskstats \ --collector.filesystem --collector.netdev --collector.meminfo验证与收尾在新旧两套序列上运行差异查询如用or合并、或按 job 分组对比同名指标确认新指标数据正确后即可下线旧实例、移除旧抓取任务。六、源码级印证新指标名在仓库中的真实定义为了让你确信上述规则与新版指标一一对应这里给出当前仓库源码中几个代表性新指标的实际定义位置均以node_为命名空间前缀由prometheus.BuildFQName拼装6.1 stat 采集器计数器补全与秒单位在 collector/stat_linux.go 中statCollector定义了以下新指标描述符node_intr_totalTotal number of interrupts servicednode_context_switches_totalTotal number of context switchesnode_forks_totalTotal number of forksnode_boot_time_secondsNode boot time, in unixtime对应旧的node_intr、node_context_switches、node_forks、node_boot_time正是升级规则中 stat 组逐一翻译的四个指标。而采集器在Update中collector/stat_linux.go通过procfs读取/proc/stat后以CounterValue上报中断/上下文切换/进程创建计数以GaugeValue上报开机时间。仓库的端到端测试产物也直接印证了新指标名与输出格式见 collector/fixtures/e2e-output.txt# HELP node_boot_time_seconds Node boot time, in unixtime. # TYPE node_boot_time_seconds gauge node_boot_time_seconds 1.418183276e09以及 collector/fixtures/e2e-output.txt 中带cpu0、modeidle标签的计数序列# HELP node_cpu_seconds_total Seconds the CPUs spent in each mode. # TYPE node_cpu_seconds_total counter node_cpu_seconds_total{cpu0,modeidle} 10870.69从这里可以直观看出cpu标签值确实是纯数字0这正是旧→新规则里需要label_replace剥离cpu前缀、新→旧规则里需要补回cpu前缀的原因。6.2 diskstats 采集器秒单位与_total后缀在 collector/diskstats_linux.go 中磁盘指标全部采用新命名node_disk_reads_completed_total、node_disk_reads_merged_totalnode_disk_read_bytes_total对应旧node_disk_bytes_readnode_disk_read_time_seconds_total对应旧node_disk_read_time_msnode_disk_writes_completed_total、node_disk_writes_merged_totalnode_disk_written_bytes_total对应旧node_disk_bytes_writtennode_disk_write_time_seconds_total对应旧node_disk_write_time_msnode_disk_io_time_seconds_total对应旧node_disk_io_time_msnode_disk_io_time_weighted_seconds_total对照升级规则可见旧→新方向把这些毫秒值ms / 1000换算为秒新→旧方向则* 1000还原为毫秒量纲换算在规则层完成而采集器内部已统一以秒为基本单位输出。6.3 filesystem 采集器_bytes单位落定在 collector/filesystem_linux.go 中文件系统统计在读取statfs后统一换算为字节size: float64(buf.Blocks) * float64(buf.Bsize), free: float64(buf.Bfree) * float64(buf.Bsize), avail: float64(buf.Bavail) * float64(buf.Bsize),对应新指标node_filesystem_size_bytes、node_filesystem_free_bytes、node_filesystem_avail_bytes与升级规则中 filesystem 组的三条翻译完全一致。6.4 指标重命名对照速查表结合两份规则文件与源码将核心指标映射汇总如下便于你快速排查仪表盘和告警采集器旧指标名新指标名转换要点statnode_boot_timenode_boot_time_seconds追加_secondsstatnode_context_switchesnode_context_switches_total追加_totalstatnode_forksnode_forks_total追加_totalstatnode_intrnode_intr_total追加_totalcpunode_cpunode_cpu_seconds_total追加单位与_totalcpu0→0标签改写diskstatsnode_disk_bytes_readnode_disk_read_bytes_total词序调整 _totaldiskstatsnode_disk_bytes_writtennode_disk_written_bytes_total词序调整 _totaldiskstatsnode_disk_io_time_msnode_disk_io_time_seconds_total毫秒→秒 _totaldiskstatsnode_disk_read_time_msnode_disk_read_time_seconds_total毫秒→秒 _totaldiskstatsnode_disk_write_time_msnode_disk_write_time_seconds_total毫秒→秒 _totalfilesystemnode_filesystem_size/free/avail..._size_bytes/_free_bytes/_avail_bytes追加_bytesmemorynode_memory_MemTotal等node_memory_MemTotal_bytes等全部追加_bytesnetworknode_network_receive_bytes等node_network_receive_bytes_total等全部追加_totalnfsnode_nfs_proceduresnode_nfs_requests_total标签version/procedure→proto/methodtextfilenode_textfile_mtimenode_textfile_mtime_seconds追加_seconds完整映射以两份规则文件为准旧→新见 docs/example-16-compatibility-rules.yml新→旧见 docs/example-16-compatibility-rules-new-to-old.yml。七、选型建议与注意事项综合升级指南的说明与仓库现状给出以下实践建议追求零改动、快速止血优先采用 recording rules 方案。把两份规则文件放入rule_files即可同时保留新旧两套指标名仪表盘与告警无需改动。但要注意其双倍存储与时间戳重对齐的代价长期运行建议设定过渡期后清理旧序列。追求数据精确、可逐步切换采用双版本双端口方案配合只启用关心采集器的开关--collector.*/--no-collector.*在验证期内并行对比再择机切换并下线旧实例。仪表盘数量少、迁移意愿强直接采用更新 Grafana 面板多查询并行方案一次性完成所有查询的新旧替换不引入额外存储。最后再次提醒两个易错点CPU 规则的label_replace方向容易写反——旧→新是把cpu0剥离为0正则cpu(.)新→旧是把0补成cpu0正则(.)替换串cpu$1磁盘时间类规则涉及毫秒与秒的换算方向与两份规则文件一一对应切勿混用否则新旧序列量纲不一致对比与告警都会失真。【免费下载链接】node_exporterExporter for machine metrics项目地址: https://gitcode.com/GitHub_Trending/no/node_exporter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考