pm-perf-tracing
Performance-trace Nub package-manager installs using the existing phase timings, structured diagnostics, and sampling-profiler workflow. Use when an install or package-manager operation is unexpectedly slow and the bottleneck needs to be localized before changing code.
- License 许可
- MIT
- 所属仓库
- nubjs/nub
- 最近更新
- 2026-11-14
- Stars
- ★ 4.4k
- Forks
- 71
01 前言 Front Matter
- name
- pm-perf-tracing
- metadata
- { "internal": true }
- description
- Performance-trace Nub package-manager installs using the existing phase timings, structured diagnostics, and sampling-profiler workflow. Use when an install or package-manager operation is unexpectedly slow and the bottleneck needs to be localized before changing code.
03 SKILL.md 正文
pm-perf-tracing
How to performance-trace the nub package manager (install/resolve/fetch/link) and find where the time actually goes — the method that cracked the hoisted-linker slowness (10.8s → root-caused to a per-file copy loop). Reach for this any time a nub install / PM operation is "mysteriously slow" — do NOT reverse-engineer from source; the instrumentation already exists, turn it on.
The two layers that already exist
-
Phase timings — works under nub TODAY.
RUST_LOG=debug nub installemitsphase:<name> <elapsed>lines on stderr:phase:resolve,phase:fetch (N packages),phase:link (N files),phase:link_bins. This alone tells you the coarse split (is it network/resolve, or linking?). The aube engine wires these through thetracingcrate. -
Rich diagnostics layer — native under nub via
NUB_DIAG_*.aube_util::diagemits structured JSONL toNUB_DIAG_FILE=<path>— including, for the linker, one event per file naming the strategy used (link_clonedir,link_reflink,link_macos_small_copy,link_copy,link_hardlink). This is the load-independent crux for a link-perf question. The full knob set (all off by default, zero cost when unset):NUB_DIAG_FILE=<path>— JSONL events to a file.NUB_DIAG_PRINT=1— live per-span lines to stderr.NUB_DIAG_SUMMARY=1— end-of-run aggregate table.NUB_DIAG_CRITPATH=1— retain records for the critical-path / lifecycle / starvation analyzers.NUB_DIAG_THRESHOLD_MS=<n>— filter live prints below<n>ms.NUB_DIAG_KERNEL=1—getrusagekernel deltas around phases.NUB_BENCH_PHASES_FILE=<path>— per-run phase-timing JSON for the bench harness.
cargo build -p nub-cli --profile fast # dev binary at <worktree>-target/fast/nub
NUB=<worktree>-target/fast/nub
NUB_DIAG_FILE=/tmp/d.jsonl NUB_DIAG_SUMMARY=1 "$NUB" install --offline
grep -o '"name":"link_[a-z_]*"' /tmp/d.jsonl | sort | uniq -c # per-strategy tally
(The diag layer reads NUB_DIAG_* under the nub embedder profile via the diag_env_prefix hook — no source edit needed. AUBE_DIAG_* is NOT read under nub. The dev-tracing-telemetry thread / wiki/research/dev-tracing-telemetry.md tracks the optional chrome-trace/flamegraph export layer on top.)
The measurement discipline (load-independent — this host is permanently contended)
The dev box runs load ~30–50 and never goes quiet, so absolute wall-clock is untrustworthy. Measure things contention can't ruin:
- Verified-clean warm loop:
rm -rf node_modulesand assert it's gone, warm store already populated,--offline(proves zero network:phase:fetchshows0 packages), and check rc=0 on every run (a timing from an errored install — e.g. npm'srm: Directory not emptypurge failures → rc=254 — is garbage). - Strategy tally, not seconds: "75,079/76,167 files took
link_macos_small_copy, 0 tooklink_clonedir" is a fact regardless of load. That's what proves a design gap. - Back-to-back A/B on the same box, report the RATIO: e.g. hoisted vs
--node-linker isolatedon the same fixture, same load window → the relative delta (≈26×) is robust even when both absolutes are inflated. - For a real clean wall-clock number, hand it to a quiet machine / CI runner — never block on this box settling.
Layout matters — always check which linker path runs
nub mirrors the incumbent layout: an npm/yarn/bun lockfile → hoisted layout (link.rs → hoisted::link_hoisted_importer); nub-identity / --node-linker isolated → isolated layout (materialize_into, the only path with the whole-dir clonefile(2) fast path). They have completely different perf characteristics. When a perf question is about linking, run BOTH (--node-linker isolated vs default) and diff — that A/B is what localized the hoisted-linker gap.
When spans aren't enough — sampling profiler
Span/JSONL instrumentation can distort a syscall-bound, parallel pass (observer effect). For "where inside the link phase do the syscalls go" use a sampling profiler on a release build: samply record -- <NUB> install --offline (macOS/Linux), or cargo flamegraph. Spans tell you which phase/strategy; the sampler tells you which syscalls/functions dominate.
Fixtures
/tmp/coffee2-demo— CoffeeScript 2.0.1, npmlockfileVersion:1, 519 pkgs / ~76k hoisted files. The canonical heavy-hoisted-layout fixture.- A minimal hoisted repro: a
package.json+package-lock.jsonwithwebpack@3.6.0+underscore(nonode_modules).
The one-liner to remember
RUST_LOG=debug nub install for the phase split; if it's phase:link, set NUB_DIAG_FILE=… for the per-file strategy tally; A/B against --node-linker isolated; judge by strategy-tally + ratio, never the contended absolute.
04 同仓库更多 Skills
nub
暂无简介
nub
This project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.
worktree
Create and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the shared CARGO_TARGET_DIR (`~/.cache/nub/shared-target`) that all worktrees reuse, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.
windows-vm-test
Run ad-hoc Nub tests and debugging probes in the maintainer's existing local Windows 11 ARM64 QEMU/HVF VM when its external disk and runbook are present. Use for interactive win32-arm64 or Windows-on-ARM x64-emulation checks; use ci-adhoc-test for true x64-native behavior or when the local VM is unavailable.
visual-review
Verify UI/layout/styling changes are correct by computing occlusion, clipping, and alignment from the browser's resolved paint order via the chrome-devtools MCP `evaluate_script` tool — instead of eyeballing a flat screenshot. Invoke BEFORE declaring any UI, site, or styling/layout change correct. Screenshots have no depth buffer, so z-index/occlusion/clip bugs are exactly where "just look at it" fails; the `evaluate_script` routines below turn those fuzzy visual judgments into deterministic measurements — including optical center-of-mass, which measures the glyph ink's true visual center so differently-sized labels can be aligned by more than eye.
type-declarations
Add, audit, or update @nubjs/types declarations for Nub runtime APIs. Use whenever Nub adds or changes a user-visible global, built-in method, module loader type, or TC39 proposal; when TypeScript or @types/node gains an overlapping declaration; and before every release to reconcile runtime changes since the previous tag. Covers conflict-safe global augmentation, compiler-version routing, fixture matrices, and package verification.