ckb-cycle-tools 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/elf.js CHANGED
@@ -207,3 +207,55 @@ function demangleV0(name) {
207
207
  const rest = name.slice(i);
208
208
  return rest === "" || rest.startsWith("C") || rest.startsWith(".") ? p : undefined;
209
209
  }
210
+ /**
211
+ * The code a CKB-VM runs from an ELF: the entry point and each executable
212
+ * `PT_LOAD` segment (its address and the bytes the file gives it), in program
213
+ * header order. A build and its stripped copy have the same code; the
214
+ * stripped one only loses sections no segment loads (symbols, debug info).
215
+ * Undefined for anything that is not a 64-bit little-endian ELF with code.
216
+ */
217
+ export function elfCode(elf) {
218
+ if (elf.length < 64 || elf[0] !== 0x7f || elf[1] !== 0x45 || elf[2] !== 0x4c || elf[3] !== 0x46)
219
+ return undefined;
220
+ if (elf[4] !== 2 || elf[5] !== 1)
221
+ return undefined;
222
+ const view = new DataView(elf.buffer, elf.byteOffset, elf.byteLength);
223
+ const phoff = Number(view.getBigUint64(0x20, true));
224
+ const phentsize = view.getUint16(0x36, true);
225
+ const phnum = view.getUint16(0x38, true);
226
+ if (phentsize < 56 || phoff + phentsize * phnum > elf.length)
227
+ return undefined;
228
+ const parts = [elf.subarray(0x18, 0x20)];
229
+ for (let i = 0; i < phnum; i++) {
230
+ const o = phoff + i * phentsize;
231
+ const PT_LOAD = 1;
232
+ const PF_X = 1;
233
+ if (view.getUint32(o, true) !== PT_LOAD || !(view.getUint32(o + 4, true) & PF_X))
234
+ continue;
235
+ const offset = Number(view.getBigUint64(o + 8, true));
236
+ const size = Number(view.getBigUint64(o + 0x20, true));
237
+ if (offset + size > elf.length)
238
+ return undefined;
239
+ parts.push(elf.subarray(o + 0x10, o + 0x18), elf.subarray(offset, offset + size));
240
+ }
241
+ if (parts.length === 1)
242
+ return undefined;
243
+ const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
244
+ let at = 0;
245
+ for (const p of parts) {
246
+ out.set(p, at);
247
+ at += p.length;
248
+ }
249
+ return out;
250
+ }
251
+ /**
252
+ * Whether two ELFs run the same code (elfCode): an unstripped build and the
253
+ * binary it stands for. Undefined when either is not an ELF this can read.
254
+ */
255
+ export function sameCode(a, b) {
256
+ const x = elfCode(a);
257
+ const y = elfCode(b);
258
+ if (!x || !y)
259
+ return undefined;
260
+ return x.length === y.length && x.every((v, i) => v === y[i]);
261
+ }
package/dist/flame.d.ts CHANGED
@@ -11,9 +11,19 @@
11
11
  */
12
12
  /** Stack (frames joined by `;`, outermost first) → cycles. */
13
13
  export type Folded = Map<string, bigint>;
14
+ /**
15
+ * A frame name with each U+037E (GREEK QUESTION MARK, which looks like `;`)
16
+ * turned back into `;`. Newer ckb-debugger and ckb-vm-pprof write a `;` inside
17
+ * a name that way, so it cannot be read as a frame separator
18
+ * (nervosnetwork/ckb-standalone-debugger#211, #212); older ones write `;`.
19
+ * Reading both as `;` keeps a function's name, and so its costs and diffs, the
20
+ * same whichever debugger profiled it.
21
+ */
22
+ export declare const asciiFrame: (name: string) => string;
14
23
  /**
15
24
  * `E:\…\src\main.rs:session_lock::lock_hash` → `session_lock::lock_hash`. The
16
- * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its address.
25
+ * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its
26
+ * address. A U+037E in the name is read as `;` (asciiFrame).
17
27
  */
18
28
  export declare function frameName(frame: string): string;
19
29
  /**
@@ -62,10 +72,18 @@ export declare function renderFlameSvg(tree: FlameNode, opts?: {
62
72
  minWidth?: number;
63
73
  }): string;
64
74
  /**
65
- * The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the
66
- * profile covers. The last one: when the script spawns other scripts, the
75
+ * The `All cycles: N` line ckb-debugger prints in flamegraph mode for the
76
+ * profiled run. The last one: when the script spawns other scripts, the
67
77
  * debugger first runs the whole group (printing its full total) to record
68
78
  * the syscalls, then profiles the root script alone ("Actual run").
79
+ *
80
+ * Up to ckb-debugger 1.1.1 this equals what the profile's frames cover. From
81
+ * 1.1.2 (nervosnetwork/ckb-standalone-debugger#209) it also counts loading the
82
+ * program, which no frame holds: on the spawn fixture 18,801 against 14,974 in
83
+ * the frames. It is not the group's total in either release (no spawned
84
+ * scripts, and 1.1.2 is still 14 cycles under the plain run on the testtool
85
+ * fixture). For what the frames cover, sum the folded stacks
86
+ * (`foldedTotal`), as `flame` and `report` do; it is the same in both releases.
69
87
  */
70
88
  export declare function profiledCycles(output: string): bigint | undefined;
71
89
  /**
@@ -77,3 +95,43 @@ export declare function profiledCycles(output: string): bigint | undefined;
77
95
  * script could print such a line itself; this count only adds a note.)
78
96
  */
79
97
  export declare function spawnedScripts(output: string): number;
98
+ /** One VM of a `Spawn tree:` that ckb-debugger prints in full mode (see spawnTree). */
99
+ export interface SpawnedVm {
100
+ /** The VM id, as `--vm-id` takes it. 0 is the group's own script. */
101
+ vm: number;
102
+ /** 0 for the program the VM was spawned with; more after each `exec` (`1/1`). `--vm-id` replays only generation 0. */
103
+ generation: number;
104
+ /** The VM that spawned it (the root's own parent is itself, 0). */
105
+ parent: number;
106
+ /** Where its binary came from, as printed: `cell_dep[1][0..11552]`. */
107
+ locator: string;
108
+ /** The same, parsed: the source, its index, and the byte range of the binary in that cell's data. */
109
+ source?: "input" | "output" | "cell_dep" | "header_dep" | "group_input" | "group_output";
110
+ index?: number;
111
+ start?: number;
112
+ end?: number;
113
+ }
114
+ /**
115
+ * Every VM in the `Spawn tree:` lines ckb-debugger (full mode) prints for a
116
+ * group whose script spawns others, root first, each with its parent and the
117
+ * locator of the binary it ran:
118
+ *
119
+ * Spawn tree: 0 cell_dep[0][0..15992]
120
+ * Spawn tree: └── 1 cell_dep[1][0..11552]
121
+ * Spawn tree: └── 2 cell_dep[2][0..9000]
122
+ *
123
+ * Each level of the tree is four characters of prefix. Empty when the script
124
+ * spawned nothing (no tree is printed). A script could print such lines itself
125
+ * (as a `Script log:` line, which does not start with `Spawn tree:`); only the
126
+ * debugger's own lines are read.
127
+ */
128
+ export declare function spawnTree(output: string): SpawnedVm[];
129
+ /** The first ckb-debugger release whose `--vm-id` replay of a spawned script is faithful, with `--vm-symbols` (1.1.2). */
130
+ export declare const CHILD_PROFILE_DEBUGGER = "1.1.2";
131
+ /**
132
+ * Whether a ckb-debugger (its `--version` line) can profile a spawned script on
133
+ * its own: 1.1.2 or later. Before it, the replay of `inherited_fds` was wrong
134
+ * (the child of the spawn fixture exits 3) and full mode read only the root's
135
+ * symbols. An unknown version cannot.
136
+ */
137
+ export declare function profilesChildren(version: string): boolean;
package/dist/flame.js CHANGED
@@ -9,12 +9,22 @@
9
9
  * A deployed binary is usually stripped: its whole run is one frame. Pass an
10
10
  * unstripped build of the same code (`ckb-debugger --bin`) to see functions.
11
11
  */
12
+ /**
13
+ * A frame name with each U+037E (GREEK QUESTION MARK, which looks like `;`)
14
+ * turned back into `;`. Newer ckb-debugger and ckb-vm-pprof write a `;` inside
15
+ * a name that way, so it cannot be read as a frame separator
16
+ * (nervosnetwork/ckb-standalone-debugger#211, #212); older ones write `;`.
17
+ * Reading both as `;` keeps a function's name, and so its costs and diffs, the
18
+ * same whichever debugger profiled it.
19
+ */
20
+ export const asciiFrame = (name) => name.replace(/\u037e/g, ";");
12
21
  /**
13
22
  * `E:\…\src\main.rs:session_lock::lock_hash` → `session_lock::lock_hash`. The
14
- * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its address.
23
+ * path ends at the first `.<ext>:`; `??:func_0x114e4` (no symbols) keeps its
24
+ * address. A U+037E in the name is read as `;` (asciiFrame).
15
25
  */
16
26
  export function frameName(frame) {
17
- const f = frame.trim();
27
+ const f = asciiFrame(frame.trim());
18
28
  if (f.startsWith("??:"))
19
29
  return f.slice(3);
20
30
  const m = /^.*?\.[A-Za-z0-9]+:(.+)$/.exec(f);
@@ -193,10 +203,18 @@ function colour(name) {
193
203
  return `hsl(${hue} 75% ${light}%)`;
194
204
  }
195
205
  /**
196
- * The `All cycles: N` line ckb-debugger prints in flamegraph mode: what the
197
- * profile covers. The last one: when the script spawns other scripts, the
206
+ * The `All cycles: N` line ckb-debugger prints in flamegraph mode for the
207
+ * profiled run. The last one: when the script spawns other scripts, the
198
208
  * debugger first runs the whole group (printing its full total) to record
199
209
  * the syscalls, then profiles the root script alone ("Actual run").
210
+ *
211
+ * Up to ckb-debugger 1.1.1 this equals what the profile's frames cover. From
212
+ * 1.1.2 (nervosnetwork/ckb-standalone-debugger#209) it also counts loading the
213
+ * program, which no frame holds: on the spawn fixture 18,801 against 14,974 in
214
+ * the frames. It is not the group's total in either release (no spawned
215
+ * scripts, and 1.1.2 is still 14 cycles under the plain run on the testtool
216
+ * fixture). For what the frames cover, sum the folded stacks
217
+ * (`foldedTotal`), as `flame` and `report` do; it is the same in both releases.
200
218
  */
201
219
  export function profiledCycles(output) {
202
220
  const all = [...output.matchAll(/^All cycles:\s*(\d+)/gm)];
@@ -217,3 +235,62 @@ export function spawnedScripts(output) {
217
235
  ids.delete("0");
218
236
  return ids.size;
219
237
  }
238
+ /**
239
+ * Every VM in the `Spawn tree:` lines ckb-debugger (full mode) prints for a
240
+ * group whose script spawns others, root first, each with its parent and the
241
+ * locator of the binary it ran:
242
+ *
243
+ * Spawn tree: 0 cell_dep[0][0..15992]
244
+ * Spawn tree: └── 1 cell_dep[1][0..11552]
245
+ * Spawn tree: └── 2 cell_dep[2][0..9000]
246
+ *
247
+ * Each level of the tree is four characters of prefix. Empty when the script
248
+ * spawned nothing (no tree is printed). A script could print such lines itself
249
+ * (as a `Script log:` line, which does not start with `Spawn tree:`); only the
250
+ * debugger's own lines are read.
251
+ */
252
+ export function spawnTree(output) {
253
+ const vms = [];
254
+ const seen = new Set();
255
+ /** The VM at each depth, as the tree is walked top to bottom. */
256
+ const path = [];
257
+ for (const m of output.matchAll(/^Spawn tree: ([ │├└─]*)(\d+)(?:\/(\d+))?[ \t]+(\S+)[ \t]*$/gmu)) {
258
+ const depth = [...m[1]].length / 4;
259
+ if (!Number.isInteger(depth) || depth > path.length)
260
+ continue;
261
+ const vm = Number(m[2]);
262
+ const generation = Number(m[3] ?? 0);
263
+ const key = `${vm}/${generation}`;
264
+ if (seen.has(key))
265
+ continue;
266
+ seen.add(key);
267
+ path.length = depth;
268
+ const parent = depth ? path[depth - 1] : vm;
269
+ path.push(vm);
270
+ const loc = /^(input|output|cell_dep|header_dep|group_input|group_output)\[(\d+)\]\[(\d+)\.\.(\d+)\]$/.exec(m[4]);
271
+ vms.push({
272
+ vm,
273
+ generation,
274
+ parent,
275
+ locator: m[4],
276
+ ...(loc && { source: loc[1], index: Number(loc[2]), start: Number(loc[3]), end: Number(loc[4]) }),
277
+ });
278
+ }
279
+ return vms;
280
+ }
281
+ /** The first ckb-debugger release whose `--vm-id` replay of a spawned script is faithful, with `--vm-symbols` (1.1.2). */
282
+ export const CHILD_PROFILE_DEBUGGER = "1.1.2";
283
+ /**
284
+ * Whether a ckb-debugger (its `--version` line) can profile a spawned script on
285
+ * its own: 1.1.2 or later. Before it, the replay of `inherited_fds` was wrong
286
+ * (the child of the spawn fixture exits 3) and full mode read only the root's
287
+ * symbols. An unknown version cannot.
288
+ */
289
+ export function profilesChildren(version) {
290
+ const m = /(\d+)\.(\d+)\.(\d+)/.exec(version);
291
+ if (!m)
292
+ return false;
293
+ const [a, b, c] = m.slice(1).map(Number);
294
+ const [x, y, z] = CHILD_PROFILE_DEBUGGER.split(".").map(Number);
295
+ return a !== x ? a > x : b !== y ? b > y : c >= z;
296
+ }
package/dist/index.d.ts CHANGED
@@ -8,16 +8,20 @@ export { checkMockTransaction, checkTypeId, debuggerArgs, DEFAULT_TX_CYCLE_LIMIT
8
8
  export type { DebuggerOutput, GroupRun, Profile, ProfiledGroup, ReplayOptions, ReplayPlan, RunDebugger } from "./replay.js";
9
9
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
10
10
  export type { FlameGroup, ProfileOptions } from "./profile.js";
11
- export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, spawnedScripts, renderFlameSvg, splitStack, } from "./flame.js";
12
- export type { FlameNode, Folded, FunctionCost } from "./flame.js";
13
- export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
11
+ export { MAX_CHILD_PROFILES, olderDebuggerNote, profileChildren, profileSpawns, SERVER_EXIT_NOTE, serverExit } from "./children.js";
12
+ export type { ChildContext, FlameChild, SpawnSplit } from "./children.js";
13
+ export { resolvedCellDeps, spawnedBinary } from "./spawn.js";
14
+ export type { SpawnedBinary } from "./spawn.js";
15
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, profilesChildren, spawnedScripts, spawnTree, CHILD_PROFILE_DEBUGGER, renderFlameSvg, splitStack, } from "./flame.js";
16
+ export type { FlameNode, Folded, FunctionCost, SpawnedVm } from "./flame.js";
17
+ export { runWasmDebugger, wasmDebuggerVersion, wasmFiles, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
14
18
  export type { WasmRun } from "./wasm.js";
15
19
  export { substituteBinaries } from "./substitute.js";
16
20
  export type { AppliedSubstitution, BinarySubstitution } from "./substitute.js";
17
- export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
18
- export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, ManifestSummary, MarkdownOptions, ReportManifest, ScenarioManifest, ScenarioResult, } from "./diff.js";
21
+ export { childDeltas, CHILDREN_FOOTNOTE, COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
22
+ export type { ChildDelta, ChildResult, CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, ManifestSummary, MarkdownOptions, ReportManifest, ScenarioManifest, ScenarioResult, } from "./diff.js";
19
23
  export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
20
- export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
24
+ export { childResult, formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
21
25
  export type { BinaryConfig, CyclesConfig, ReportOptions, ScenarioConfig } from "./report.js";
22
26
  export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
23
27
  export type { ScanOptions, ScanResult, ScannedBinary, ScannedMock } from "./scan.js";
package/dist/index.js CHANGED
@@ -3,10 +3,12 @@ export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFound
3
3
  export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
4
4
  export { checkMockTransaction, checkTypeId, debuggerArgs, DEFAULT_TX_CYCLE_LIMIT, groupsOf, nodeOrder, nodeStop, nodeVerdict, overTxLimitLines, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, sumLines, } from "./replay.js";
5
5
  export { flameTransaction, profileTransaction, runNativeDebugger } from "./profile.js";
6
- export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, spawnedScripts, renderFlameSvg, splitStack, } from "./flame.js";
7
- export { runWasmDebugger, wasmDebuggerVersion, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
6
+ export { MAX_CHILD_PROFILES, olderDebuggerNote, profileChildren, profileSpawns, SERVER_EXIT_NOTE, serverExit } from "./children.js";
7
+ export { resolvedCellDeps, spawnedBinary } from "./spawn.js";
8
+ export { flameTree, foldedTotal, formatFolded, frameName, functionCosts, parseFolded, profiledCycles, profilesChildren, spawnedScripts, spawnTree, CHILD_PROFILE_DEBUGGER, renderFlameSvg, splitStack, } from "./flame.js";
9
+ export { runWasmDebugger, wasmDebuggerVersion, wasmFiles, wasmOutput, wasmRunner, WASM_TX_FILE } from "./wasm.js";
8
10
  export { substituteBinaries } from "./substitute.js";
9
- export { COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
11
+ export { childDeltas, CHILDREN_FOOTNOTE, COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
10
12
  export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
11
- export { formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
13
+ export { childResult, formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
12
14
  export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
package/dist/profile.d.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  import type { MockTransaction, RpcTransaction } from "./mock.js";
2
+ import { type FlameChild } from "./children.js";
2
3
  import { type Folded } from "./flame.js";
3
4
  import { type DebuggerOutput, type Profile, type ReplayOptions, type ReplayPlan } from "./replay.js";
4
5
  export { checkTypeId, parseDebuggerOutput, parseDebuggerRun, parseNames, readTransactionJson, selectorFor, TYPE_ID_CODE_HASH, TYPE_ID_CYCLES, } from "./replay.js";
5
6
  export type { DebuggerOutput, GroupRun, Profile, ProfiledGroup } from "./replay.js";
7
+ export { MAX_CHILD_PROFILES } from "./children.js";
8
+ export type { FlameChild } from "./children.js";
6
9
  /** The most a run may print. More is a script flooding its logs: the run is an error, not a result. */
7
10
  export declare const MAX_DEBUGGER_OUTPUT: number;
8
11
  export interface ProfileOptions extends ReplayOptions {
@@ -55,6 +58,15 @@ export interface FlameGroup {
55
58
  * but in no frame of `folded`, and `--bin` replaces only the root's binary.
56
59
  */
57
60
  spawned?: number;
61
+ /**
62
+ * With `spawned`: each spawned script's own profile, from one `--vm-id`
63
+ * replay per spawned VM (ckb-debugger 1.1.2 and later). The group's
64
+ * `cycles` stay the source of truth; these are profiled frames, and they
65
+ * leave out what the spawn itself costs the parent.
66
+ */
67
+ children?: FlameChild[];
68
+ /** With `spawned`: why some or all spawned scripts have no profile of their own (an older debugger, an `exec`, too many). */
69
+ childrenNote?: string;
58
70
  }
59
71
  /**
60
72
  * Profiles each script group with ckb-debugger's flamegraph mode. `bins` maps a
@@ -71,6 +83,15 @@ export declare function flameTransaction(target: string | RpcTransaction | MockT
71
83
  scripts?: string[];
72
84
  readFile: (path: string) => Promise<string>;
73
85
  readBinary?: (path: string) => Promise<Uint8Array>;
86
+ /**
87
+ * Unstripped builds of spawned scripts, by data hash (or the type hash of
88
+ * the cell they are in), to name a child's frames (`--vm-symbols`). `bins`
89
+ * is looked up too. Each must have the same code as the binary the child
90
+ * ran (elf.ts `sameCode`), or it is not used.
91
+ */
92
+ vmSymbols?: Record<string, string>;
93
+ /** Profile each spawned script on its own (default true; needs ckb-debugger 1.1.2). */
94
+ children?: boolean;
74
95
  }): Promise<{
75
96
  plan: ReplayPlan;
76
97
  groups: FlameGroup[];
package/dist/profile.js CHANGED
@@ -4,11 +4,14 @@ import { tmpdir } from "node:os";
4
4
  import { join } from "node:path";
5
5
  import { promisify } from "node:util";
6
6
  import { checkDebuggerPath, resolveDebugger } from "./debugger.js";
7
+ import { profileChildren } from "./children.js";
7
8
  import { elfFunctionNames } from "./elf.js";
8
9
  import { nameAddresses, parseFolded, spawnedScripts } from "./flame.js";
9
10
  import { debuggerArgs, parseDebuggerRun, planReplay, replayGroups, selectorFor, TYPE_ID_CODE_HASH, } from "./replay.js";
10
11
  // The pure parts live in replay.ts, shared with the browser; existing imports keep working.
11
12
  export { checkTypeId, parseDebuggerOutput, parseDebuggerRun, parseNames, readTransactionJson, selectorFor, TYPE_ID_CODE_HASH, TYPE_ID_CYCLES, } from "./replay.js";
13
+ // Child profiles live in children.ts, shared with the browser.
14
+ export { MAX_CHILD_PROFILES } from "./children.js";
12
15
  const run = promisify(execFile);
13
16
  /** The most a run may print. More is a script flooding its logs: the run is an error, not a result. */
14
17
  export const MAX_DEBUGGER_OUTPUT = 64 << 20;
@@ -82,6 +85,8 @@ export async function flameTransaction(target, options) {
82
85
  const { exec, version: debuggerVersion } = await debuggerOf(options);
83
86
  const plan = await planReplay(target, options);
84
87
  const bins = Object.fromEntries(Object.entries(options.bins ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
88
+ const vmSymbols = Object.fromEntries(Object.entries(options.vmSymbols ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
89
+ const scriptNames = Object.fromEntries(Object.entries(options.scriptNames ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
85
90
  const dir = await mkdtemp(join(tmpdir(), "ckb-flame-"));
86
91
  try {
87
92
  const txFile = join(dir, "tx.json");
@@ -115,10 +120,30 @@ export async function flameTransaction(target, options) {
115
120
  const spawned = spawnedScripts(runOut.stdout);
116
121
  const names = bin ? await namesOf(bin) : new Map();
117
122
  const folded = nameAddresses(parseFolded(await options.readFile(out).catch(() => "")), names);
118
- // Flamegraph mode leaves out loading the binary, so result and cycles come
119
- // from plain runs: with the build, and with the deployed binary to compare.
123
+ // A flamegraph run's own total is not the group's: up to ckb-debugger 1.1.1 it
124
+ // leaves out loading the binary, 1.1.2 counts loading but is still a few
125
+ // cycles short (14 on the testtool fixture), and every release leaves out
126
+ // spawned scripts. So result and cycles come from plain runs: with the
127
+ // build, and with the deployed binary to compare.
120
128
  const parsed = runOut.exitCode === null ? parseDebuggerRun(runOut) : parseDebuggerRun(await exec([...base, ...(bin ? ["--bin", bin] : [])]));
121
129
  const deployed = bin ? parseDebuggerRun(await exec(base)) : undefined;
130
+ let children;
131
+ let childrenNote;
132
+ if (spawned && options.children !== false) {
133
+ ({ children, childrenNote } = await profileChildren(runOut.stdout, {
134
+ version: debuggerVersion,
135
+ base: [...base, ...(bin ? ["--bin", bin] : [])],
136
+ out: (vm) => join(dir, `${selector}.vm${vm}.folded`),
137
+ exec,
138
+ mock: plan.mock,
139
+ group: g,
140
+ symbolsOf: (hash) => vmSymbols[hash] ?? bins[hash],
141
+ names: scriptNames,
142
+ readFile: options.readFile,
143
+ readBinary,
144
+ namesOf,
145
+ }));
146
+ }
122
147
  groups.push({
123
148
  selector,
124
149
  ...(g.name && { name: g.name }),
@@ -129,6 +154,8 @@ export async function flameTransaction(target, options) {
129
154
  cycles: parsed.cycles,
130
155
  folded,
131
156
  ...(spawned && { spawned }),
157
+ ...(children?.length && { children }),
158
+ ...(childrenNote && { childrenNote }),
132
159
  ...(bin &&
133
160
  deployed && {
134
161
  bin,
package/dist/report.d.ts CHANGED
@@ -1,6 +1,8 @@
1
- import type { CycleReport, GroupResult, ReportManifest, ScenarioResult } from "./diff.js";
1
+ import { SERVER_EXIT_NOTE } from "./children.js";
2
+ import type { ChildResult, CycleReport, GroupResult, ReportManifest, ScenarioResult } from "./diff.js";
2
3
  import { type RpcOutPoint } from "./mock.js";
3
- import { type Profile, type ProfileOptions } from "./profile.js";
4
+ import { type FlameChild, type Profile, type ProfileOptions } from "./profile.js";
5
+ export { SERVER_EXIT_NOTE };
4
6
  export interface BinaryConfig {
5
7
  /** The built binary, relative to the config file. */
6
8
  path: string;
@@ -87,6 +89,8 @@ export declare function runReport(configPath: string, options?: ReportOptions):
87
89
  notices?: string[];
88
90
  manifest: ReportManifest;
89
91
  }>;
92
+ /** A spawned script's profile as a report records it: profiled frames, never a share of the group's total. */
93
+ export declare function childResult(c: FlameChild): ChildResult;
90
94
  /**
91
95
  * `file` with its symlinks resolved, when it is inside one of `roots` (already
92
96
  * resolved); an error otherwise. A file that does not exist is checked by its
package/dist/report.js CHANGED
@@ -16,6 +16,7 @@
16
16
  */
17
17
  import { readFile, realpath, stat } from "node:fs/promises";
18
18
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
19
+ import { SERVER_EXIT_NOTE } from "./children.js";
19
20
  import { checkDebuggerPath, resolveDebugger } from "./debugger.js";
20
21
  import { FUNCTION_LIMIT, overTxLimitOf, resultLabel, spawnNote, termLine, termLines, unmatchedError } from "./diff.js";
21
22
  import { foldedTotal, functionCosts } from "./flame.js";
@@ -24,6 +25,7 @@ import { fileDigest, gitCommit, inputsHash, scenarioInputs, sha256, toolchainOf,
24
25
  import { flameTransaction, parseNames, profileTransaction, readTransactionJson } from "./profile.js";
25
26
  import { consensusOf, nodeVerdict, overTxLimitLines, PUBLIC_RPC } from "./replay.js";
26
27
  import { substituteBinaries, targetScriptKeys } from "./substitute.js";
28
+ export { SERVER_EXIT_NOTE };
27
29
  const HASH = /^0x[0-9a-fA-F]{64}$/;
28
30
  /** Parses and checks a cycles.json, with a message that says what to fix. */
29
31
  export function parseCyclesConfig(json) {
@@ -276,12 +278,16 @@ export async function runReport(configPath, options = {}) {
276
278
  });
277
279
  // The scripts whose code is a binary with symbols, when the scenario asks for functions.
278
280
  const symbols = new Map();
281
+ // The same builds by data hash: a spawned script is found by the binary it ran, not by a group.
282
+ const vmSymbols = new Map();
279
283
  if (s.functions ?? config.functions) {
280
284
  for (const a of applied) {
281
285
  const sym = config.binaries[a.name].symbols;
282
286
  if (sym)
283
287
  for (const k of a.scriptKeys)
284
288
  symbols.set(k.toLowerCase(), sym);
289
+ if (sym)
290
+ vmSymbols.set(a.newDataHash.toLowerCase(), sym);
285
291
  }
286
292
  }
287
293
  if (symbols.size) {
@@ -289,7 +295,8 @@ export async function runReport(configPath, options = {}) {
289
295
  await recordFunctions(groups, swapped, symbols, binDir, inside, {
290
296
  ...profileOptions,
291
297
  ...(scriptVersion !== undefined && { scriptVersion }),
292
- });
298
+ scriptNames,
299
+ }, vmSymbols);
293
300
  }
294
301
  }
295
302
  debuggerVersion ??= profile.env.debugger;
@@ -372,7 +379,7 @@ export async function runReport(configPath, options = {}) {
372
379
  * of that group with that build. A build that does not cost the same cycles as
373
380
  * the binary it stands for is not the same code: the group gets a warning instead.
374
381
  */
375
- async function recordFunctions(groups, mock, symbols, binDir, inside, options) {
382
+ async function recordFunctions(groups, mock, symbols, binDir, inside, options, vmSymbolPaths = new Map()) {
376
383
  const fmt = (n) => n.toLocaleString("en-US");
377
384
  const symbolsOf = (g) => symbols.get(`${g.codeHash}:${g.hashType}`.toLowerCase());
378
385
  const wanted = groups.filter((g) => symbolsOf(g));
@@ -396,11 +403,19 @@ async function recordFunctions(groups, mock, symbols, binDir, inside, options) {
396
403
  const run = wanted.filter((g) => bins[g.codeHash]);
397
404
  if (!run.length)
398
405
  return;
406
+ // Builds for spawned scripts: one that cannot be read leaves that child's frames unnamed (said on the child).
407
+ const vmSymbols = {};
408
+ for (const [hash, sym] of vmSymbolPaths) {
409
+ const file = await inside(resolve(binDir, sym)).catch(() => undefined);
410
+ if (file && (await stat(file).then((st) => st.isFile(), () => false)))
411
+ vmSymbols[hash] = file;
412
+ }
399
413
  let flame;
400
414
  try {
401
415
  flame = await flameTransaction(mock, {
402
416
  ...options,
403
417
  bins,
418
+ vmSymbols,
404
419
  scripts: run.map((g) => g.selector),
405
420
  readFile: (path) => readFile(path, "utf8"),
406
421
  });
@@ -429,9 +444,34 @@ async function recordFunctions(groups, mock, symbols, binDir, inside, options) {
429
444
  g.functions = functionCosts(f.folded)
430
445
  .slice(0, FUNCTION_LIMIT)
431
446
  .map((c) => ({ name: c.name, self: Number(c.self), total: Number(c.total) }));
447
+ // Only beside a profile that checked out: the children were replayed with the same build.
448
+ if (f.children?.length)
449
+ g.children = f.children.map(childResult);
450
+ if (f.childrenNote)
451
+ g.childrenNote = f.childrenNote;
432
452
  }
433
453
  }
434
454
  }
455
+ /** A spawned script's profile as a report records it: profiled frames, never a share of the group's total. */
456
+ export function childResult(c) {
457
+ const script = c.name ?? (c.codeHash ? short(c.codeHash) : c.locator);
458
+ const base = { vm: c.vm, parent: c.parent, script, ...(c.codeHash && { codeHash: c.codeHash }) };
459
+ if (c.failed)
460
+ return { ...base, failed: c.failed };
461
+ const out = { ...base, result: c.result, ...(c.error && { error: c.error }), profiled: Number(foldedTotal(c.folded)) };
462
+ if (c.symbolsWarning)
463
+ out.functionsWarning = c.symbolsWarning;
464
+ else if (!c.symbols)
465
+ out.functionsWarning = "no symbols build for the binary it ran: its frames have no names";
466
+ else if (!c.folded.size)
467
+ out.functionsWarning = "the profiler recorded no stacks";
468
+ else {
469
+ out.functions = functionCosts(c.folded)
470
+ .slice(0, FUNCTION_LIMIT)
471
+ .map((f) => ({ name: f.name, self: Number(f.self), total: Number(f.total) }));
472
+ }
473
+ return out;
474
+ }
435
475
  /**
436
476
  * `file` with its symlinks resolved, when it is inside one of `roots` (already
437
477
  * resolved); an error otherwise. A file that does not exist is checked by its
@@ -472,6 +512,19 @@ async function realParent(p) {
472
512
  return join(await realParent(parent), basename(p));
473
513
  }
474
514
  }
515
+ /** One spawned script under its group in the terminal report. */
516
+ function childReportLine(c, groupOk = false) {
517
+ const fmt = (n) => n.toLocaleString("en-US");
518
+ const t = termLine;
519
+ const head = `spawned vm ${c.vm} (${t(c.script)})`;
520
+ if (c.failed || c.result === undefined)
521
+ return `${head}: not profiled: ${t(c.failed ?? "no result")}`;
522
+ const result = resultLabel({ result: c.result, ...(c.error && { error: c.error }) });
523
+ const top = (c.functions ?? []).slice(0, 3).map((f) => `${t(f.name)} ${fmt(f.self)}`);
524
+ return (`${head}: ${t(result)}, ${fmt(c.profiled ?? 0)} cycles in its profiled frames` +
525
+ (top.length ? `; costliest (self): ${top.join(", ")}` : c.functionsWarning ? `; functions not recorded: ${t(c.functionsWarning)}` : "") +
526
+ (groupOk && (c.error || c.result !== 0) ? ` (${SERVER_EXIT_NOTE})` : ""));
527
+ }
475
528
  /**
476
529
  * The report for a terminal: one block per scenario. Every name, warning and
477
530
  * error from the config, the build or the debugger goes through termLine (or
@@ -535,6 +588,10 @@ export function formatReport(report) {
535
588
  if (g.spawned)
536
589
  out.push(` ${spawnNote({ ...g, head: g })}`);
537
590
  }
591
+ for (const c of g.children ?? [])
592
+ out.push(` ${childReportLine(c, g.result === 0 && !g.error)}`);
593
+ if (g.childrenNote)
594
+ out.push(` spawned scripts: ${t(g.childrenNote)}`);
538
595
  }
539
596
  }
540
597
  if (report.debugger)
@@ -0,0 +1,29 @@
1
+ import type { SpawnedVm } from "./flame.js";
2
+ import { type MockTransaction, type RpcCellOutput } from "./mock.js";
3
+ export interface SpawnedBinary {
4
+ /** The bytes the VM loaded. */
5
+ data: Uint8Array;
6
+ /** Their blake2b hash: the code hash a `data`/`data1`/`data2` script would name it by. */
7
+ dataHash: string;
8
+ /** The type script hash of the cell it came from, when that cell has one and the binary is its whole data. */
9
+ typeHash?: string;
10
+ }
11
+ /**
12
+ * The cell deps as the node resolves them, the order `cell_dep[i]` counts in:
13
+ * each code dep is itself, each dep group is the cells it lists (the group
14
+ * cell is not one of them).
15
+ */
16
+ export declare function resolvedCellDeps(mock: MockTransaction): {
17
+ output: RpcCellOutput;
18
+ data: string;
19
+ }[];
20
+ /**
21
+ * The binary a spawned VM ran. `group` gives the group's input and output
22
+ * indices, for `group_input[i]` and `group_output[i]`. Undefined when the
23
+ * locator does not name a cell of this transaction (a witness, or a line this
24
+ * cannot parse).
25
+ */
26
+ export declare function spawnedBinary(mock: MockTransaction, vm: SpawnedVm, group: {
27
+ inputs: number[];
28
+ outputs: number[];
29
+ }): SpawnedBinary | undefined;