feat(tools): add qperf profiling harness#1039
Conversation
![mai-team-app[bot]](https://avatars.githubusercontent.com/u/34859362?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review 总结
改动内容
本 PR 扩展 tools/qperf QEMU TCG plugin 与 analyzer，新增 tools/starry-syscall-harness Python harness，并在 scripts/axbuild 中集成 cargo starry perf / cargo starry run --perf。主要增强包括：
- qperf plugin raw sample v3 格式，新增 PC/SP/FP/timestamp/cpu/callchain 字段
- RISC-V frame-pointer callchain unwinding（leaf + fp 模式）
- analyzer 支持 Rust demangle、symbol style、focus filtering、hotspot categories、stack depth summary
- cargo starry perf 子命令集成 qperf 完整 workflow
- harness CLI 提供 perf-profile/perf-postprocess/perf-compare
- 本地 UI、MCP server、OS 知识图谱静态扫描
- 约 2000 行文档覆盖设计说明、验证报告、使用指南
实现逻辑
设计合理：
- 采样侧（profiler.rs）通过
read_first(reg_candidates)兼容 QEMU 不同架构的寄存器命名（sp/x2、fp/s0/x8） - FP unwind 包含 plausible_frame_pointer 校验、loop 检测、距离限制（16MiB）
- writer 线程使用
recv_timeout+AtomicBoolshutdown +qemu_plugin_register_atexit_cb，确保 QEMU 退出时正确 flush 数据 AXBUILD_TMP_DIR环境变量隔离避免 Docker root-owned 文件阻塞Box<starry::Command>减少栈上 enum 大小- 没有新增内核/driver 修改，保持 tools-only 范围
验证结果
本地验证全部通过：
| 检查项 | 结果 |
|---|---|
cargo fmt --check |
PASS |
git diff --check |
PASS |
bash -n qperf-smoke.sh |
PASS |
python3 -m py_compile (4 文件) |
PASS |
cargo clippy tools/qperf |
PASS |
cargo clippy tools/qperf/analyzer |
PASS |
cargo xtask clippy --package axbuild |
PASS |
| 冲突标记检查 | 无冲突标记 |
node --check app.js |
容器无 node，环境限制 |
PR 不包含 test-suit 或 apps 测试变更，不需要 QEMU Starry 运行验证。
CI 状态
当前 commit status 为 pending（无 CI 检查触发），PR 创建时间较短，不影响本地验证结论。
重复/重叠分析
- 已检查 origin/dev：base 只有基础 qperf plugin/analyzer，本 PR 是显著扩展
- 已检查其他 open PR：PR #1038 是 nginx CI 测试（无关）
- fork 上
feat/qperf-hotspot-enhancement等旧分支未单独提交为上游 PR，本 PR 是整合版本 - 无重复或冲突风险
已知局限
Logicalcallchain 模式已在 CLI 声明但未实现，CLI 会给出明确错误提示（文档已说明）- 完整 QEMU profile 验证依赖 host 环境（qemu-system-riscv64/libudev-dev），作者已在本地 WSL2 环境完成 blk/net full-stack 验证
- harness.py 约 2400 行，后续可考虑模块化拆分
Powered by mimo-v2.5-pro
|
请处理冲突 |
ZR233
left a comment
ZR233
left a comment
There was a problem hiding this comment.
这个 PR 把 qperf plugin/analyzer、tools/starry-syscall-harness 以及 cargo starry perf / cargo starry run --perf 串成了一条工具链，整体方向是有价值的；工具侧扩展、报告产物和 axbuild 入口的分层也基本清楚。
当前还不能合入，主要有三点需要先处理：
- PR 当前
mergeStateStatus=DIRTY，与dev有未解决冲突。由于这个 PR 同时改scripts/axbuild/src/starry/perf.rs、mod.rs和 qperf/harness 目录，必须先 rebase/merge 最新dev后再看最终形态。 - 这个分支与现有开放 PR 有明显重叠：#990 是更早的 syscall/qperf harness 大分支；#1093 已把 qperf/OScope harness 打包到
apps/qperf、apps/OScope-harness；#1095 又在同一个starry perf/run --perfruntime 上接入 apps 路径并修改相同 axbuild 文件。请在 rebase 后明确本 PR 与 #1093/#1095 的关系：是继续保留tools/作为最终入口，还是改为依赖/让位于apps/方案；否则合并顺序会造成重复入口和语义冲突。 - 提交进仓库的验证报告仍记录
cargo starry perf boot为FAIL、blk和旧 full harness QEMU run 为NOT RUN。我在当前 head 本地补跑了cargo xtask starry perf --case boot --arch riscv64 --timeout 8 --format folded --output-dir target/qperf-review-smoke，可以生成report.md、report.json、hotspots.csv、qperf/stack.folded和qperf/flamegraph.svg，但 committed docs/PR body 仍应在 rebase 后更新为当前 head 的可复现结果，避免把失败的验收记录作为正式文档合入。
我本地验证通过：git diff --check origin/dev...HEAD、cargo fmt --check、Python py_compile、node --check tools/starry-syscall-harness/web/app.js、bash -n tools/starry-syscall-harness/scripts/qperf-smoke.sh、cargo xtask clippy --package axbuild、cargo clippy --manifest-path tools/qperf/Cargo.toml --all-targets --all-features -- -D warnings、cargo clippy --manifest-path tools/qperf/analyzer/Cargo.toml --all-targets --all-features -- -D warnings，以及上面的 riscv64 qperf boot smoke。
CI 方面，当前 run 里真正失败的是 Test starry loongarch64 qemu / run_container 的 apk-curl，日志表现为 APK 下载/安装阶段约 60s 后 terminated 并输出 APK_CURL_TEST_FAILED；其他 clippy/Starry/ArceOS jobs 是 fail-fast 级联取消。这个失败与本 PR 的 qperf/axbuild 工具改动没有直接路径交集，我已把证据补充到既有跟踪 issue #786。CI 后续仍需要在 rebase 后重新跑到稳定状态。
重复/重叠检查：origin/dev 只有既有 qperf 基础工具和 Starry app runner；本 PR不是 base 已有功能的简单重复，但与 #1093/#1095 在 qperf harness 打包路径和 axbuild runtime 入口上属于 conflict-risk，需要先收敛方案。
| pub rootfs: Option<PathBuf>, | ||
|
|
||
| #[command(flatten)] | ||
| pub perf: ArgsQemuPerf, |
There was a problem hiding this comment.
| | analyzer focused flamegraph | PASS | `target/qperf-integration-smoke/analyzer/flamegraph.virtio.svg` | `--focus 'virtio|VirtQueue'` 输出 159 samples | | ||
| | stack.folded symbol 粒度 | PARTIAL | `target/qperf-integration-smoke/analyzer/stack.full.folded` | symbol demangle 可读；调用链仍常短栈 | | ||
| | harness perf-postprocess | PASS | `target/qperf-integration-smoke/postprocess/report.json` | 从既有 qperf artifacts 生成 report/csv，参数中包含 `symbol_style/focus/no_truncate` | | ||
| | cargo starry perf boot | FAIL | `target/qperf-integration-smoke/logs/cargo-starry-perf-boot.log` | qperf tools、StarryOS build、rootfs 准备均已推进；宿主缺 `qemu-system-riscv64`，未产生 raw samples/report | |
There was a problem hiding this comment.
这个验证报告作为仓库文档提交时仍记录核心入口 cargo starry perf boot 为 FAIL，并且后面的 blk/旧 full harness QEMU run 是 NOT RUN。我在当前 head 本地跑 cargo xtask starry perf --case boot --arch riscv64 --timeout 8 --format folded --output-dir target/qperf-review-smoke 可以生成 report/json/hotspots/folded/flamegraph 等产物；请在 rebase 后把 committed 验证报告和 PR 描述更新为当前 head 的真实可复现结果，避免把失败验收记录合入正式文档。
There was a problem hiding this comment.
不要只放一个 .md 文档在 docs 根目录下，根目录下的文档实际没有接入 文档系统，需要在docs/docs下的对应目录中，且确保本地 yarn start 后启动网站后可以正常流量，
ZR233
left a comment
ZR233
left a comment
There was a problem hiding this comment.
结论：请求修改。当前 head 4e6d7ecac930eec51c419eb8cea28e396fe82a39 的 qperf 运行链路可以工作，但该分支已落后并与当前 dev 的模块边界冲突，不能按现状合入。
本轮复审：
- 变更范围：新增 qperf plugin/analyzer、Starry perf CLI、采集监控与报告工具；其中
scripts/axbuild/src/starry/perf.rs从 406 行增至 2013 行，PerfOutputs从 7 个字段增至 29 个。 - 本地静态验证通过：
cargo fmt --check、cargo xtask clippy --package axbuild、qperf 与 qperf-analyzer 的cargo clippy --all-targets --all-features -- -D warnings、Pythonpy_compile、node --check、bash -n、git diff --check。 - 运行时验证：执行
cargo xtask starry perf --case boot --arch riscv64 --timeout 8 --format all --output-dir target/qperf-review-smoke-all，成功启动到 Starry shell，采集 535 个样本，并实际生成 report、JSON、hotspots、folded stack 和 flamegraph。由于测试主动设置 8 秒超时，QEMU 返回 124，报告按实现标记为incomplete；这不改变下面的结构性阻塞项。 - 当前 head 的 Actions 仅有一个独立失败：Starry loongarch64 container 的 apk-curl 下载超时，属于已由 #786 跟踪的基础设施/基线问题；其余红色项是 fail-fast 取消，并非新的独立失败。
- 重复/冲突：#1093、#1095 已合入相关 qperf/app 入口，#1347 已将 perf 按职责模块化；#1151 仍开放且覆盖 qperf runtime/apps。PR 当前 merge state 为
DIRTY，需要先 rebase 并收敛实现，不能把旧单体文件重新带回。 - 原有 3 个未解决线程仍然有效：入口与 #1093/#1095 的收敛、提交文档中的失败/未运行验收记录、以及文档未接入站点。
新增的 inline 评论是本轮主要代码质量阻塞项：请在 rebase 最新 dev 后复用 #1347 的现有子模块边界，并按原始采样、阶段火焰图、运行时产物和报告输出拆分 PerfOutputs。完成结构收敛、解决现有线程并更新验证材料后再请求复审。
| raw: PathBuf, | ||
| folded: PathBuf, | ||
| flamegraph: PathBuf, | ||
| folded_boot: PathBuf, |
There was a problem hiding this comment.
【阻塞｜模块与对象职责】本次把已有的 perf.rs 从 406 行扩展到 2013 行，并把 PerfOutputs 从 7 个字段扩到 29 个；同一文件现在同时负责参数校验、Starry 构建、QEMU/QMP 生命周期、窗口监控、host 指标、analyzer 调用、ELF 地址解析和报告渲染。项目 code-quality 准则对约 800 行以上文件要求拆分、对约 8 个以上字段要求按变化原因检查；这里已经形成多个独立变化原因。当前 dev 的 #1347 已把 perf 按 args/analyzer/harness/metrics/monitor/outputs/qemu/summary/symbols/toolchain 拆开，请先 rebase 最新 dev，把本 PR 的新增逻辑接入这些现有模块；同时将 PerfOutputs 按原始采样、阶段火焰图、运行时/QMP 产物和最终报告拆成有职责的子对象，而不是继续堆字段。否则该分支会重新引入已被移除的单体模块，后续任何一类输出或运行流程变化都必须修改同一个 2000 行文件。
3 participants
问题
当前 StarryOS 的 qperf 使用门槛较高，用户需要手动拼接 harness、QEMU plugin、analyzer、marker/window、flamegraph 等参数，导致性能采样和报告复现成本较高。同时，原有火焰图和 folded stack 更偏 leaf hotspot，缺少调用链、workload window、工程分类热点和对比报告等工具能力。
改动
tools/qperf中扩展 QEMU TCG plugin 与 analyzer：tools/starry-syscall-harness：perf-profile、perf-postprocess、perf-compare等 CLI；--qperf-metrics在 tools 侧解析 guest stdout 中的QPERF_METRIC key=value，不在本 PR 中强制启用内核/driver 侧插桩。scripts/axbuild中集成cargo starry perf和cargo starry run --perf：target/qperf/<case>/perf/<arch>/latest/下的 report/json/csv/flamegraph/folded stack；--perf时原有cargo starry run行为不变。设计逻辑
本 PR 将 qperf 和 harness 的主要实现放在
tools/，将用户入口放在现有scripts/axbuild的cargo starry子命令中，避免引入新的并行 CLI 体系。内核/driver 侧的 virtio counter 插桩和性能优化原型没有放入本 PR，后续可以拆成单独 PR；本 PR 只保留 tools 侧对QPERF_METRIC的解析与报告合并能力，便于被测分支自行导出指标。验证
已在本地完成以下检查：
cargo fmtpython3 -m py_compile tools/starry-syscall-harness/knowledge_graph.py tools/starry-syscall-harness/ui_server.py tools/starry-syscall-harness/harness.py tools/starry-syscall-harness/mcp_server.pynode --check tools/starry-syscall-harness/web/app.jsbash -n tools/starry-syscall-harness/scripts/qperf-smoke.shgit diff --checkcargo xtask clippy --package axbuildcargo clippy --manifest-path tools/qperf/Cargo.toml --all-targets --all-features -- -D warningscargo clippy --manifest-path tools/qperf/analyzer/Cargo.toml --all-targets --all-features -- -D warnings未在这个上游 PR 分支重新执行完整 QEMU profile；完整采样依赖本机 QEMU/rootfs/网络环境，文档中保留了手动 smoke 命令和已验证的报告格式说明。
范围说明
/proc/qperf_metrics导出实现。