P1–P40 are complete — twenty-three analyzers, ten collectors, drill-down queries, baseline comparison, emulator lifecycle, gesture injection, report artifacts, a scenario runner with selectors and assertions and a workload runner for externally published plans, UI capture, diff and animation labels, offline HAP inspection, symbol statistics and an offline flamegraph and a machine-checked parity ledger, a multi-run trend page, deterministic UI exploration, coverage ingestion, ELF-based optimization detection, a verified model-driven agent, ELF-based symbol recovery with measured naming accuracy, a root-cause report that checks what a model cites, and model-guided exploration that checks every choice it is offered, thermal curves read from the device, performance budgets checked by a gate, a root cause that names what changed between two runs, a versioned tool-result envelope for agents, and every command served as an MCP tool, a device-free source scanner that finds and ranks the defect in an ArkTS tree, and an external review of it that published its own false positives, 2569 tests

HarmonyOS performance,
made measurable.

ohos-perf turns a HarmonyOS device into structured, evidence-backed performance data. Capability probing, capture through hitrace, hiprofiler, procfs, hiperf, hidumper and uitest, trace ingest, typed queries, twenty-three analyzers — frames, frame load, fault tree, binder, threads, memory, memory measure, native memory, hilog, startup, render, GC pressure, VSync anomalies, empty frames, RenderService skips, flamegraph stacks, symbol statistics, component reuse, redundant-file I/O, coverage ingestion, thermal sensors, UI tree and screenshot — baseline comparison, declarative scenarios and a CLI, in one TypeScript toolkit with zero native dependencies.

Node ^22.13.0 || >=23.4.0 · ESM · TypeScript · MIT

ohos-perf — analyze
$ ohos-perf analyze ./scene --json
{
  "metrics": [   /* 81 metrics from the analyzers */
    { "id": "frame.jank.rate", "value": 37.267080745341616,
      "unit": "%", "fidelity": "exact",
      "provenance": { "collector": "hitrace+streamer",
                      "table": "frame_slice", "rows": 177,
                      "device": "offline" } },
    { "id": "fault.arkui.HandleOnAreaChangeEvent",
      "value": 51, "unit": "count", "fidelity": "exact",
      "provenance": { "collector": "hitrace+streamer",
                      "table": "callstack", "rows": 51 } },
    { "id": "binder.transactions.count", "value": 372,
      "unit": "count", "fidelity": "exact",
      "provenance": { "collector": "hitrace+streamer",
                      "table": "callstack", "rows": 372 } },
    /* … 76 more, including binder.latency.avg, thread.*, mem.*, gc.*, */
    /* vsync.*, empty_frame.*, components.*, degraded proxies */
  ],
  "evidence": [ /* 98 items: 60 jank, 7 vsync periods, 6 empty frames, */
                 /* 6 fault patterns, 5 binder hotspots, 1 gc, 1 startup, 6 */
                 /* no_data and 6 degraded-capability notices */ ]
}

Real output from the recorded emulator trace: 81 metrics, 101 evidence items, byte-identical across runs. Every metric carries provenance — collector, table, rows, device.

23capabilities probed
23analyzers over 8 layers
2570unit tests, plus 11 against a real device; 2542 + 28 skipped on a clean checkout
0native dependencies

Why ohos-perf

Closed tools give you answers. This gives you the data.

HapRay and DevEco are excellent at producing a verdict. But their pipelines are opaque, and the emulator cannot produce every signal. ohos-perf exposes each stage as a typed API — and when a signal is unavailable or approximate, it says so instead of inventing a number.

Capability matrix, not guesswork

One probe produces 23 verdicts. Each one records availability, the reason when missing, the evidence command and its output, and the fidelity you should expect.

Deterministic by contract

The same input produces byte-identical JSON across runs. Metrics are sorted by id; evidence is sorted by (kind, window, id). Diffs in CI are meaningful.

Every number is traceable

Metrics carry provenance (collector, table, rows scanned, device) and evidence carries drill-down ids. A claim you cannot trace back to frame_slice is a claim you should not ship.

Honest about the floor

Fidelity is exact, approximate or proxy — never silently upgraded. On an emulator, missing PMU and hiprofiler support is reported with a reason, not a zero.

TypeScript all the way down

Typed queries over 88 tables, an ESM package with a checked public surface, and Node's built-in SQLite. No native build step, no Python, no bundled binary.

Built to be called by agents

The CLI speaks stable JSON, ohos-perf query turns every drillDown handle into the next call, and ohos-perf compare classifies what changed between two captures — including incomparable, which means the direction is unknown rather than nothing changed. skill/ohos-perf/SKILL.md packages that loop, so an agent can go from an evidence item to its frames, callstacks and binder pairs, then check the fix against a baseline, without screen-scraping or parsing prose.

The gesture is inside the window

A scenario step starts the capture, injects its actions while the collectors are running, then awaits the capture — so the tap that caused the work is in the trace, not in a second terminal. setup runs before the window and cleanup after it, so neither pollutes the measurement. A failed action keeps its scene: the trace is still a real measurement of what the device did. Actions record a host-clock atMs, so a gesture is correlatable with the scene's capture.startedAtMs even on devices that refuse /proc/uptime.

Scored against HapRay

Recorded traces pin field-level output for binder, threads and fault tree against HapRay rev 9386e4e. The threads scorer also has a synthetic HapRay golden that exercises the redundancy-scoring path, which the recorded traces cannot: they contain no redundant patterns and no perf samples, so their thread goldens are all-zero. Memory and startup claim no parity.

Analyzers

Twenty-two analyzers over one trace. Every finding carries its evidence.

analyze runs all twenty-three against a scene and merges the result into one report: 81 metrics and 101 evidence items on the recorded emulator trace — memory measure finds no mem.rss rows, the flamegraph and the symbols analyzer no perf_sample rows, frame load no samples at all and native memory no native_hook rows on a plain hitrace capture, so each reports a degraded proxy with the reason — byte-identical across runs. Each analyzer declares the capabilities it needs; when the trace cannot support one, it reports a degraded proxy with the reason instead of a zero.

Analyzer What it measures Metric ids HapRay parity
frames Frame counts, jank rate, whole-span FPS, per-frame jank evidence, stutter levels 1–3 paired against the expected frame and split by ui / render / sceneboard, and fixed 1 s FPS windows frame.* ✓
frame-load Per-frame sampled-event weight inside the frame's own inclusive window, top-10 loaded frames with thread and symbol drill-downs, and the non-overlapping span weight. Needs --hiperf on a debuggable app frame.load.* ✓
fault-tree ArkUI / Render Service / av_codec / Audio signals, ported from HapRay's fault tree fault.* ✓
binder IPC transaction pairing, latency, process/thread/interface hotspots binder.* ✓
threads Wakeup chains, per-thread redundancy scoring, thread-pattern evidence thread.* ✓
memory RSS/PSS peak and mean from /proc samples, growth evidence mem.* —
mem-measure Exact per-process RSS peak and mean from the hiprofiler memory plugin's process_measure, attributed by trace ipid mem.measure.* —
native-memory Alloc and free events from hiprofiler's native_hook, paired per address (LIFO, partial frees) into a running total with peak, trough and end, plus the live allocations at the peak and at the end split per callchain and thread, classified into APP / ArkUI / OS_Runtime / RN / Flutter / WEB / KMP / SYS_SDK. Needs --plugins nativehook on a debuggable app mem.native.* ✓
hilog The device log captured with --hilog, evaluated against a typed rule set — HapRay's four CreatePixelMap rules are the default. Per-rule match counts, sample messages and drill-downs; a line that does not parse is a raw row, counted and never dropped hilog.* ✓
startup Cold-start duration from app_startup, with a start-marker fallback startup.* —
render Live FPS from RenderService refresh-rate deltas and hitch counts above 16.67 / 33 / 66 ms, sampled with --hidumper render.* —
gc GC invocations by phase (full, partial, shared) over the whole callstack span, plus the app's share of perf samples from GC threads gc.* ✓
vsync VSync cadence mismatches and high/low-frequency periods, scoped to the app's own vsync groups vsync.* ✓
empty-frame Frames that rendered nothing, with HapRay's two false-positive filters (a NativeWindow/FlushBuffer call, and a sibling frame in the same vsync), plus their load share and the normal / moderate / severe severity ladder empty_frame.* ✓
rs-skip RenderService DisplayNode skip events reverse-traced through NativeWindow to the app frame they belong to, with a trace-accuracy figure rs_skip.* ✓
flamegraph Folded stacks from perf_sample weighted by event_count, and the app's share of all samples. Needs --hiperf on a debuggable app flamegraph.* —
components ArkUI component builds and recycle-pool reuse from H:CustomNode:Build* trace events components.* ✓

Parity means the algorithm was compared field by field against ArkAnalyzer-HapRay rev 9386e4e. Binder, threads and fault tree are pinned by committed goldens on two recorded traces; the threads scorer and component reuse also have synthetic HapRay goldens, because the traces contain no redundant patterns and no ArkUI build events. VSync, empty frames, RenderService skips and GC reproduce each HapRay rule and threshold in their own tests, and their output on both recorded traces was checked against HapRay during development. Frames, memory, memory measure, startup and the flamegraph have no HapRay equivalent that runs on these traces, so none is claimed; native memory reproduces HapRay's pairing, peak and unreleased semantics and its component table, but its capture is absent from both traces.

Capability matrix

Know what the device can actually give you.

Measured, not assumed. A Mate 60 on OpenHarmony 7.0.0.111 reports 21 of 23 capabilities; the HarmonyOS emulator reports 14. Both numbers are first-class results — the missing ones carry a reason.

Capability Collector Emulator Real device Fidelity
trace.frameshitrace✓✓exact
trace.schedhitrace✓✓exact
trace.binderhitrace✓✓exact
trace.thread_statehitrace✓✓exact
render.vsynchitrace✓✓exact
trace.arkhitrace✓✓exact
perf.sampleshiperf✓✓exact
perf.pmuhiperf—✓exact
mem.procfsprocfs✓✓exact
mem.native_hookhiprofiler—✓exact
mem.gpuhiprofiler—✓exact
power.xpowerhiprofiler—✓exact
net.iohiprofiler—✓exact
disk.iohiprofiler—✓exact
js.heaphiprofiler——unavailable
coveragebjc_cov——unavailable
startup.app_startuphiprofiler—✓exact
render.fps_livehidumper✓✓exact proxy on emu
render.hitchhidumper✓✓exact
hilog.streamhilog✓✓exact
ui.treeuitest✓✓exact
ui.captureuitest✓✓exact
ui.gestureuitest✓✓exact

Measured on 2026-11-16/17 (Mate 60) and 2026-11-17 (emulator). The emulator column is a live caps run; a matrix built from the committed probe snapshot reports 12 of 23 instead, because that snapshot predates the hilog row, the separate uitest dumpLayout measurement (117 KB of output) and the ui.capture row. Rows marked — report a reason through the matrix; they are never silently zero. coverage is gated on bjc_cov (absent on the Mate 60, where aa also prints nothing over plain shell) and stays unavailable because no collector in this package consumes its output. js.heap is unavailable on every device because no analyzer consumes the js_heap_* tables, and the measured hidumper --mem-jsheap route needs a debug-signed or profilerable app.

Architecture

Eight layers. Each one usable on its own.

Start from the transport, or start from a metric. Every layer is a typed seam, so an agent, a CLI command and a library caller walk the same path.

  1. L7

    API / CLI / Skill

    Programmatic API, ohos-perf CLI, named query drill-downs, compare against a baseline, and the shipped ohos-perf agent skill.

  2. L6

    Report

    Metric and Evidence models, provenance, fidelity, stable ordering.

  3. L5

    Analyze

    Twenty-two analyzers: frames with stutter levels and 1 s FPS windows, frame load, fault tree, binder, threads, memory, memory measure, native memory, startup, render, GC pressure, VSync, empty frames with load severity, RenderService skips, flamegraph, symbol statistics and component reuse, with a capability matrix that degrades what the trace cannot support.

  4. L4

    Query

    Eleven typed query classes over the 88 tables trace_streamer produces: frames, processes, threads, sched, instant, callstacks, binder, thread state, startup, perf and memory measurements.

  5. L3

    Ingest

    trace_streamer wrapper, scene artifact layout, read-only database handle.

  6. L2

    Collectors

    hitrace, procfs, hiprofiler, hiperf, hidumper, uitest, screenshot, hilog, jsheap and thermal. One collect runs every requested collector concurrently: --procfs memory samples, --hiprofiler --plugins gpu,xpower,nativehook,memory (the memory plugin records per-process process_measure without needing an app), --hiperf perf.data for a debuggable app (converted into a second perf.db), --hidumper render counters, --uitest the UI tree, --screenshot a real screen capture and --hilog the device log for the capture window. --app is required only by the modes that resolve a pid. A failure restores the previous scene's artifacts rather than presenting a partial scene as complete.

  7. L1

    Device

    Device model, one-shot capability probe, cached CapabilityMatrix.

  8. L0

    Transport

    hdc client: shell, port forwarding, file send/recv, target listing, connect.

Demo

From a device to a report in one flow.

24-second overview. No audio. The numbers come from the recorded emulator trace in the test fixtures.

Use it

Two entry points, same engine.

As a library

import {
  connect, resolveAppIdentity, runAnalyzers, defaultAnalyzers,
  FrameQuery, ProcessQuery, ThreadQuery, CallstackQuery, BinderQuery,
} from '@ohos-perf/core';

// One probe → identity, 20 capability verdicts, evidence.
const device = await connect();
const caps = await device.capabilities();

// Capture, convert with trace_streamer, open trace.db.
const session = await device.collect({
  app: 'com.example.app',
  durationMs: 10_000,
  sceneRoot: 'scenes/demo',
});
const scene = await session.ingest();

// All analyzers, one context. A capability the trace cannot
// support degrades to a named proxy — never a silent zero.
const processes = new ProcessQuery(scene.traceDb);
const result = await runAnalyzers(defaultAnalyzers(), {
  db: scene.traceDb,
  frames: new FrameQuery(scene.traceDb),
  processes,
  threads: new ThreadQuery(scene.traceDb),
  callstacks: new CallstackQuery(scene.traceDb),
  binder: new BinderQuery(scene.traceDb),
  app: resolveAppIdentity(processes, 'com.example.app'),
  window: { startNs: 0, endNs: Number.MAX_SAFE_INTEGER },
  caps,
  deviceId: device.id,
});

console.log(result.metrics, result.evidence);
scene.close();

As a CLI

# Probe the attached device.
ohos-perf doctor

# Machine-readable capability matrix.
ohos-perf caps --json

# Drive the UI first; gestures are their own command.
ohos-perf gesture click 500 800 --json
ohos-perf gesture swipe 500 800 500 200 --velocity 600 --json
ohos-perf gesture key Home --json

# Capture a scene; every collector runs concurrently.
ohos-perf collect --app com.example.app --duration 10 \
  --out ./scene --procfs --hiperf --hidumper --uitest --screenshot --hilog

# Run all analyzers over it.
ohos-perf analyze ./scene --json

# Compare against a baseline capture, by metric and by screen.
ohos-perf compare ./before ./after --json
ohos-perf ui-compare ./before ./after --out ./ui-diff --json

# Fail a CI job when a budget is violated or a metric it names was not measured.
ohos-perf gate budgets.json ./after --baseline ./before --out ./gate --json

# Inspect a package on disk: no device, nothing extracted.
ohos-perf hap app.hap --out ./hap-report
ohos-perf hap app.hap --json

# Boot an emulator when no device is attached.
ohos-perf emulator list --json
ohos-perf emulator start ProbePhone --timeout 300
ohos-perf emulator stop ProbePhone

# Exit codes are real: a failed analysis is 1.
$ ohos-perf analyze ./missing; echo $?
1

Roadmap

Shipped, next, and deliberately honest.

Every phase below ends the same way: a capability is reported available only when the package can actually drive it, and a missing one carries a reason.

Shipped · v0.2.0

The measurable core

P0–P6: capability probing, six collectors, trace ingest, typed queries, fourteen analyzers with provenance and fidelity, deterministic JSON, baseline comparison and the agent skill. 906 tests at release; the release reported 20 of 21 capabilities available on a Mate 60, and P8 later corrected the coverage row to 19.

Shipped · v0.2.0

The rest of the analysis surface

P6: GC pressure, VSync anomaly periods, empty frames with HapRay's false-positive filters, RenderService skips reverse-traced through NativeWindow, folded flamegraph stacks, and ArkUI component reuse. Every one is pinned against HapRay rev 9386e4e — on the recorded traces where they have data, on synthetic goldens where they do not. HapRay's UI animation diff is ported (rows 31-32), narrower by design: a region is labelled only when both the pixels and the tree moved inside it.

Shipped · v0.3.0

Emulator lifecycle

P7: ohos-perf emulator {list,start,stop,create} so CI and an agent can boot their own target instead of relying on an attached device. start waits for bootevent.boot.completed and reports the target collect --target needs; create never downloads an image and prints the exact -install command instead. Verified against a real 6.1.1.200 install: a warm start returns in 4 s, a cold one in 35 s.

Shipped · v0.3.0

Gesture injection, honest coverage

P8: ohos-perf gesture {click,swipe,key,input,text} drives the app through uitest uiInput, reading success from the tool's No Error marker because hdc masks the device exit code. coverage was re-probed against bjc_cov and is now reported unavailable with its measured reason instead of inheriting hiprofiler's presence. The Mate 60 matrix went from 20 to 19 of 21 — the count dropped because a wrong claim was removed.

Measured · not shipped

Deliberately out

`coverage` has no bjc_cov on the Mate 60 and no collector here to consume it; js.heap needs a debug-signed or profilerable app the Mate 60 did not offer, and no analyzer consumes js_heap_*. HapRay's UI animation diff is ported (rows 31-32) and narrower by design: a region is labelled only when both the pixels and the tree moved inside it, because pixels alone are not evidence of an animation. Each is a measured no with a reason, not a zero.

Shipped · v0.4.0

Report artifacts

P9: ohos-perf report <scene> --out <dir> renders one analysis pass as a typed, versioned model and six artifacts — a self-contained HTML page with no scripts and no network, report.json, summary.json, metrics.csv, evidence.csv and a dependency-free XLSX workbook. Identical inputs and the same package version produce byte-identical files; every metric keeps its provenance and fidelity; a capability-skipped analyzer is a labelled degraded section with the device's own reason, never a hidden zero. --baseline adds the typed comparison to every artifact.

Shipped · v0.5.0

Frame load, stutter, FPS windows

P10: every app frame's sampled-event load from one batched perf_sample read, top-10 loaded frames with thread, symbol and file drill-downs, stutter graded 1–3 against the expected frame and split by ui / render / sceneboard, fixed 1 s FPS windows, and empty-frame load share with a normal / moderate / severe ladder. Four new queries — frames.fpsSeries, frame.load.threads, frame.load.symbols, frame.load.files. Two upstream behaviors are deliberately not ported: the ±1 ms window expansion (which inflates load and is why upstream's empty share can exceed 100%) and high_load_frames (an instruction count compared against a percentage). Without perf samples every load metric is a degraded proxy with a reason, never a zero.

Shipped · v0.6.0

Native memory

P11: hiprofiler's native_hook alloc and free events paired per address — LIFO across reused addresses, partial frees leave a remainder — into a running total with peak (earliest on a tie), trough and end. Live allocations at the peak and at the end are split per callchain, process and thread, resolved through the trace's own frame and data_dict tables, and classified by HapRay's component table (APP, ArkUI, OS_Runtime, RN, Flutter, WEB, KMP, SYS_SDK). A capture with only native_hook_statistic reports end-of-capture bytes as a proxy and never claims a peak or a timeline. Four new queries: mem.native.unreleased, mem.native.callchain, mem.native.timeline, mem.native.categories. "Unreleased" means still allocated when the capture stopped — it is not a leak claim.

Shipped · v0.7.0

Hilog capture and rules

P12: collect --hilog streams the device log for the capture window into hilog.log, parsed at analysis time so a rule change is a re-analysis rather than a re-capture. A typed rule set — { name, regex, groups, conditions } — is evaluated by an AST evaluator with no eval: a malformed regex or expression is a typed error naming the rule, never a silently dropped pattern. HapRay's four CreatePixelMap rules ship as the default. The analyzer reports hilog.lines.count, parsed and unparsed, one count per rule, and one hilog_match evidence item per matching rule with up to five sample messages. Three new queries: hilog.matches, hilog.rules, hilog.around. A scene with no log degrades with a reason; a log with no matches is a real zero.

Shipped · v0.8.0

Declarative scenarios

P13: ohos-perf run scenario.json --out <dir> validates a versioned JSON document whole before the first device call, then runs each step's three phases for real — setup before the capture window, actions inside it concurrently with the collectors, cleanup after it always, including after a failed action. Every (round, step) pair writes a complete scene at <out>/<id>/round-<n>/, so a step is analyzed with the same analyze/report/query as any other capture, plus steps.json, testInfo.json and pids.json. A failed action fails the step and keeps its scene; --keep-going continues and the exit code stays 1. HapRay's Python runner parses setup and cleanup and never executes them, and retries a case until its output is non-empty — neither behavior is ported.

Shipped · v0.9.0

UI capture and diff

P14: collect --screenshot pulls a real screen capture into screenshot.png beside the tree, and ui-compare <a> <b> --out <dir> reports what changed both structurally and by pixel — ui-diff.json, an offline ui-diff.html and two marked PNGs. Trees are matched by node identity (bundleName|type|id|text), so an inserted node is one difference instead of shifting every later comparison as HapRay's index matching does. Pixels are compared by a 64-bit dHash and a bounded diff over a ≤256 px downscale at tolerance 8, both reported with the threshold. The PNG codec is pure TypeScript over Node's zlib: no OpenCV, no Pillow, no native build, and palette/16-bit/interlaced images are refused with a typed error rather than mis-decoded. Different screen sizes are UI_SIZE_MISMATCH, never silently rescaled. HapRay's four broken behaviors — capture filenames its comparator cannot find, a CaptureUI.capture_ui that does not exist, an inverted if not regions that drops animations, and index-based child matching — are not ported.

Shipped · v0.10.0

Offline HAP inspection

P15: ohos-perf hap app.hap reads the package itself — no device, no hdc, nothing extracted to disk. A pure-TypeScript ZIP reader over Node's zlib inflates stored and deflated entries and CRC-checks every read, refusing by name what it cannot read honestly (HAP_ZIP64_UNSUPPORTED, HAP_ENCRYPTED_ENTRY, HAP_UNSAFE_PATH, HAP_CRC_MISMATCH). One pass produces a per-file inventory under HapRay's own category table, a technology stack detected by a typed port of its techstack-config.yaml (Flutter, React Native, Hermes, KMP, Compose Multiplatform, Lynx, Qt, Unity, Taro, Weex, Cangjie and the third-party library rules), and the assets worth a second look: duplicate groups confirmed by SHA-256 after a (size, crc32) grouping, and files above their category's threshold. Every match names the rule that decided it; a rule requiring metadata matches only when the file itself yields it. --out writes hap.json and an offline hap.html through the same report model as a captured scene. HapRay's ROI, UX scores and "estimated savings" are not ported — none of them is a measurement.

Shipped · v0.11.0

Symbols that are real

P16: a real perf.db showed that frame resolution was wrong in a way no fixture revealed. perf_callchain.name is not a symbol but a data_dict id, and the old code fell back to the first perf_files row of a file when the exact pair missed — inventing names for 1,972 leaf frames (7.14% of all samples). Resolution is now exact (file_id, symbol_id) only, then data_dict, never a neighbour. The symbols analyzer reports the weight it could name and the weight it could not (9.43% on the measured capture), collect --hiperf --so-dir symbolizes at capture time through the device's own trace_streamer, and report writes an offline flamegraph.svg + flamegraph.html from the same folded stacks. New query: symbol.stats.

Shipped · v0.12.0

Scenarios that select and assert

P17: a scenario action used to be a raw coordinate — a claim about one resolution. It is now a selector over the captured UI tree: ten kinds (`text`, `id`, `type`, `clickable`, `all`, `any`, `not`, `index`, `bounds`, `relative`), validated as data with the JSON path in every refusal. `tap`/`tapText` resolve the node and click its centre; a node whose bounds did not parse is refused rather than tapped at (0,0). `scrollTo` swipes its container from 70% to 30% of the height, re-dumping after each swipe, up to five times, and stops at the list's edge — the refusal says how many swipes it actually spent. `swipeArea` and `inputInto` cover carousels and text fields. A step's `expect` block — `present` with `min`/`max`, `absent`, `foreground` — runs against a fresh dump after the actions and before cleanup, records every clause in `steps.json`, and marks the step failed while keeping its scene. HapRay's DSL parses `verify` and never runs it; ours runs. `run --cases

` runs a directory of scenarios as one suite with an anchored `--filter` and a `cases.json` index, refusing an empty match instead of reporting a silent zero-case pass.

Shipped · v0.14.0

Both ways to trace a skipped frame

P19: RenderService skip reverse tracing ran only HapRay's NativeWindow path. It now runs both. The system-API path reads an UnMarsh RSTransactionData event on an RS IPC thread — its name carries the submitting pid (recv data from <pid>) — then follows sched_wakeup back, directly or up to five hops, to the app thread whose frame was submitted. That is what makes ArkUI, RN and KMP skips visible at all. The waste is charged twice over: milliseconds from the traced frame's duration, and rs_skip.cpu_waste.instructions from the app process's sampled weight inside it. rs_skip.traced.rs_api.count and rs_skip.traced.nativewindow.count say which method produced each trace, and every evidence sentence names it. Both new metrics are absent — never zero — when there is nothing to measure.

Shipped · v0.15.0

An animation is not just a moving pixel

P20: ui-compare compared a start/end capture pair structurally and by pixel but emitted no animation label. It does now — and requires both halves to agree. A region is an animation only when its pixels moved and the tree reports a change inside it, because HapRay's pixel-only rule also fires on a blinking cursor, a video frame or a system clock, none of which the app re-rendered. ui-diff.json carries three lists: animations with HapRay's severity bands (major under 50% similar, moderate under 70%, minor under 85%), pixelOnly for the screen moving without the tree, and unmeasuredRegions for regions too small for the 9×8 dHash grid to say anything about. A tree change the pixels did not show is a rendering defect, and is left to the tree diff where it belongs.

Shipped · v0.16.0

A trend only where the runs are comparable

P21: `report` wrote one bundle from one scene, and `compare` compared two. HapRay's multi-version page drew a trend across any files it was handed, because its page had no model that could refuse. `trend --out

` refuses what makes a trend false — fewer than two reports, a duplicate label, two different apps — and makes the rest visible: a metric a run did not emit is a gap, never a zero, and so is a degraded stand-in; a delta runs between the first and last run that actually measured it; a verdict appears only where the metric has a known direction; and the ordering is stated, by capture time when every run recorded one and by argument otherwise. `trend.html` carries an inline SVG sparkline per metric with no scripts and no external resources, and `trend.json` is the same model.

Shipped · v0.17.0

A saved report renders as it was measured

P22: HapRay's `update` re-runs the whole pipeline from the scene, so an old report becomes a function of today's code — two people opening the same saved run on different versions see different numbers. Ours does not. `report.json` is a typed model, and every artifact but the flamegraph is a pure function of it, so `render --out

` reproduces `report.html`, `report.json`, `summary.json`, `metrics.csv`, `evidence.csv` and `report.xlsx` byte for byte from the model alone — no scene, no device, no analyzer. Verified by deleting the source scene before re-rendering. The flamegraph is absent rather than empty: its folded stacks live in `perf_sample`, not in the model, and an empty canvas would picture a capture in which nothing ran. This closes the last partial row: 30 ported, 0 partial, 0 missing, 5 refused with a named prerequisite.

Shipped · v0.18.0

A walk that can be repeated and can tell you what it saw

P23: HapRay's haptest dumps the screen, hashes it and taps an unvisited element — but its random strategy is unseeded, so two runs of the same build explore different screens, and it counts every tap as progress, so a tap on a dead button looks exactly like one that opened a screen. explore <app> keeps the shape and fixes both. Every order is a total order: depth-first is the dump's pre-order, breadth-first sorts by depth and is stable within one, and random is a seeded permutation whose seed is reported, so a walk replays. A tap that leaves the hash unchanged is recorded no change, and the summary leads with states reached rather than taps spent. Visited is per screen, because a node id is unique within one dump and two screens can both have button1. After each tap it polls until the screen changes instead of HapRay's flat 5 s, so the wait is a ceiling only a dead element pays. An unparseable rect is skipped rather than tapped at (0,0), and a target that left the screen fails instead of clicking whatever moved in.

Shipped · v0.19.0

Coverage you can read without shipping the compiler

P24: HapRay does not measure coverage — it shells out to bjc, which needs an instrumented build, a debug HAP, an on-device cache, aa dump and a matching source path. When any of that is missing its analyzer returns None, so the section disappears and a reader cannot tell "never measured" from "0% of lines ran". analyze now reads the coverageReport.json that bjc writes — the same document HapRay's own HTML template renders — and reports line, function and branch percentages as approximate, naming the file they came from, because the instrumented build is not the app a user runs. Percentages are recomputed rather than taken from the producer's pct, a total of zero is 0% rather than NaN, and a report claiming 120% of lines ran is refused by name. A scene with no report gets a no_data item saying coverage was not measured — the distinction the silent skip cannot make.

Shipped · v0.20.0

Optimization level from the ELF, not from a 2 GB model

P25: HapRay answers "was this built optimized, and with LTO?" with a ~2 GB TensorFlow LSTM over raw .text bytes plus a 551-feature SVM, and prints the guess as a percentage — its own source records 16.7% false positives on low-optimization binaries. opt <package|lib.so> reads what the ELF records instead. LTO is exact: lto_priv.* symbols and .gnu.lto_* sections prove it, and their absence from a file that still has a symbol table proves the opposite — a stripped file says unknown, because the markers may have been removed. A -O flag in .comment states the level outright. Only when nothing recorded it does the instruction mix decide, and that verdict is labelled inferred with its signals named. Validated against real release libraries: libflutter.so measures 23.5% SIMD and reads high, which is exactly HapRay's own verdict on the same file — while this one says which half it measured.

Shipped · v0.21.0

A model-driven walk whose success is checked, not claimed

P26: HapRay's gui-agent wraps the external phone_agent package: the model sees a screenshot, answers with one action, and says finished when it believes the task is done — and that flag is recorded as success. Three things make its output unusable as a measurement, and each is fixed rather than reproduced. A done answer must carry an expectation, evaluated against the screen; a claim the screen contradicts is unverified and exits non-zero, and so is a bare done with no assertion. The safety rule is code, not a prompt sentence — and HapRay's sentence is weaker than it reads: phone_agent ships a confirmation callback, but it fires only when the model labels its own tap, covers Tap alone, and HapRay passes none, so the default is a blocking input() that raises EOFError in a batch run: a tap or text entry is resolved to the node it lands on — reading the node's text and its id, with _ read as a word break so pay_button is caught — and an irreversible target is refused before the device sees it. A tap that misses every labelled control is checked against a 24 px margin, because a measured model aimed 15 px below a checkout screen's only button — on its padding, inside the hit region — and strict containment waved it through; a tap on a different clickable control is still performed, so stacked buttons do not block each other. Every step records the gesture and the screen hash either side of it, so replayAgent re-walks a transcript with no model and stops at the first screen that differs. The client is injected, never bundled: httpAgentModel speaks OpenAI-compatible /chat/completions over an injected fetch, and with no endpoint configured the command names the variables to set instead of sending a task to a host nobody named.

Shipped · v0.22.0

Function boundaries from the symbol table, and an accuracy you can check

P27: HapRay's symbol_recovery shells out to radare2 for function boundaries and asks an LLM to name what it finds — and never measures whether the name is right. Its own documentation records the heuristic it rests on: a function over 100 KB is "unreasonable, skip", and a lookup it misses gets a default size of 2000 bytes. An ELF already answers the boundary question exactly, because every STT_FUNC symbol records st_value and st_size, so symbols recover <lib.so> <address...> finds the containing function by lookup. The recorded size is authoritative — a function followed by padding is not stretched to the next symbol — an offset past every function is unresolved rather than blamed on its predecessor, and a stripped file says it cannot recover instead of guessing. --measure adds the number HapRay never states: names the file does record are held out, the model names them from their instruction mix and bytes — never their names — and the report says how many it got right, so a run states an accuracy rather than presenting a guess as a fact.

Shipped · v0.23.0

A root-cause report that checks what the model claims

P28: HapRay's root-cause reads its own report JSON files, hands the summaries to a model, and writes Markdown — so the model sees a summary of a summary and never the measured numbers. It cannot run without an endpoint either: --skip-llm writes "Pending Agent Inference" placeholders, which is an empty artifact, not an offline one. root-cause <scene-dir|report.json> feeds the Evidence items directly, each with its measured signals, and ranks them by our own severities in a total order, so two runs of one capture produce identical bytes. The verdict is the highest finding's own sentence, and observations that report a gap in the capture — a skipped analyzer, a missing artifact, any item carrying no measured signal — are counted separately and kept out of it: a first version opened with "hilog skipped: capability not probed", which says nothing about performance. A model may add suspects, but every citation must name an evidence id the run produced and every file, symbol or thread it mentions must appear in what the evidence carried; anything else is marked ungrounded in place, because a footnote is read after the fix has been applied. Running it against a live endpoint is what caught the check's own two defects: it flagged the analyzers' own ui.json and thread_state, and it flagged "Re-run" as an invented name because of the hyphen.

Shipped · v0.24.0

Model-guided exploration that checks every choice

P29: HapRay's haptest asks a model which numbered element to tap and trusts the answer — an index past the end of its list clicks element 0, an unparseable answer clicks the first element, and a failed call clicks the first button — then spends a second model call per transition deciding whether the screen counts as a new page. explore --model keeps the offer and checks the answer against it: an index outside the list, an action the screen does not allow, or a non-JSON reply is a recorded refusal naming the step, and the deterministic order takes that step instead. Page identity is hashPageShape, a digest of the tree's structure, so navigated, updated and no change are measured rather than asserted. The walk scrolls the first scrollable node up to three times and goes back once per screen when nothing unvisited is tappable, rebuilds its trail from the pages it actually reached, never offers an irreversible target to a model, and never lets the model supply a coordinate. A refusal list is what tells a model stuck from a model working; without one, both produce the same step count.

Shipped · v0.25.0

Thermal curves read from the device, not a hard-coded sensor list

P30: HapRay's thermal analyzer returns None when a step has no thermal_data.jsonl, so a scene that never sampled temperatures and a device that stayed cool produce the same report — nothing. collect --thermal samples hidumper -s ThermalService -a '-t' for the capture window into thermal.jsonl, one record per sample carrying the elapsed time and every reading's raw value, the unit inferred for it, and the normalized Celsius value. The unit rule is HapRay's, applied per reading rather than per device: a magnitude of at least 1000 is millidegrees and anything smaller is plain Celsius — the Mate 60 reports all nine sensors in millidegrees, while another recorded device reports modem at 27. analyze reports start, end, peak, mean and rise per sensor, the sample count, the capture duration and the median interval, and a scene without a capture gets a no_data item naming --thermal instead of a missing section. Sensors are whatever the device printed, so a device without a modem never gets a fabricated modem curve; a sensor absent from one sample contributes no value rather than a zero or the previous reading carried forward. --thermal-interval sets the 5 s default, and a scenario step can list thermal in capture.collectors, so a run gets one thermal curve per step.

Shipped · v0.32.0

The defect, found in the source and ranked against the symptom

all 21 cases, case by case." data-zh="P37:此前本包的每一项分析都从运行中的设备开始,想知道列表为什么卡的人必须先采集。现在 suspects <root> 只凭源码就能回答。扫描器把 ArkTS 当文本加花括号跟踪来读 —— 不是解析器,因为 struct 上的装饰器与 builder 语法会打破任何 TypeScript 文法 —— 并处理了让逐行读法出错的几件事:正则字面量里的引号、参数表跨行的方法、初始化式跨行的字段,以及 CRLF。十七条规则对应 OhmBench 记录的缺陷形状。报告的症状就是排序输入:--prompt prompt.json(基准自带的文件)或 --symptom/--scenario 会把报告收窄到能解释它的那些发现,中英术语表把“文章列表”对上 ArticleListView。仅这一步收窄就把精确率从 0.344 提到 0.590。在 OhmBench 的 21 个盲测用例上 —— 只有源码与 prompt.json,没有 ground truth、没有补丁、没有 git 历史 —— 精确率 0.857、召回率 0.929,由基准自己的匹配器打分。HapRay 在同样的输入上给出零个代码位置,这是实测的:把 21 个盲测树逐个作为 --report-dir 跑它的 root-cause,每次都以“未发现可用的性能信号产物”作答,不点名任何文件。六个不完美用例中有一个仍是排序漏判而非检测漏判,其余是命名屏幕过滤的代价;每一处漏判与原因都写在 bench/ohmbench/RESULTS.md 里,而不是被平均掉。">P37: every analysis this package had started from a running device, so a reader who wanted to know why a list stutters had to capture it first. suspects <root> answers from the source alone. The scanner reads ArkTS as text with brace tracking — not a parser, because decorators on struct and builder syntax break every TypeScript grammar — and it handles what made a line-oriented reader wrong: a quote inside a regex literal, a method whose parameter list wraps across lines, a field whose initializer spans lines, and CRLF. Seventeen rules name the shapes OhmBench records. The reported symptom is the ranking input: --prompt prompt.json (the benchmark's own file) or --symptom/--scenario narrows the report to the findings that can explain it, and a Chinese-to-English glossary matches "文章列表" to ArticleListView. Narrowing to what the prompt explains moved precision from 0.344 to 0.590 in one step. On OhmBench's 21 blind cases — source and prompt.json, no ground truth, no patches, no git history — precision 0.857, recall 0.929, scored by the benchmark's own matcher. HapRay returns zero code locations on the same input, measured by running its root-cause action over all 21 blind trees: it accepts one as --report-dir and answers "未发现可用的性能信号产物" without naming a file. One of the six imperfect cases is still a ranking miss rather than a detection miss, and the rest are the price of the named-screen filter; every miss and its reason is in bench/ohmbench/RESULTS.md rather than averaged away.

Shipped · v0.33.4

Somebody else's workload, on a real device

), the enabled selector compared a synthesized flag where the reference compares the dump's own attribute, scroll_to swiped without the velocity too, an unmarked node did not inherit its nearest ancestor's bundleName the way the reference does, and type_keys sent one inputText per character where the reference sends a single uinput -K burst." data-zh="P39:此前本包的每一次测量都从我们自己写的场景开始。基准会发布自己的场景,而 workload <plan.workload.json> 原样运行它:HapRay PerfTestCase 读取的 setup / measured / verify 三段,加上运行框架自己的先停后启前奏 —— 已发布的计划依赖它,没有它时,第一个动作是 wait 的计划会停在桌面上并在自己的第一个断言处失败,这是第一次试跑就测到的。setup 在采集之前运行,measured 在采集窗口内运行,verify 在其后;measured 失败仍会把采集做完,因为 trace 是对实际发生了什么的记录,而超过 --duration 的阶段会失败并同时点名两个数字。计划在解析设备之前整体校验。在模拟器上驱动 OhmBench 的 21 个用例 —— bench/ohmbench/dynamic/ 负责构建、签名、安装与运行 —— 发现了一个源码轴永远无法暴露的缺陷:所有按应用归属的分析器,在一条满是该应用的 trace 上都报告 no_data。trace 记录的是内核 comm,上限 15 个字符(com.hefengbao.jingmo.hw 存成 ngbao.jingmo.hw),而普通 hitrace 完全没有记录 pid。resolveAppIpids 现在会回退到名称匹配,collect 把应用的 pid 写进 scene.json;在同一条 trace 上重跑 analyze,降级的分析器从十二个减到真正缺数据的那些。21/21 构建并签名,19/21 安装 —— 两个 cloudmusic 用例都被拒绝 ohos.permission.SYSTEM_FLOAT_WINDOW,debug 配置无法授予 —— 21 个用例中有六个把自己的工作负载跑完并完成分析,其中三个由 root-cause 给出 critical 结论。其余每个用例都列出了它自己的计划失败在选择器上的那一步,因为基准没有为它提供预置数据。动态运行还发现了一个保真度缺陷:运行器发送的 uitest uiInput swipe 缺少参考驱动会带的速率参数,实测一次滑动 5.15 秒,带上参数则是 3.21 秒。随后逐行比对两个驱动又发现五处:选择器会排除 dump 未写 enabled 的所有节点(参考实现只跳过显式的 enabled="false"),enabled 选择器比对的是合成出的标志,而参考实现比对 dump 自带的属性,以及 scroll_to 的滑动同样没有带速率,未标注的节点也没有像参考实现那样继承最近祖先的 bundleName,type_keys 还逐字符发送 inputText,而参考实现发送单条 uinput -K 连发。">P39: every measurement this package had started from a scenario we wrote. A benchmark publishes its own, and workload <plan.workload.json> runs it unchanged: the setup / measured / verify shape HapRay's PerfTestCase reads, with the harness's own stop-then-launch preamble — the published plans rely on it, so without it a plan whose first action is wait starts on the home screen and fails at its own first assertion, measured on the first plan tried. setup runs before the capture, measured inside it, verify after; a measured failure finishes the capture anyway, because the trace is a record of what happened, and a phase that overruns --duration fails naming both numbers. The plan is validated whole before a device is resolved. Driving OhmBench's 21 cases on the emulator — bench/ohmbench/dynamic/ builds, signs, installs and runs them — found a defect the source axis could never surface: every app-attributed analyzer reported no_data on a trace full of the app. The trace records the kernel's comm, capped at 15 characters (com.hefengbao.jingmo.hw is stored as ngbao.jingmo.hw), and a plain hitrace recorded no pid at all. resolveAppIpids now falls back to a name match, and collect records the app's pids in scene.json; re-running analyze on the same trace cut the degraded analyzers from twelve to the ones that genuinely lack data. 21/21 built and signed, 19/21 installed — both cloudmusic cases are refused ohos.permission.SYSTEM_FLOAT_WINDOW, which a debug profile cannot grant — and six of the 21 ran their own workload to completion and were analyzed, three of them ending in a critical verdict from root-cause. Every other case is listed with the selector its own plan failed at, because the benchmark ships no prepared data for it. The dynamic run also found a fidelity bug: the runner sent uitest uiInput swipe without the velocity the reference driver sends, and a swipe measured 5.15 s against 3.21 s with it.

Shipped · v0.33.5

A capture that recovers from its own aborted run

P40: a hitrace --trace_begin left recording by a killed process answers error: OpenRecording failed, errorCode(1103) to every later begin on that device, and collect threw on that answer before it reached the best-effort stop it already had — so one killed sweep made every capture on the device fail. Observed here as a 21-case run that recorded 0/21, every case stopped at measured on the same 1103. collect now recognises 1103, stops the stale recording with --trace_finish_nodump, and retries the same begin once; two failures in a row raise with both attempts named, and a begin that failed for any other reason is not retried and stops nothing. The same sweep found two more: aa start exits 0 for a bundle that is not installed, so three call sites recorded a start for an app that was never there — the workload runner, the scenario runner and collect --cold-start now read the device's own failed to start ability line — and the CLI had been importing a published core nested under packages/cli/node_modules, which beat the workspace link and meant the built CLI ran the previous build.

Shipped · v0.32.3

A review that was wrong four times, and the four times it was right

P38: an external review of the suspects scanner produced eleven findings. Six were real; five described failures the code does not have, in the same confident register as the real ones. Both halves are published at docs/reviews/2026-11-19-codex-p37-suspects.md, each claim reproduced or refuted against the code before anything changed. The review's only Critical — apply the confidence tier before the name filter — is accurate about the code and wrong about the fix: applied as written it measures precision 0.738 and recall 0.833, three cases worse, because the name filter answers which question and confidence answers which answer within it. It was reverted and the tradeoff is pinned by a test. What shipped is narrower and duller: a SQL concatenation is followed to the end of its statement instead of only through quote-leading lines; loop depth is counted on noise-stripped text, so a for (…) inside a string is not a loop; executeSql has to name a write before it counts as one; a cap or a destroy() is searched in the class that holds the finding, not the file; duplicate module statements report their own lines; and a regex after a keyword is a regex, not a division. Nine call sites also spread a user-sized array into Math.max, which throws somewhere between 124k and 150k arguments — they now use maxOf/minOf. OhmBench is byte-identical: precision 0.857, recall 0.929.

Shipped · v0.26.0

A budget that fails a build on a metric nobody measured

P31: compare says what moved; a budget says how much movement is allowed, and gate <budgets.json> <run> [--baseline <run>] turns that into an exit code a CI job reads. The document is versioned and validated whole before a scene is opened — an unknown key, a duplicate metric id, an entry with zero or two bounds, or a delta budget with no baseline names the budget ids and the flag to add, so a budget typo never fails after a two-minute capture. Four bounds: max/min are absolute limits in the metric's own unit, maxDelta/maxDeltaPct are limits on movement from the baseline, and a negative delta limit is legal — it says the metric must fall. The design rule is that a metric which was not measured is a failure: a metric the run never emitted, a degraded proxy, a non-numeric value and a percentage against a zero baseline are all missing, never a pass, so a green build cannot mean an analyzer stopped running. Exit 0 all passed, 2 a budget failed or could not be measured, 1 the gate could not run — a verdict and an error are different codes on purpose. --json still exits 2 on a violation, and --out writes gate.json. HapRay's regression story at its pinned revision is a chart a person reads, with no threshold, verdict or exit code anywhere in the tree.

Shipped · v0.27.0

A root cause that knows what changed

P32: `root-cause` explained one run. After a regression the question is what changed, and `root-cause --baseline <run>` answers it: `buildMovement` compares the two runs' metrics and evidence counts and returns one row per metric — `regressed`, `improved`, `unchanged`, `incomparable` or `gap` — plus a per-kind count of findings on each side. A gap means that side did not measure the metric (absent, or a skipped analyzer's degraded zero): it carries a reason and no delta, so a jank rate that disappeared can never read as "improved from 12% to 0". The direction is the caller's, baseline → input, whatever the capture times say — `trend` sorts by time because its x axis is time; a movement that did the same would invert every verdict when a baseline was captured later. The movement is rendered before the verdict, carried into the model's prompt, and a suspect's new `metrics` citations are checked against its rows exactly like evidence ids. Two runs for different apps are refused naming both, before a model is asked. HapRay's multi-version page leaves the comparison to a human reading dropdowns, and its root cause sees one run.

Shipped · v0.28.0

One envelope for every command

P33: every command answers in one versioned envelope under --machine-json (one line on stdout) or --result-file (the same document on disk) — schemaVersion, toolId, command, success derived from exitCode, the command's own payload, and the failure as a typed error whose code is the token stderr prints first. success is exactly exitCode === 0, so a caller cannot describe a failed run as a successful one, and a gate verdict of fail is exit 2 with no error: the tool ran and the news is bad. parseToolResult validates on the way back in — unknown schemaVersion, another tool's toolId, and a success that contradicts exitCode are refused by name — which HapRay's write-only machine_output.py never does, and no result file is written unless asked.

Shipped · v0.29.0

Every command is an MCP tool

P34: ohos-perf mcp serves every command as an MCP tool over stdio. The tool list is derived from the CLI itself — one tool per leaf command, named ohos-perf_, with that command's own options as its inputSchema — so there is no second list to drift and a new command is a new tool. Each call runs the command with --machine-json and returns the envelope as structuredContent, so an MCP answer is byte-identical to the shell answer; isError means the command could not run, never that the news is bad. The server answers both protocol eras: modern 2026-07-28 (server/discover, version in _meta) and legacy 2025-11-25 (initialize), because a client that predates the handshake change should not have to be upgraded to be measured. Framing is newline-delimited JSON-RPC 2.0 written here — about 150 lines rather than a 7 MB SDK. HapRay has no MCP surface at any revision.

Shipped · v0.30.1

The captured heap is analyzed, not just saved

P35: HapRay's row 20 captures a .heapsnapshot and analyzes nothing, so a heap is a file a person opens in DevEco Studio and no report mentions. analyze now reads jsheap.heapsnapshot and reports total heap, node count, detached count and object count as exact metrics, plus the largest constructor by self size — a detached node is the shape of a leak, and no other capture in this package can show one. The reader streams the document instead of JSON.parse-ing it — one aggregate pass, nothing allocated per node and the two number arrays streamed rather than held: 12.3 MB peak against 19.6 MB for a full parse of the same 9.4 MB file, and 30.1 MB against 106.5 MB on a 50 MB one, measured (P36 materializes the graph for retained size and moves that 50 MB figure to 77.4 MB) — and indexes every field from snapshot.meta rather than a hardcoded offset, and treats to_node as the node-slot offset V8 actually writes. A snapshot is a collector artifact, so it is read only when scene.json declares the jsheap collector; a scene without one gets a no_data item naming --jsheap. The device route stays unavailable for a reason that is now measured: with a debug-signed app running, hidumper --mem-jsheap exits 0 and writes no file, and its -T takes a thread id — the collector was passing the pid.

Shipped · v0.31.0

The heap report says what holds the memory

P36: self size answers “how many bytes is this node”, which is not what a heap snapshot is for — an Array holding ten megabytes has a self size of a few hundred bytes. Retained size, the bytes that become unreachable when a node is collected, comes from a dominator tree over the whole graph (iterative Cooper–Harvey–Kennedy in typed arrays, 665 ms at 861 605 nodes and 2 268 808 edges, ~70 rounds). On a real 9.4 MB snapshot the ranking flips: Array holds 3.78 MB of its own 0.62 MB and leads, where self size puts Object first. jsheap.retained.largest.bytes and jsheap.unreachable.count join the metrics, and the evidence names the largest retained holder with self size beside it. Unreachable is counted separately from detachedness because an embedder annotation and a graph fact can legitimately disagree — which is what a leak hunt looks for. Past a documented ceiling (20 million edges or 4 million nodes — the working set is ~53 bytes a node, so edges alone were not a memory bound) the graph is not built and the heap totals are reported with the omission named, rather than dying out of memory. A weak edge is not a reference: it is validated and counted in the heap total but kept out of the graph, so a Map that merely mentions a payload does not look like its owner. The graph costs memory and that is measured: the 50 MB fixture's peak moved 30.1 → 77.4 MB, still below JSON.parse's 106.7 MB, pinned by a test.

Shipped · v0.26.0

One release per workstream

A source-level inventory of HapRay rev 9386e4e found 35 user-facing capabilities. P9 shipped the report layer, P10 frame load and stutter, P11 native memory, P12 hilog, P13 the scenario runner, P14 UI capture and diff, P15 offline HAP inspection, P16 symbol intelligence, P17 selector-driven scenarios and P18 the last four gaps. P28 re-pinned the inventory to rev bd5c98a — 428 commits later — and appended the four capabilities those commits added. Every row now lives in a machine-checked ledger: 38 ported, 0 partial, 0 missing, 1 out. Row 38 left the missing list in v0.24.0: the model's choice is kept and its answer verified against the offer, while HapRay's second call about whether the screen changed is replaced by a structural digest. Row 39 left it in v0.25.0: thermal sensors are read from the device, and a scene without a capture says so with no_data instead of HapRay's silent None. The out row is build, which wraps deveco-cli to compile a debug HAP: a build tool, not a measurement, and a package analyzer cannot own the toolchain that compiles the package it reads. HapTest exploration, coverage, the optimization detector, the LLM GUI agent and radare2 symbol recovery all left the refused list: the first was a defect in HapRay's implementation rather than a prerequisite, the second needed only its report read, the third needed the ELF read rather than a ~2 GB model shipped, the fourth needed the model trusted less rather than a network dependency dropped, and the fifth needed the ELF's own st_value/st_size rather than a disassembler — plus an accuracy measurement HapRay never states. A test fails if a ported row names an analyzer the engine does not register, so the claim cannot drift again. P31 goes past the inventory rather than into it: HapRay has no budget or gate concept at any revision, so gate adds a capability the ledger cannot express, and the counts stay 38 ported, 0 partial, 0 missing, 1 out.

Quickstart

Install, capture, analyze.

Published on npm as @ohos-perf/cli and @ohos-perf/core. Node ^22.13.0 || >=23.4.0, and an hdc + trace_streamer from a DevEco Studio installation.

1

Install the CLI

Globally, or run it once with npx. The library is @ohos-perf/core.

2

Check the device

doctor verifies hdc, trace_streamer and the attached target before anything is captured.

3

Capture a scene

Add --procfs for memory sampling, --cold-start for a launch capture, or --hiprofiler --plugins memory for exact per-process RSS without an app.

4

Analyze offline

No device? Point the analyzer at an existing trace.db and get the same metrics.

$ npm install -g @ohos-perf/cli      # 0.33.4 on npmjs

# Probe the attached device (real or emulator).
$ ohos-perf doctor

# Capture 10s of the app, with memory sampling and a cold start.
$ ohos-perf collect --app com.example.app \
    --duration 10 --out ./scene --procfs --cold-start EntryAbility

# Run all analyzers over the scene, offline.
$ ohos-perf analyze ./scene --json

# Or render an offline report bundle (HTML, JSON, CSV, XLSX).
$ ohos-perf report ./scene --out ./report --baseline ./before

# Drive a sequence and capture each step: one scene per (round, step).
$ ohos-perf run scenario.json --out ./runs --json

# Or let it walk the UI itself, and say which screens it reached.
$ ohos-perf explore com.example.app --max-steps 20 --json

# The library: the same pipeline as typed calls.
$ npm install @ohos-perf/core