ckb-cycle-tools 1.2.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/CHANGELOG.md +416 -213
- package/README.md +859 -659
- package/dist/children.d.ts +100 -0
- package/dist/children.js +146 -0
- package/dist/cli.js +64 -9
- package/dist/diff.d.ts +223 -2
- package/dist/diff.js +358 -13
- package/dist/elf.d.ts +13 -0
- package/dist/elf.js +52 -0
- package/dist/flame.d.ts +61 -3
- package/dist/flame.js +81 -4
- package/dist/index.d.ts +12 -7
- package/dist/index.js +8 -5
- package/dist/manifest.d.ts +37 -0
- package/dist/manifest.js +107 -0
- package/dist/mock.d.ts +5 -0
- package/dist/mock.js +2 -1
- package/dist/profile.d.ts +21 -0
- package/dist/profile.js +29 -2
- package/dist/replay.d.ts +98 -1
- package/dist/replay.js +107 -1
- package/dist/report.d.ts +18 -2
- package/dist/report.js +175 -13
- package/dist/spawn.d.ts +29 -0
- package/dist/spawn.js +77 -0
- package/dist/wasm.d.ts +22 -1
- package/dist/wasm.js +31 -1
- package/package.json +4 -2
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
|
|
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
|
|
66
|
-
*
|
|
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
|
|
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
|
|
197
|
-
*
|
|
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
|
@@ -4,19 +4,24 @@ export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFound
|
|
|
4
4
|
export type { ScriptGroup, TxAnalysis } from "./analyze.js";
|
|
5
5
|
export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
|
|
6
6
|
export type { HttpRpcOptions, MockTransaction, NodeConsensus, Rpc, RpcOutPoint, RpcTransaction, VmEpochs } from "./mock.js";
|
|
7
|
-
export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
|
|
7
|
+
export { checkMockTransaction, checkTypeId, debuggerArgs, DEFAULT_TX_CYCLE_LIMIT, groupsOf, nodeOrder, nodeStop, nodeVerdict, overTxLimitLines, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, sumLines, } from "./replay.js";
|
|
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 {
|
|
12
|
-
export type {
|
|
13
|
-
export {
|
|
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, resultLabel, summarize, } from "./diff.js";
|
|
18
|
-
export type { CycleDiff, CycleReport, DiffOptions, DiffRow, FunctionDelta, FunctionResult, GroupResult, MarkdownOptions, ScenarioResult } from "./diff.js";
|
|
19
|
-
export {
|
|
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";
|
|
23
|
+
export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
|
|
24
|
+
export { childResult, formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
|
|
20
25
|
export type { BinaryConfig, CyclesConfig, ReportOptions, ScenarioConfig } from "./report.js";
|
|
21
26
|
export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
|
|
22
27
|
export type { ScanOptions, ScanResult, ScannedBinary, ScannedMock } from "./scan.js";
|
package/dist/index.js
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
export { checkDebuggerPath, DebuggerNotFoundError, resolveDebugger } from "./debugger.js";
|
|
2
2
|
export { analyzeTransaction, groupScripts, knownScriptNames, TransactionNotFoundError } from "./analyze.js";
|
|
3
3
|
export { buildMockTransaction, httpRpc, isCellbase, mockFromTransaction, nodeConsensus, parseOutPointVec, scriptVersionAt, } from "./mock.js";
|
|
4
|
-
export { checkMockTransaction, checkTypeId, debuggerArgs, groupsOf, nodeVerdict, parseDebuggerOutput, parseDebuggerRun, planReplay, readTransactionJson, replayGroups, selectorFor, } from "./replay.js";
|
|
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 {
|
|
7
|
-
export {
|
|
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, resultLabel, summarize, } from "./diff.js";
|
|
10
|
-
export {
|
|
11
|
+
export { childDeltas, CHILDREN_FOOTNOTE, COMMENT_MARKER, diffFailed, diffReports, formatMarkdown, formatText, FUNCTION_LIMIT, functionDeltas, FUNCTIONS_SHOWN, INPUTS_CHANGED, manifestLines, resultLabel, summarize, } from "./diff.js";
|
|
12
|
+
export { canonicalJson, fileDigest, gitCommit, inputsHash, scenarioInputs, toolchainOf } from "./manifest.js";
|
|
13
|
+
export { childResult, formatReport, groupResults, parseCyclesConfig, runReport } from "./report.js";
|
|
11
14
|
export { configFromMocks, formatScan, scanTestMocks } from "./scan.js";
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { ScenarioConfig } from "./report.js";
|
|
2
|
+
export declare const sha256: (data: Uint8Array | string) => string;
|
|
3
|
+
/** The sha256 and size of a file, read as a stream (a debugger binary is tens of MB). */
|
|
4
|
+
export declare function fileDigest(path: string): Promise<{
|
|
5
|
+
sha256: string;
|
|
6
|
+
size: number;
|
|
7
|
+
}>;
|
|
8
|
+
/** This package's name and version, from its package.json ("unknown" if it cannot be read). */
|
|
9
|
+
export declare function toolIdentity(): Promise<{
|
|
10
|
+
name: string;
|
|
11
|
+
version: string;
|
|
12
|
+
}>;
|
|
13
|
+
/**
|
|
14
|
+
* The commit checked out at `dir`, or undefined: not a git checkout, no git, or
|
|
15
|
+
* anything else. Never fails the report. Only a commit id is kept, whatever git printed.
|
|
16
|
+
*/
|
|
17
|
+
export declare function gitCommit(dir: string): Promise<string | undefined>;
|
|
18
|
+
/** JSON with object keys sorted at every level: the same value always gives the same text. */
|
|
19
|
+
export declare function canonicalJson(value: unknown): string;
|
|
20
|
+
/**
|
|
21
|
+
* The part of a scenario's cycles.json entry that decides what runs: its form
|
|
22
|
+
* (and transaction hash), the binaries it names, its CKB-VM version, and for a
|
|
23
|
+
* transaction fetched from a node, the network. Not its name (the key it is
|
|
24
|
+
* matched by), the path of its file (whose bytes are hashed instead: a moved
|
|
25
|
+
* file with the same bytes is the same input), nor `functions` (which records
|
|
26
|
+
* names, not cycles).
|
|
27
|
+
*/
|
|
28
|
+
export declare function scenarioInputs(s: ScenarioConfig, network: string | undefined): Record<string, unknown>;
|
|
29
|
+
/**
|
|
30
|
+
* sha256 over a scenario's inputs: the canonical entry (scenarioInputs), then
|
|
31
|
+
* the bytes of its mock or transaction file exactly as read, if it has one.
|
|
32
|
+
*/
|
|
33
|
+
export declare function inputsHash(entry: Record<string, unknown>, file?: Uint8Array): string;
|
|
34
|
+
/** The longest toolchain description a report keeps. */
|
|
35
|
+
export declare const TOOLCHAIN_MAX = 4096;
|
|
36
|
+
/** A toolchain description as a report keeps it: trimmed, clipped; undefined when empty. */
|
|
37
|
+
export declare function toolchainOf(s: string | undefined): string | undefined;
|
package/dist/manifest.js
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a report's numbers were measured with, so two reports can be checked for
|
|
3
|
+
* comparability (review #46, point 4): the tool, the debugger binary, the
|
|
4
|
+
* commit, the toolchain, and per scenario the CKB-VM version, a hash of its
|
|
5
|
+
* inputs and the binaries swapped into it. Node only (hashes files, runs git);
|
|
6
|
+
* the shape is in diff.ts, which compares it.
|
|
7
|
+
*/
|
|
8
|
+
import { execFile } from "node:child_process";
|
|
9
|
+
import { createHash } from "node:crypto";
|
|
10
|
+
import { createReadStream } from "node:fs";
|
|
11
|
+
import { readFile } from "node:fs/promises";
|
|
12
|
+
export const sha256 = (data) => createHash("sha256").update(data).digest("hex");
|
|
13
|
+
/** The sha256 and size of a file, read as a stream (a debugger binary is tens of MB). */
|
|
14
|
+
export function fileDigest(path) {
|
|
15
|
+
return new Promise((resolve, reject) => {
|
|
16
|
+
const hash = createHash("sha256");
|
|
17
|
+
let size = 0;
|
|
18
|
+
createReadStream(path)
|
|
19
|
+
.on("data", (chunk) => {
|
|
20
|
+
const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
|
|
21
|
+
size += bytes.length;
|
|
22
|
+
hash.update(bytes);
|
|
23
|
+
})
|
|
24
|
+
.on("error", reject)
|
|
25
|
+
.on("end", () => resolve({ sha256: hash.digest("hex"), size }));
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
/** This package's name and version, from its package.json ("unknown" if it cannot be read). */
|
|
29
|
+
export async function toolIdentity() {
|
|
30
|
+
try {
|
|
31
|
+
const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
|
|
32
|
+
return { name: String(pkg.name ?? "ckb-cycle-tools"), version: String(pkg.version ?? "unknown") };
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
return { name: "ckb-cycle-tools", version: "unknown" };
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
|
|
39
|
+
/**
|
|
40
|
+
* The commit checked out at `dir`, or undefined: not a git checkout, no git, or
|
|
41
|
+
* anything else. Never fails the report. Only a commit id is kept, whatever git printed.
|
|
42
|
+
*/
|
|
43
|
+
export function gitCommit(dir) {
|
|
44
|
+
return new Promise((resolve) => {
|
|
45
|
+
try {
|
|
46
|
+
execFile("git", ["rev-parse", "--verify", "--quiet", "HEAD"], { cwd: dir, timeout: 10_000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" } }, (err, stdout) => {
|
|
47
|
+
const out = String(stdout ?? "").trim().toLowerCase();
|
|
48
|
+
resolve(!err && COMMIT.test(out) ? out : undefined);
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
resolve(undefined);
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
/** JSON with object keys sorted at every level: the same value always gives the same text. */
|
|
57
|
+
export function canonicalJson(value) {
|
|
58
|
+
if (Array.isArray(value))
|
|
59
|
+
return `[${value.map(canonicalJson).join(",")}]`;
|
|
60
|
+
if (value && typeof value === "object") {
|
|
61
|
+
const o = value;
|
|
62
|
+
return `{${Object.keys(o)
|
|
63
|
+
.filter((k) => o[k] !== undefined)
|
|
64
|
+
.sort()
|
|
65
|
+
.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
|
|
66
|
+
.join(",")}}`;
|
|
67
|
+
}
|
|
68
|
+
return JSON.stringify(value) ?? "null";
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* The part of a scenario's cycles.json entry that decides what runs: its form
|
|
72
|
+
* (and transaction hash), the binaries it names, its CKB-VM version, and for a
|
|
73
|
+
* transaction fetched from a node, the network. Not its name (the key it is
|
|
74
|
+
* matched by), the path of its file (whose bytes are hashed instead: a moved
|
|
75
|
+
* file with the same bytes is the same input), nor `functions` (which records
|
|
76
|
+
* names, not cycles).
|
|
77
|
+
*/
|
|
78
|
+
export function scenarioInputs(s, network) {
|
|
79
|
+
const kind = s.mock !== undefined ? "mock" : s.file !== undefined ? "file" : "tx";
|
|
80
|
+
return {
|
|
81
|
+
kind,
|
|
82
|
+
...(s.tx !== undefined && { tx: s.tx.toLowerCase() }),
|
|
83
|
+
...(s.binaries !== undefined && { binaries: [...s.binaries].sort() }),
|
|
84
|
+
...(s.scriptVersion !== undefined && { scriptVersion: s.scriptVersion }),
|
|
85
|
+
...(kind !== "mock" && { network: network ?? null }),
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* sha256 over a scenario's inputs: the canonical entry (scenarioInputs), then
|
|
90
|
+
* the bytes of its mock or transaction file exactly as read, if it has one.
|
|
91
|
+
*/
|
|
92
|
+
export function inputsHash(entry, file) {
|
|
93
|
+
const h = createHash("sha256");
|
|
94
|
+
h.update("ckb-cycles inputs v1\n");
|
|
95
|
+
h.update(canonicalJson(entry));
|
|
96
|
+
h.update("\n");
|
|
97
|
+
if (file)
|
|
98
|
+
h.update(file);
|
|
99
|
+
return h.digest("hex");
|
|
100
|
+
}
|
|
101
|
+
/** The longest toolchain description a report keeps. */
|
|
102
|
+
export const TOOLCHAIN_MAX = 4096;
|
|
103
|
+
/** A toolchain description as a report keeps it: trimmed, clipped; undefined when empty. */
|
|
104
|
+
export function toolchainOf(s) {
|
|
105
|
+
const t = (s ?? "").trim();
|
|
106
|
+
return t ? (t.length > TOOLCHAIN_MAX ? `${t.slice(0, TOOLCHAIN_MAX - 1)}…` : t) : undefined;
|
|
107
|
+
}
|
package/dist/mock.d.ts
CHANGED
|
@@ -82,6 +82,11 @@ export interface NodeConsensus {
|
|
|
82
82
|
/** "mainnet", "testnet", or the chain id for any other chain. */
|
|
83
83
|
network: string;
|
|
84
84
|
vmEpochs: VmEpochs;
|
|
85
|
+
/**
|
|
86
|
+
* The consensus `max_block_cycles`, when the node gives it: the node verifies
|
|
87
|
+
* each transaction under this one limit (see DEFAULT_TX_CYCLE_LIMIT).
|
|
88
|
+
*/
|
|
89
|
+
maxBlockCycles?: bigint;
|
|
85
90
|
}
|
|
86
91
|
/**
|
|
87
92
|
* Asks the node which chain it serves and when its hardforks took effect, so a
|
package/dist/mock.js
CHANGED
|
@@ -94,7 +94,8 @@ export async function nodeConsensus(rpc) {
|
|
|
94
94
|
return f.epoch_number === null ? Infinity : Number(f.epoch_number);
|
|
95
95
|
};
|
|
96
96
|
const network = c.id === "ckb" ? "mainnet" : c.id === "ckb_testnet" ? "testnet" : c.id;
|
|
97
|
-
|
|
97
|
+
const max = typeof c.max_block_cycles === "string" && /^0x[0-9a-fA-F]+$/.test(c.max_block_cycles) ? BigInt(c.max_block_cycles) : undefined;
|
|
98
|
+
return { chain: c.id, network, vmEpochs: [epochOf("0032"), epochOf("0049")], ...(max !== undefined && max > 0n && { maxBlockCycles: max }) };
|
|
98
99
|
}
|
|
99
100
|
/** Parses a molecule OutPointVec: u32 LE count, then 36-byte out points. */
|
|
100
101
|
export function parseOutPointVec(data) {
|
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
|
-
//
|
|
119
|
-
//
|
|
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,
|