jc 的 --mpstat-s 流式解析器：把 Linux mpstat 输出逐行转成 JSON Lines

开发工具【免费下载链接】jcCLI tool and python library that converts the output of popular command-line tools, file-types, and common strings to JSON, YAML, or Dictionaries. This allows piping of output to tools like jq and simplifying automation scripts.项目地址https://gitcode.com/gh_mirrors/jc/jc点击查看免费下载本篇围绕 docs/parsers/mpstat_s.md 展开讲解 jc 中mpstat_s流式streaming解析器的定位、CLI 与 Python 模块两种用法、完整输出 Schema 及其源码实现。读完本文你将能够把mpstat的 CPU 利用率与中断速率表格流式转换为可被jq等工具消费的 JSON Lines理解每条输出字段的生成逻辑并掌握raw、quiet、ignore_exceptions三个参数在流式解析中的作用。一、mpstat_s 是什么流式解析器与非流式解析器的区别mpstat_s是 jc 中专门处理sysstat包mpstat命令输出的流式解析器文档原文明确指出This streaming parser outputs JSON Lines (cli) or returns an Iterable of Dictionaries (module)CLI 场景输出为JSON Lines每解析出一行mpstat数据就立即yield一个 JSON 对象。由于流式处理不缓存整块输入内存占用恒定适合mpstat 1 3600 | jc --mpstat-s这类长时间采集、逐行落盘或逐行送入下游管道如jq、grep的场景。模块场景jc.parse(mpstat_s, lines)返回一个字典迭代器消费时才逐行解析不会一次性构造完整结果列表。需要注意jc 仓库中同时存在一个非流式的mpstat解析器见 jc/parsers/mpstat.py它把整个输出解析为 JSON 数组。二者文档中都带有同一条提示Note: Latest versions ofmpstatsupport JSON output (v11.5.1)也就是说较新版本的mpstat自带 JSON 输出能力这条注释是提醒用户在条件允许时可直接使用mpstat原生 JSON但在sysstat较旧CentOS 7 等的发行版上文本表格仍是唯一输出mpstat/mpstat_s两个解析器正是为此而存在。从源码结构看jc/parsers/mpstat_s.py 中的info类声明了该解析器的元数据class info(): Provides parser metadata (version, author, etc.) version 1.1 description mpstat command streaming parser author Kelly Brazil author_email kellyjonbrazilgmail.com compatible [linux] tags [command] streaming True由此可确认三点事实解析器版本 1.1、兼容平台为linux、streaming True标记使其被 CLI 按流式方式调度。二、CLI 用法文档给出的标准用法是$ mpstat | jc --mpstat-s带-AAll输出 CPU、NODE、中断三类全部统计时的完整示例$ mpstat -A | jc --mpstat-s {cpu:all,percent_usr:0.22,percent_nice:0.0,percent_sys:...} {cpu:0,percent_usr:0.22,percent_nice:0.0,percent_sys:0....} {cpu:all,intr_s:37.61,type:interrupts,time:03:15:06 PM} ...加上-rraw见 jc/cli.py 中self.raw r in self.options则保留原始字符串不做 float 转换$ mpstat -A | jc --mpstat-s -r {cpu:all,percent_usr:0.22,percent_nice:0.00,percent_...} {cpu:0,percent_usr:0.22,percent_nice:0.00,percent_sy...} {cpu:all,intr_s:37.61,type:interrupts,time:03:15:06 PM}两种模式的差别仅在数值字段默认模式下percent_usr是 float0.22raw 模式下是字符串0.22适合需要严格保留原始格式如小数位宽再自行处理的场景。三、模块用法文档给出的 Python 调用方式import jc result jc.parse(mpstat_s, mpstat_command_output.splitlines()) for item in result: # do somethingparse的完整签名与 jc/parsers/mpstat_s.py 一致def parse(data: Iterable[str], raw: bool False, quiet: bool False, ignore_exceptions: bool False) - Union[Iterable[Dict], tuple]参数说明参数类型说明dataiterable逐行文本数据如sys.stdin或str.splitlines()不能是单个字符串否则抛TypeError由streaming_input_type_check保证见 jc/streaming.pyrawboolTrue时输出未经_process处理的原始字段字符串数字quietboolTrue时抑制兼容性检查产生的警告信息如非 Linux 平台上的提示ignore_exceptionsboolTrue时不抛异常改为在输出中附加_jc_meta错误元数据并继续解析后续行返回值为字典迭代器Iterable of Dictionaries。四、输出 Schema文档定义的完整 Schema 如下每个 JSON Lines 行是一个对象字段按行内容出现非全部必填{ type: string, // cpu 或 interrupts time: string, // 行首时间如 03:15:06 PM cpu: string, // CPU 标识all 或数字编号 node: string, // 使用 -P ALL 等出现 NODE 表头时的节点标识 average: boolean, // 汇总行行首为 Average:时为 true percent_usr: float, percent_nice: float, percent_sys: float, percent_iowait: float, percent_irq: float, percent_soft: float, percent_steal: float, percent_guest: float, percent_gnice: float, percent_idle: float, intr_s: float, x_s: float, // x 为整数对应具体中断号如 58_s nmi_s: float, loc_s: float, spu_s: float, pmi_s: float, iwi_s: float, rtr_s: float, res_s: float, cal_s: float, tlb_s: float, trm_s: float, thr_s: float, dfr_s: float, mce_s: float, mcp_s: float, err_s: float, mis_s: float, pin_s: float, npi_s: float, piw_s: float, hi_s: float, timer_s: float, net_tx_s: float, net_rx_s: float, block_s: float, irq_poll_s: float, block_iopoll_s: float, tasklet_s: float, sched_s: float, hrtimer_s: float, rcu_s: float, // 仅在使用 -qq 或 ignore_exceptionsTrue 时存在 _jc_meta: { success: boolean, // 解析失败时为 false error: string, // success 为 false 时存在 line: string // success 为 false 时存在 } }字段可按含义分组理解CPU 百分比组percent_*对应mpstat默认输出无参数或-u的%usr %nice %sys %iowait %irq %soft %steal %guest %gnice %idle列。总中断组intr_s对应-I SUM风格的intr/s列。中断明细组x_sx是整数中断号mpstat -A在支持中断明细的平台如 x86上会输出每个 IRQ 的/s速率列表头形如58/s解析后键名为58_s。内核事件组nmi_s…rcu_s对应mpstat -A输出的 NMI、LOC、CPU MIGRATION、RESCHEDULE、CALL、TLB 以及软中断HI、TIMER、NET_TX、NET_RX、BLOCK、IRQ_POLL、TASKLET、SCHED、HRTIMER、RCU速率。_jc_meta错误元数据对象仅在ignore_exceptionsTrue或 CLI 的-qq时随错误行输出用于在流中定位失败行而不中断管道。五、真实输出对照从 fixture 看解析结果仓库的测试 fixture 提供了可直接对照的输入输出样本。输入 tests/fixtures/centos-7.7/mpstat-A.out 节选自 CentOS 7.7 的mpstat -ALinux 3.10.0-1062.1.2.el7.x86_64 (localhost) 03/11/2022 _x86_64_(1 CPU) 03:15:06 PM CPU %usr %nice %sys %iowait %irq %soft %steal %guest %gnice %idle 03:15:06 PM all 0.22 0.00 0.37 0.01 0.00 0.00 0.00 0.00 0.00 99.40 03:15:06 PM 0 0.22 0.00 0.37 0.01 0.00 0.00 0.00 0.00 0.00 99.40 03:15:06 PM CPU intr/s 03:15:06 PM all 37.61 03:15:06 PM 0 33.15 03:15:06 PM CPU 0/s 1/s 4/s ... NMI/s LOC/s ... PIW/s 03:15:06 PM 0 0.02 0.02 ...对应输出 tests/fixtures/centos-7.7/mpstat-A-streaming.json 的解析结果中前三行依次为{cpu:all,percent_usr:0.22,percent_nice:0.0,percent_sys:0.37,percent_iowait:0.01,percent_irq:0.0,percent_soft:0.0,percent_steal:0.0,percent_guest:0.0,percent_gnice:0.0,percent_idle:99.4,type:cpu,time:03:15:06 PM} {cpu:0,percent_usr:0.22,percent_nice:0.0,percent_sys:0.37,percent_iowait:0.01,...,type:cpu,time:03:15:06 PM} {cpu:all,intr_s:37.61,type:interrupts,time:03:15:06 PM}与文档 Examples 一节完全一致。而 tests/fixtures/ubuntu-18.04/mpstat-A.out 则展示了带NODE表头的输出多 NUMA 节点机器其结果对象中会出现node:all、node:0而非cpu键例如 tests/fixtures/ubuntu-18.04/mpstat-A-streaming.json 中{node:all,percent_usr:26.15,percent_nice:8.92,percent_sys:32.36,percent_iowait:1.39,...,type:cpu,time:08:50:55 AM}同时该样本还包含按中断号展开的对象键如19_s、56_s与软中断对象hi_s、timer_s、net_rx_s、block_s、rcu_s等完整覆盖了 Schema 中的中断明细组与内核事件组。六、源码实现解析6.1 主循环表头检测与类型判定parse() 是一个生成器函数核心逻辑按行处理输入jc.utils.compatibility(__name__, info.compatible, quiet) streaming_input_type_check(data) header_found: bool False for line in data: try: streaming_line_input_type_check(line) # skip blank lines if not line.strip(): continue output_line: Dict {} # check for header, normalize it, and fix the time column if CPU in line or NODE in line: header_found True if %usr in line: stat_type cpu else: stat_type interrupts header_text: str line.replace(/, _)\ .replace(%, percent_)\ .lower() header_start line.find(CPU ) if header_start -1: header_start line.find(NODE ) header_text header_text[header_start:] continue ...几个关键点表头行识别mpstat输出由多个表格块组成每块都有自己的表头行含CPU或NODE。解析器不预设表头长什么样而是逐块捕获一旦发现表头就更新header_text和stat_type并continue跳过该表头行本身表头不会出现在输出中。type字段判定表头行若含%usr则本块是 CPU 利用率表typecpu否则为中断表typeinterrupts。这就是 Schema 中type只有两个取值的原因。列名归一化header_text经过三步变换——/→_intr/s→intr_s、58/s→58_s、%→percent_%usr→percent_usr、整体小写。之后截取从CPU或NODE起始位置之后的部分丢弃表头行最前面的时间列文本保证列名与数据行对齐。时间列剥离mpstat数据行以时间前缀开头如03:15:06 PM。解析器用同一header_start下标把行切成两段line[:header_start]作为时间line[header_start:]作为表格数据再调用通用表格解析器if header_found: output_line simple_table_parse([header_text, line[header_start:]])[0] output_line[type] stat_type item_time line[:header_start].strip() if Average: not in item_time: output_line[time] line[:header_start].strip() else: output_line[average] True if output_line: yield output_line if raw else _process(output_line)simple_table_parse是 jc 的通用工具函数jc/parsers/universal.py把“表头行 数据行”按空白切列并拼成字典。因此Average:汇总行mpstat 1 5最后一行的Average:前缀不输出time而是标记average: true。6.2 类型转换_process 与动态中断列_process() 负责把字符串数值转为 floatfloat_list { percent_usr, percent_nice, percent_sys, percent_iowait, percent_irq, percent_soft, percent_steal, percent_guest, percent_gnice, percent_idle, intr_s, nmi_s, loc_s, spu_s, pmi_s, iwi_s, rtr_s, res_s, cal_s, tlb_s, trm_s, thr_s, dfr_s, mce_s, mcp_s, err_s, mis_s, pin_s, npi_s, piw_s, hi_s, timer_s, net_tx_s, net_rx_s, block_s, irq_poll_s, block_iopoll_s, tasklet_s, sched_s, hrtimer_s, rcu_s } for key in proc_data: if (key in float_list or (key[0].isdigit() and key.endswith(_s))): proc_data[key] jc.utils.convert_to_float(proc_data[key]) return proc_data固定字段走float_list白名单而x_s这类中断号动态列0_s、1_s、58_s… 中断号随机器而异无法穷举则用规则key[0].isdigit() and key.endswith(_s)动态匹配——这正是 Schema 中x_s: float, # x is an integer的实现依据。rawTrue时跳过_process所有数值保持原始字符串与 CLI-r行为对应。6.3 异常处理与 _jc_metaparse被 jc/streaming.py 的add_jc_meta装饰器包裹except Exception as e: yield raise_or_yield(ignore_exceptions, e, line)raise_or_yield的语义见 docs/streaming.md 对jc.streaming的说明ignore_exceptionsFalse默认重新抛出异常并附带出错行信息流立即终止ignore_exceptionsTrueCLI 上对应-qq双重 quiet 模式捕获异常给该行的输出对象附加_jc_metasuccess: false、error、line流继续。这使得长时间监控场景可以在不中断管道的前提下事后用jq select(._jc_meta and (._jc_meta.success|not))之类的过滤定位失败行。七、测试覆盖tests/test_mpstat_s.py 对该解析器做了 5 项验证覆盖了默认输出与-A全量输出、多次采样-A 2 5以及两套发行版差异测试方法输入 fixture期望输出test_mpstat_s_nodata空列表空结果[]test_mpstat_s_centos_7_7tests/fixtures/centos-7.7/mpstat.outtests/fixtures/centos-7.7/mpstat-streaming.jsontest_mpstat_s_A_centos_7_7tests/fixtures/centos-7.7/mpstat-A.outtests/fixtures/centos-7.7/mpstat-A-streaming.jsontest_mpstat_s_A_2_5_centos_7_7tests/fixtures/centos-7.7/mpstat-A-2-5.outtests/fixtures/centos-7.7/mpstat-A-2-5-streaming.jsontest_mpstat_s_A_ubuntu_18_4tests/fixtures/ubuntu-18.04/mpstat-A.outtests/fixtures/ubuntu-18.04/mpstat-A-streaming.json从源码结构看CentOS 7.7 样本无 NODE 块单 NUMA 节点Ubuntu 18.04 样本含 NODE 块与更多中断号列两者共同保证了cpu/node两种键、type两种取值、静态与动态中断列的解析路径都被覆盖。八、适用前提与限制小结平台解析器声明compatible [linux]在非 Linux 上运行时jc.utils.compatibility会给出提示可用quietTrue或 CLI-q抑制输出仍会尝试解析。上游工具mpstat来自sysstat包CentOS 7、Ubuntu 18.04 等旧发行版默认即为文本表格输出文档同时提示sysstatv11.5.1 的mpstat支持原生 JSON 输出此类环境可直接使用mpstat --json无需 jc 解析。列集依赖表头解析结果完全以输入中实际出现的表头为准——intr_s、x_s、nmi_s等字段只在对应表头存在时出现下游脚本应按需取值而非假设固定键集。选型建议一次性完整分析需要随机访问所有采样点用非流式的jc --mpstatjc/parsers/mpstat.py边采边传、长时监控、逐行处理用本文的jc --mpstat-s。赞分享开发工具【免费下载链接】jcCLI tool and python library that converts the output of popular command-line tools, file-types, and common strings to JSON, YAML, or Dictionaries. This allows piping of output to tools like jq and simplifying automation scripts.项目地址https://gitcode.com/gh_mirrors/jc/jc点击查看免费下载相关推荐jc mpstat 解析器详解将 mpstat 多核 CPU 利用率与中断统计输出转为结构化 JSONjc mpstat 解析器详解将 mpstat 多核 CPU 利用率与中断统计输出转为结构化 JSON mpstat 是 sysstat 工具包中用于输出每个开发工具FastAPI 流式输出 JSON Lines用 yield 实现高性能逐行 JSON 数据流FastAPI 流式输出 JSON Lines用 yield 实现高性能逐行 JSON 数据流 本文围绕 FastAPI自 0.134.0 起内置的 JS后端Web框架API设计jc mount 解析器把多平台 mount 输出转成结构化 JSON 的完整指南jc mount 解析器把多平台 mount 输出转成结构化 JSON 的完整指南 本文围绕 jc 项目中的 mount 解析器展开讲解如何把 Linux、开发工具上一篇3秒上手的终端AI助手OpenCode如何用简洁设计重构开发者工作流下一篇beautiful-docs贡献者访谈他们如何发现这些优秀的技术文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考