文档类型:架构设计 / 核心机制白皮书
适用版本:Arm Performix 2026.4.0(Engine 1.24.0)
目标受众:平台研发、性能工具接入方、架构评审
文档状态:Draft(基于本机开源代码 + 官方发行包 + 两台真实设备实测整理)

1. 概述与设计背景 (Overview & Purpose)

1.1 一句话定义

Arm Performix 是一套面向 Arm 平台的"采集—分析—可视化"一体化性能工具链:主机侧提供 GUI 与 CLI(apx),目标侧部署轻量 agent 与采集器,把 PMU/SPE、/proc、strace、微基准等数据统一转成 parquet/CSV,再由主机侧用 DuckDB 渲染成 Timeline、火焰图、Top-down、系统调用热图等视图。

它在系统中的位置可以概括为:"性能数据的 ETL + 分析编排层"——向下屏蔽 Android/Linux、adb/SSH、闭源采集器的差异,向上以 recipe 为单位提供可复现的分析工作流。

1.2 核心痛点:为什么需要它

在 Performix 之前,团队做 Arm 性能分析通常面临四个割裂:

痛点具体表现后果
工具割裂Linux 用 perf,Android 用 simpleperf/Streamline,syscall 用 strace,微架构用私有脚本结论口径不一致,无法横向对比
链路割裂采集在设备、分析在工作站,靠 adb pull / scp 手工搬运数据易丢、不可复现、无法多人协作
平台割裂Android 要 adb root,Linux 要 SSH;工具包版本、依赖各不相同接入成本高,新人上手慢
语义割裂只有"计数器和样本",没有"这个数字意味着什么"(Top-down、MPKI、延迟来源)数据很多,结论很少

Performix 的核心价值就是把这些"割裂"收敛成统一的 recipe、统一的 run 产物、统一的视图语义。

1.3 上下游与系统边界

依赖的外部组件:
- Android 目标:adb、设备 perf_event_open 权限(通常需 adb root)、可选 strace
- Linux 目标:sshd + SFTP、python3(sysutil)、perf、strace、可选 asct
- 主机:sl-record/sl-analyze(闭源,随发行包提供)、DuckDB(编译进 apx)

系统边界(它不负责的事):
- 不做 APM/链路追踪,不采集业务埋点
- 不做持续采集与在线监控(run 是一次性的)
- 不替代 perfetto/atrace 的 Android 全局 trace 能力
- 不提供跨机器的数据汇聚(run 存在本机文件系统)

2. 发展历程与架构演进 (Evolution History)

2.1 阶段一:单机 CLI(V0.x)

  • 形态:一个 CLI 直接在本机调用采集/分析工具,run 产物落本地目录。
  • 架构局限:只能分析本机;跨设备要手工拷贝;没有 agent,目标侧依赖用户自己准备环境。
  • 演进动因:真实负载在 Android/Linux 设备上,必须"从主机驱动远端采集"。

2.2 阶段二:采集/分析分离(V1.0 → V1.2x)

  • 形态:引入 apx-agent(目标侧常驻进程)+ run 目录(可复现产物)+ recipe(把"怎么采、怎么分析、怎么展示"固化成代码)。
  • 关键变化:
  • 工具包由主机制作、按目标平台分发(--deploy-tools)
  • 采集产物统一为 .apc(Streamline 抓包)/ .csv / .parquet
  • 分析从"人手敲命令"变成"recipe 里的 render stage"
  • 架构局限:agent 与工具版本强绑定;单个目标同时只能跑一个 run(target lock)。
  • 演进动因:需要多人复现同一份结论,且能对比不同 run。

2.3 阶段三:多 recipe + GUI + 渐进开源(V1.19 → 当前)

  • 形态:7 个可见 recipe(System Utilization / Code Hotspots / CPU Microarchitecture / Instruction Mix / Memory Access / Syscall Trace Summary / System Characterization),GUI 与 CLI 双入口,run 可在 History 中回放与对比。
  • 当前基线:Engine 1.24.0 + App 2026.4.0;开源仓库只释放了 CLI 与 System Utilization 的完整链路,其余 recipe 依赖闭源工具包(sl-record/sl-analyze/asct)。
  • 架构局限:Top-down/Instruction Mix 强依赖 CPU telemetry 规格(仅 Arm 自家核);SPE 依赖硬件;工具包不开源导致无法完全自建。

2.4 架构演进对比

3. 设计目标与权衡 (Design Goals & Trade-offs)

3.1 业务目标

目标说明
降低 Arm 性能分析门槛不需要熟记 perf/Streamline/strace 参数,选 recipe 即可出结论
结论可复现run 目录固化 recipe 源码、参数、原始产物、日志
跨平台统一Android 走 adb、Linux 走 SSH,上层 recipe 无感
从"数"到"因"不止给指标,还给 Top-down、延迟来源、失败率等解释性视图

3.2 技术指标(非功能需求)

维度目标/现状
采集开销采样类(hotspots)低;metrics 类随事件组增加;sysutil 为每秒读 /proc,开销可忽略
传输产物回传(SFTP/HTTP 分块),单 run 可达数百 MB(实测 Code Hotspots 266 MB)
可扩展recipe / tool integration 均为 JS 插件式,新增能力不改引擎
可移植主机支持 Linux/macOS/Windows(x64);目标支持 Android aarch64、Linux aarch64/x86_64
隔离性单目标串行(target lock),避免多次采集互相干扰

3.3 非目标(Non-Goals)

  • 不做长时间在线监控(无常驻采集、无告警)
  • 不做跨机数据聚合/多租户
  • 不覆盖非 Arm 架构的微架构分析(x86 仅作为 Linux 目标做通用采集)
  • 不替代业务侧 APM;不做代码级热更新

3.4 设计权衡与备选方案

决策点当前选择备选方案取舍理由
采集器复用闭源 sl-record/sl-analyze(Streamline 血统)全自研 perf 前端省掉符号化/反汇编/事件库的巨量工作;代价是无法完全开源、依赖 Arm 生态
数据格式parquet + CSV,分析用 DuckDB自建时序库文件即数据,便于打包/回放/导出;查询性能足够单机分析
传输SFTP(Linux)/ adb(Android)自建 gRPC 数据通道复用系统能力、权限模型简单;代价是依赖 sshd/adb 稳定性
并发单目标串行(锁)并行多 run采集会互相干扰(PMU/CPU 竞争),串行保证数据可信
平台门槛telemetry 命中才允许 microarch通用事件兜底无规格时算不出 Top-down,宁可显式报错也不给错结论
开源策略渐进开源(先 CLI + System Utilization)一次性全开源闭源工具受第三方许可约束;先开放可自建的部分

4. 核心功能与工作机制 (Core Features & Mechanism)

4.1 核心概念 / 术语表

术语含义
Recipe一个分析工作流(怎么采、怎么分析、怎么展示),JS 编写,含 deployments/parameters/stages
Tool Integration采集器在引擎侧的适配层(如 neoprof、sysutil-timeline、syscall-trace),负责参数拼装、执行、产物登记
Tool Bundle按目标平台打包的工具包(sl-record-Linux-aarch64.tar.gz 等),由 --deploy-tools 下发
Target采集目标:android://serial、ssh://user@host:port、localhost
Run一次 recipe 执行的完整产物目录(metadata/manifest/recipe/工具输出)
Componentrun 内的一个数据文件 + 类型 + schema 版本(manifest 条目)
Renderer / Visualization把 component 变成图表(Timeline/Flame/Topdown/Table)的渲染单元
Telemetry Specification每个 CPU 型号的事件与指标定义(JSON),决定 Top-down 能否计算
Deploy Tools把缺失/过期的工具包推送到目标并校验

4.2 功能模块拆解

模块职责关键实现
GUI选择 recipe/target、配置参数、查看/对比 runElectron + gRPC 客户端
CLI (apx)脚本化入口:target/recipe/run/support/daemonCobra + gRPC
Engine(daemon)平台匹配、依赖解析、工具部署、调度、DuckDB 查询、渲染编排Go + goja(执行 recipe JS)+ DuckDB
apx-agent目标侧命令执行、文件传输、提权、端口上报Go(单文件,静态链接)
采集器真正读 PMU/SPE//proc/stracesl-record / sysutil-timeline / strace / asct
分析器抓包 → parquet / 符号化 / 反汇编sl-analyze(闭源)、parquet-to-json
渲染器组件 → 视图配置Go renderer + recipe 内的 renderStages

4.3 核心运转流程

关键步骤说明:
1. 平台预检:recipe 的 deployments[].appliesTo 必须匹配目标 OS/架构;不匹配直接拒绝(如 Android 上跑 cpu_microarchitecture)。
2. 能力预检(ready):探测工具是否存在、SPE 节点是否暴露、strace 是否安装、PMU 是否可用。
3. 采集:--deploy-tools 会先补齐工具;采集期间持有 target lock。
4. 回传与分析:Linux 默认目标侧跑 sl-analyze,Android 固定主机侧跑(reformat_on_host=true)。
5. 渲染:recipe 的 renderStages 生成 renderer 配置,GUI 拉取组件渲染。

4.4 三种采集通道(按数据源)

通道适用数据源代表 recipe
PMU / SPE需要硬件计数器perf_event_open、Arm SPECode Hotspots、Microarchitecture、Instruction Mix(dynamic)、Memory Access
/proc + /sys 轮询系统级利用率/proc/stat|meminfo|vmstat|diskstats|net/devSystem Utilization(Linux)
专用采集器syscall / 微基准 / GPU / CMNstrace、asct、Mali/CMN 计数器Syscall Trace、System Characterization、GPU、CMN

5. 核心数据模型与存储 (Data Model & Storage)

5.1 Run 目录模型

~/.local/share/apxd/runs/<run_id>/
├── metadata.json          # run 元信息(名称/时间/参数/目标/结果/size)
├── manifest.json          # 组件清单:path + component_type + schema_version
├── categorization.json    # 分类信息
├── recipe/
│   ├── source/recipe.js   # 该次 run 使用的 recipe 源码(可回放)
│   └── version.json
├── collector/             # 目标信息(OS/CPU/cluster/pids)
├── tool/<tool>/<idx>/     # 采集与分析产物(.apc/.csv/.parquet/.log)
├── user_messages/
└── log.json               # 结构化事件日志

manifest 条目结构(实测):

{
  "path": "tool/sysutil-timeline/0/timeline.csv",
  "component_type": { "name": "sysutil-timeline-csv", "schema_version": "3.0" }
}

关键特性:manifest 只记录路径与类型,不记录哈希,因此组件可被替换(这也是"假 run"能加载的原因)。

5.2 核心组件类型(实测/源码)

component_type载体说明
metadata / categorizationJSONrun 元信息
recipe / versionJS / JSON回放所需的 recipe
sysutil-timeline-csvCSVLinux 系统利用率(160 列)
capture_apc二进制目录Streamline 抓包(SQLite + images)
sl-collect-flat-functions-csvCSV(zst)函数 self/total 样本
sl-collect-call-tree / sl-collect-metricsJSON(zst)调用树 / 调用路径指标
syscall-trace-parquetparquetsyscall 事件(7 列)
log-json / log-textJSON/文本日志

5.3 Run 状态机

5.4 存储设计

数据位置说明
run 产物~/.local/share/apxd/runs/<id>/文件系统即数据库;可整目录拷贝/归档
并发锁~/.local/share/apxd/locks/<id>/target/run 级锁
扩展工具包~/.local/share/apxd/extensions/tools/用户放置的自定义 bundle(注意:仅用于列目录,部署时引擎优先读 exe 同级 tools/)
主机配置~/.config/apxd/apx.yml目标、特性开关、adb 路径等
主机日志~/.local/state/apxd/*.logdaemon 运行日志
目标侧工具Linux ~/.local/share/apx/tools/;Android /data/local/tmp/apx/由 --deploy-tools 维护

无 Redis/MySQL:这是"单机 + 文件"架构,换取零运维与可打包性。

6. 代码框架与落地实现 (Code Architecture & Implementation)

6.1 目录/模块结构(开源部分)

core/
├── apap-cli/                     # CLI + GUI 引擎入口
│   ├── cmd/                      # cobra 子命令(target/recipe/run/support/daemon)
│   ├── recipes/                  # 7 个 recipe(JS)
│   ├── tool-integrations/        # 采集器适配层(neoprof/sysutil/syscall/asct/…)
│   ├── tools-builtin/            # 开源内置工具源码(sysutil-timeline/syscall-trace/…)
│   └── tools/                    # 发行时打包的工具 bundle(按平台)
├── apap-engine/                  # 引擎核心
│   ├── recipeparser/             # 解析 recipe JS(goja 运行时 + API 注入)
│   ├── recipe/runtime/           # 阶段编排、deploy、ready、run、render
│   ├── conductor/                # 目标平台抽象(Linux/Android/Local)
│   ├── deploymentsupport/        # 工具依赖解析与部署
│   ├── telemetry/                # CPU 事件/指标规格(JSON + 查询)
│   ├── renderimpls/              # 渲染器(sl-analyze/SQL/…)
│   ├── target/                   # SSHTarget / AndroidTarget / LocalTarget
│   └── featureflags/             # 特性开关
└── atperf-agent/                 # 目标侧 agent(含 sysinfo/armcpus)

6.2 核心抽象关系

6.3 关键代码骨架

(1)recipe 定义(core/apap-cli/recipes/system_utilization.js 摘)

const recipe = {
  name: 'system_utilization',
  version: '1.0',
  deployments: [
    { appliesTo: [{ architecture: 'aarch64', os: 'Linux' }],
      dependencies: [{ type: 'tool', name: 'sysutil-timeline', version: '1.0.0',
                       requiredWhen: { type: 'always' } }] },
  ],
  parameters: [
    { id: 'interval', config: { type: 'input', defaultValue: '1.0' } },
  ],
  readyStages: [...],
  runStages: [...],
  renderStages: [...],
};

(2)采集命令拼装(tool-integrations/neoprof.js::buildRecordArgs 摘)

if (mode === 'metrics') {
  args.push('-M', metricsGroup, '-r', samplingFrequency);
} else if (mode === 'samples') {
  args.push('-r', samplingFrequency);
} else if (mode === 'spe') {
  if (speSampleRate) args.push('-F', speSampleRate);
  if (speWorkflow) args.push('-X', speWorkflow);
}

(3)系统利用率采集循环(tools-builtin/sysutil-timeline/collector.py 摘)

cpu_pcts = cpu_percents(prev_cpu, curr_cpu)          # Δ/Δ,clamp 0–100
total_iowait = iowait_percent(prev_cpu["cpu"], curr_cpu["cpu"])
ctxt_per_s = rate_from_delta(prev_stat["ctxt"], curr_stat["ctxt"], elapsed)
read_bps = rate_from_delta(prev.sectors_read, curr.sectors_read, elapsed) * sector_size

(4)run 组件登记(概念)

{ "path": "tool/neoprof/0/output/functions-....csv",
  "component_type": { "name": "sl-collect-flat-functions-csv", "schema_version": "1.1" } }

6.4 设计模式

模式体现
插件 / 策略recipe 与 tool integration 均为可插拔 JS 模块,按 name+version 解析
管道(Pipeline)采集 → 分析 → 渲染三段式,每段是独立 stage
适配器SSHTarget / AndroidTarget / LocalTarget 统一目标接口
模板方法引擎固定"预检→部署→执行→回传"骨架,细节下沉到 recipe/integration

7. 接入指南与关键配置 (Integration & Configurations)

7.1 接入一个目标(Step 1–3)

Step 1:准备目标
- Android:adb devices 可见;adb root(否则采 PMU 会提权失败);可选 strace
- Linux:SSH 可达,目标有 python3、binutils;PMU 需 perf_event_paranoid ≤ 1 或 root

Step 2:添加目标

apx target add android://<设备序列号> --name dev-a
apx target add user@host:22:/path/key --name arm-server
apx target test --target dev-a
apx target prepare --target dev-a      # 部署 agent

Step 3:跑 recipe

apx recipe list
apx recipe ready system_utilization --system-wide --target dev-a
apx recipe run system_utilization --system-wide --timeout 15 --deploy-tools --target dev-a

7.2 扩展一个 recipe(How to Extend)

  1. 在 core/apap-cli/recipes/ 新建 <name>.js,导出 { name, title, version, deployments, parameters, readyStages, runStages, renderStages }。
  2. 在 deployments[].appliesTo 声明支持的 OS/架构,并列出 dependencies(tool + version)。
  3. 在 runStages 里通过 context.runTools({toolConfigs:[...]}) 调用采集器。
  4. 在 renderStages 里声明 renderer 与 visualization(组件路径、字段、聚合方式)。
  5. 用 apx recipe info <name> 验证平台矩阵,再用真实目标跑 ready。

7.3 新增一个 tool integration

  1. 在 core/apap-cli/tool-integrations/ 新建模块,实现 probe()(能否用)与 run()(怎么采)。
  2. 声明 deployments(工具包名/版本/平台)与 parameters。
  3. 在引擎的 tool 注册表中登记(随 recipe 引用自动解析)。
  4. 用 --deploy-tools 验证工具包下发与产物登记。

7.4 核心配置项字典

主机配置 ~/.config/apxd/apx.yml

配置项类型默认含义动态生效
enable-android-targetsboolfalse是否允许 Android 目标(含 android:// 语法与 adb 选项)重启 daemon
daemon-autostartbooltrueCLI 是否自动拉起 daemon重启
adb-pathstringadbadb 可执行文件路径重启
data-dirstring~/.local/share/apxdrun/锁/扩展目录重启
log-level / log-filestringinfo / stdout日志级别与落盘重启
jobsintCPU 核数并行任务数重启
http-port / http-chunk-bytesint0 / 1 MiB产物传输分块重启
deployment-tools-dirstring空目标侧工具部署根目录重启
enable-experimental-recipesboolfalse展示实验 recipe重启
enable-gpu-recipeboolfalseGPU recipe重启
enable-neoprof-timelineboolfalseNeoProf 时间线导出重启
enable-neoprof-system-utilizationboolfalseAndroid 走 NeoProf 做 sysutil重启
enable-jfr-captureboolfalseJava JFR 采集重启
enable-full-capture-supportbooltrue完整抓包保留重启

常用 recipe 参数

参数适用含义
interval / thread_scan_intervalSystem Utilization采样间隔 / 线程扫描间隔
sampling_freq(low/normal/high)Code Hotspots / Microarch采样频率档位
rich_data_captureHotspots / Microarch是否回收镜像与符号
reformat_on_hostHotspots分析放主机还是目标
collect_java_stacks / collect_dotnet_stacksHotspots / Microarch是否补 Java/.NET 栈
metrics_group / collect_allMicroarchitecture采集哪些指标组
min_latency_cycles / spe_sample_rateMemory AccessSPE 过滤与采样率
mode(dynamic/static/both)Instruction Mix动态/静态

8. 稳定性保障与运维排障 (Reliability & Operations)

8.1 异常处理与容灾

机制现状
并发控制target lock(同一目标串行);run 级锁目录
超时--timeout 控制采集时长;工具调用有超时(agent RPC deadline)
失败重试采集失败不自动重试(避免污染数据),由用户重跑;工具部署可 --deploy-tools-force 强制重装
幂等性run 目录以 run_id 区分;重复执行产生新 run,不覆盖
清理默认运行结束清理目标工作区;--no-cleanup 保留
降级缺失可选工具仅告警(如 numastat),必需工具缺失直接失败

8.2 可观测性与排障

核心观测点

类型位置/内容
daemon 日志~/.local/state/apxd/<timestamp>.log
run 事件日志<run>/log.json(阶段开始/结束、错误码)
GUI 日志~/.config/Arm Performix/logs/main.log
支持包apx support collect(打包日志与系统信息)
关键错误码engine.packages.LOAD_TOOL_BUNDLE、engine.agent.connection_creator.AGENT_NOT_DEPLOYED、engine.tool.service.ELEVATE_PRIVILEGES_FAILED、engine.common.CREATE_SFTP_CLIENT、engine.recipe.stages.SCRIPTED_STAGE_ERROR

Runbook(实测归纳)

症状定位处置
ELEVATE_PRIVILEGES_FAILED目标 su 不支持 su -cadb root 后重试;或给目标 root 能力
LOAD_TOOL_BUNDLE工具包不在 exe 同级 tools/把 bundle 放进 <bin>/tools/<tool>/<ver>/
AGENT_NOT_DEPLOYED目标无 verify-and-launch.shapx target prepare
CREATE_SFTP_CLIENT目标无 SFTP安装/启用 SFTP 子系统(OpenSSH≥)
Target platform is not supportedrecipe 的 appliesTo 不含该 OS/架构换目标平台(Linux recipe 不能在 Android 跑)
None of the CPUs ... supported无 telemetry 规格换 Arm 自家核,或放弃该 recipe
采集卡住无输出提权/交互式密码等待用交互终端跑,或 adb root

8.3 使用限制与避坑指南(红线)

  1. microarch / instruction mix(dynamic) 只支持 telemetry 库里的核(cortex-a725/x925、c1-、neoverse-);第三方 SoC 核(非 Arm 自研核)直接拒绝。
  2. Memory Access / Cache Sharing 需要 Arm SPE(/sys/bus/event_source/devices/arm_spe_*);云 VM 通常不透传。
  3. Syscall Trace 依赖 strace(不是 ftrace),且只支持 launch/attach,不支持 system-wide。
  4. Instruction Mix(static) 需要目标有 python3 -m venv + pip。
  5. System Characterization 需要 ASCT 包(Arm 内部发行,需凭证)。
  6. 同一目标同时只能跑一个 run(target lock)。
  7. Android 目标需要 adb root(或可用的 su -c)才能采 PMU。
  8. 扩展工具包目录只用于"列目录":部署时引擎优先读可执行文件同级的 tools/,仅放 extensions/tools 会报 LOAD_TOOL_BUNDLE。
  9. 大抓包传输慢:Code Hotspots 实测单 run 266 MB,跨网传输需预留时间。
  10. Windows on Arm 不支持构建(DuckDB 无 Windows Arm64 库)。

9. 总结与未来规划 (Summary & Future Work)

9.1 当前技术债

技术债影响
采集/分析核心闭源(sl-record/sl-analyze/asct)无法完全自建、无法审计算法细节
telemetry 只覆盖 Arm 自家核第三方 SoC(如本次实测的第三方 SoC)microarch 不可用
单目标串行多设备并采需多 daemon/多机
产物为文件系统无集中存储、无跨机检索
Android 依赖 root量产机不可用,仅研发阶段

9.2 演进方向(建议)

  1. 扩大开源范围:把 tool integration 与 renderer 逐步开源,允许自定义采集器。
  2. telemetry 扩展:支持第三方核的通用事件集(至少 MPKI 级)。
  3. 多目标并行:以 target 为维度拆分调度,避免全局串行。
  4. 数据面升级:run 产物可选对象存储/中心仓,支持跨机对比。
  5. 非 root 采集:Android 走 simpleperf 兼容路径,降低量产机门槛。

10. 参考资料 (References)

10.1 外部技术参考(已核实)

内容链接
开源仓库(CLI + recipes)https://github.com/arm/performix
产品主页 / 下载https://developer.arm.com/servers-and-cloud-computing/arm-performix
安装指南https://learn.arm.com/install-guides/performix/
Microarchitecture 学习路径https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-microarchitecture/
制品下载站(CLI/App)https://artifacts.tools.arm.com/arm-performix/
本机代码树~/apps/performix/core(v2026.4.0)
本机发行包~/apps/performix-cli、~/apps/performix-app
Logo

更多推荐