@node-projects/speedscope 2.1.0 → 2.2.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/README.md +47 -6
- package/dist/release/file-format-schema.json +6 -0
- package/dist/release/index.html +1 -1
- package/dist/release/re2js.LICENSE +21 -0
- package/dist/release/release.txt +3 -3
- package/dist/release/speedscope-5DZPH3NW.js +244 -0
- package/docs/IMPORT_FORMATS.md +174 -0
- package/docs/JAVA_THREAD_DUMPS.md +8 -3
- package/docs/JAVA_THREAD_DUMP_ZIP.md +65 -0
- package/docs/LARGE_TRACE_PERFORMANCE.md +72 -0
- package/docs/OTEL_PROFILES.md +117 -0
- package/docs/PERF_IMPORT.md +66 -0
- package/docs/PPROF_IMPORT.md +50 -0
- package/docs/PROFILE_COMPARISON.md +118 -0
- package/docs/PROPERTY_TESTS.md +36 -0
- package/docs/PYTHON_CPROFILE.md +25 -0
- package/docs/RELEASING.md +19 -6
- package/docs/SEARCH_AND_LAYOUT.md +128 -3
- package/docs/SINGLE_FILE.md +55 -0
- package/docs/SOURCE_AND_LABELS.md +116 -1
- package/package.json +14 -2
- package/src/lib/file-format-spec.ts +4 -0
- package/dist/release/speedscope-OUBBGH23.js +0 -191
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Compare profiles
|
|
2
|
+
|
|
3
|
+
Open a recording, then choose **Profile actions → Compare profiles…**. Select a
|
|
4
|
+
baseline and candidate from the loaded profiles, or use **Open comparison
|
|
5
|
+
recording…** to load a second local recording in any supported format. Choose
|
|
6
|
+
its profile and click **Compare**. The application recording is not replaced.
|
|
7
|
+
Both recordings remain in memory until the dialog closes. Replacing the main
|
|
8
|
+
recording closes the comparison and cancels pending work.
|
|
9
|
+
|
|
10
|
+
Profile choices have name filters and pages of 100 options. The current selection
|
|
11
|
+
is retained even when outside the filtered page. After comparison the settings
|
|
12
|
+
collapse; reopen **Profiles and scaling** to change the inputs or mode.
|
|
13
|
+
|
|
14
|
+
## Signed values and matching
|
|
15
|
+
|
|
16
|
+
Differences are always **candidate minus baseline**. Positive/red means an
|
|
17
|
+
increase, negative/blue a decrease, and neutral means unchanged. Total includes
|
|
18
|
+
callees; self excludes them. The root's self weight represents idle/unattributed
|
|
19
|
+
recording weight. These measurements compare the selected inputs; they do not
|
|
20
|
+
identify the cause of a change or establish statistical significance.
|
|
21
|
+
|
|
22
|
+
Functions match by exact name, file, line and column under the same caller path,
|
|
23
|
+
independently of importer-assigned frame IDs. Recursion and different callers
|
|
24
|
+
remain distinct. Equal source identities under one caller merge. Renamed/moved
|
|
25
|
+
code or different symbolication can appear as removed/added paths; there is no
|
|
26
|
+
fuzzy alignment or cross-build symbol matching.
|
|
27
|
+
|
|
28
|
+
**Absolute weights** requires identical units and does not rescale recording
|
|
29
|
+
duration or event rate. **Share of each profile total** divides each side by its
|
|
30
|
+
own full total, including idle weight; differences are percentage points. A
|
|
31
|
+
zero-total profile contributes zero. Different-unit normalized comparisons show
|
|
32
|
+
composition only, not absolute performance. Raw side totals and units remain
|
|
33
|
+
visible so that this distinction can be checked.
|
|
34
|
+
|
|
35
|
+
## Graph, table and navigation
|
|
36
|
+
|
|
37
|
+
The differential flamegraph uses an additive union envelope for widths:
|
|
38
|
+
`max(baseline self, candidate self) + sum(child envelopes)`. It preserves room
|
|
39
|
+
for added and removed paths and may exceed either recording's total. Widths are
|
|
40
|
+
comparison layout weights, not an execution-time axis. Color uses signed total
|
|
41
|
+
differences; tooltip/selection details show both total and self changes.
|
|
42
|
+
|
|
43
|
+
Click or keyboard-focus a tile to select it. Double-click, or use **Zoom to
|
|
44
|
+
selected**, to inspect that subtree. **Parent call path**, ancestor buttons and
|
|
45
|
+
**All stacks** navigate back. Ancestor controls retain at most 16 entries;
|
|
46
|
+
**All stacks** remains available for deep paths.
|
|
47
|
+
|
|
48
|
+
The accessible table displays 100 call paths per page. Search matches full names
|
|
49
|
+
and source files case-insensitively, returning the first 100 matches with an
|
|
50
|
+
explicit limit notice. Selecting a table result focuses its parent so the path
|
|
51
|
+
can be inspected in the graph. Search does not require rendering the full graph.
|
|
52
|
+
|
|
53
|
+
## Resource policy and limits
|
|
54
|
+
|
|
55
|
+
Comparison is a cancellable walk of the grouped trees. It does not retain a
|
|
56
|
+
per-sample stack array or construct full path strings for every node. The result
|
|
57
|
+
still consumes memory proportional to the union; this is not an out-of-core
|
|
58
|
+
comparison engine. Temporary merge indexes are discarded after preparation.
|
|
59
|
+
|
|
60
|
+
| Resource | Maximum |
|
|
61
|
+
| --- | ---: |
|
|
62
|
+
| Union nodes | 500,000 |
|
|
63
|
+
| Input node visits | 2,000,000 |
|
|
64
|
+
| Unique serialized source identity characters | 8 Mi |
|
|
65
|
+
| Name plus file characters per source identity | 65,536 |
|
|
66
|
+
| Graph layout tiles | 5,000 |
|
|
67
|
+
| Graph traversal visits | 20,000 |
|
|
68
|
+
| Graph levels relative to the focused node | 128 |
|
|
69
|
+
|
|
70
|
+
Exceeding a model budget fails explicitly; compare cropped/filtered recordings
|
|
71
|
+
instead. Nonfinite source weights or overflowing union weights also fail.
|
|
72
|
+
Graph detail/depth limits and hidden subpixel paths are indicated. The graph
|
|
73
|
+
mounts only visible rows. Search/table selection and subtree zoom provide access
|
|
74
|
+
to paths beyond the initial graph limits. No weights are silently truncated.
|
|
75
|
+
|
|
76
|
+
PLC self-comparison prepared 160,613 union nodes with zero differences and about
|
|
77
|
+
47.45 MiB retained model heap in one Node 24 ARM64 check. Preparation plus the
|
|
78
|
+
post-comparison GC took 683 ms. This excludes browser import/rendering and is not
|
|
79
|
+
a memory guarantee for another capture. The original PLC export hash was unchanged.
|
|
80
|
+
|
|
81
|
+
Comparison is transient. Closing the dialog releases the external candidate and
|
|
82
|
+
comparison state; reopening starts a new comparison. Existing Export still saves
|
|
83
|
+
the main recording. Comparison-file export, synchronized timelines and
|
|
84
|
+
statistical comparison remain separate features.
|
|
85
|
+
|
|
86
|
+
## Differential folded files
|
|
87
|
+
|
|
88
|
+
Use **Open differential folded…** inside the comparison dialog to open
|
|
89
|
+
`difffolded.pl` output: `stack;leaf baselineWeight candidateWeight`. The two
|
|
90
|
+
columns are nonnegative weights, not a weight and its signed delta. The first
|
|
91
|
+
becomes Baseline and the second Candidate; click **Compare** to see their signed
|
|
92
|
+
differences. Both sides are also available in the profile selectors. **Use loaded
|
|
93
|
+
recording** restores the original choices. The main recording is unchanged.
|
|
94
|
+
|
|
95
|
+
Alternatively, import a file named `capture.diff.folded` or
|
|
96
|
+
`capture.differential.folded` (also `.collapsed`, `.stacks`, and gzip variants)
|
|
97
|
+
through the main Import button. It creates two ordinary aggregate profiles;
|
|
98
|
+
choose Compare profiles to visualize them. Export preserves both sides as
|
|
99
|
+
ordinary speedscope profiles. No signed native schema extension is required.
|
|
100
|
+
|
|
101
|
+
Selection is explicit because `function 12 3` could be an ordinary folded symbol
|
|
102
|
+
named `function 12` with weight 3. Ordinary folded import retains that meaning.
|
|
103
|
+
The differential picker supports any filename, using an internal format hint.
|
|
104
|
+
It rejects malformed noncomment lines, negative/nonfinite weights, overflowing
|
|
105
|
+
totals and mixed one/two-column files. Decimal/scientific notation is accepted;
|
|
106
|
+
all-zero rows have no measured width. UTF-8 plain/native-gzip inputs stream with
|
|
107
|
+
the existing text byte, line, sample and depth guards. Output models still scale
|
|
108
|
+
with both sides; generic fallback decoding can materialize expanded input.
|
|
109
|
+
|
|
110
|
+
The format follows the [producer's column definition](https://github.com/brendangregg/FlameGraph/blob/master/difffolded.pl).
|
|
111
|
+
Our graph uses the documented union envelope and total-delta colors. It does not
|
|
112
|
+
reproduce the producer SVG's candidate-only widths or self-only color scale.
|
|
113
|
+
Weights already normalized by the producer are imported as supplied; choose
|
|
114
|
+
absolute mode to avoid normalizing them again. See the
|
|
115
|
+
[authored example](../sample/profiles/differential-folded/example.diff.folded).
|
|
116
|
+
|
|
117
|
+
Signed pprof delta recordings use a related contribution-pair projection,
|
|
118
|
+
explained in [pprof import](PPROF_IMPORT.md).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Property-test migration
|
|
2
|
+
|
|
3
|
+
The utility and LRU suites use fast-check 4.10.3. Byte domains remain signed
|
|
4
|
+
8-bit for bisect inputs and unsigned 8-bit for base64 data. Generated arrays
|
|
5
|
+
now cover up to 50 values; cache histories cover up to 100 commands, retaining
|
|
6
|
+
the 1,000-run cache comparison against the slow reference implementation.
|
|
7
|
+
Fast-check reports a seed and shrink path on failure for deterministic replay.
|
|
8
|
+
|
|
9
|
+
The math suite still uses jsverify. This is intentional partial progress on
|
|
10
|
+
[#354](https://github.com/jlfwong/speedscope/issues/354), not a completed migration.
|
|
11
|
+
The previous default number generator used a size in 0–50 and 32-bit fractions;
|
|
12
|
+
it did not sample arbitrary IEEE doubles. Filtered generators also grew their
|
|
13
|
+
size after repeated rejection. Replacing them with generic finite doubles or
|
|
14
|
+
fixed bounded filters changes their domain and behavior.
|
|
15
|
+
|
|
16
|
+
A trial migration exposed fixed-absolute-tolerance inverse round-trip failures
|
|
17
|
+
for near-singular transforms. Two recorded coefficient/input examples are:
|
|
18
|
+
|
|
19
|
+
| Operation | Affine coefficients `(m00,m01,m02,m10,m11,m12)` | Input |
|
|
20
|
+
| --- | --- | --- |
|
|
21
|
+
| Vector round-trip | `(-34,-34,-34,-34,-33.999999984167516,-34)` | `(0,-0.9999999986030161)` |
|
|
22
|
+
| Position round-trip | `(-27,-27,-27,-27,-26.999999987427145,-27)` | `(0,0)` |
|
|
23
|
+
|
|
24
|
+
The observed round-trip outputs were `(0,-1)` and
|
|
25
|
+
`(2.384185792125848e-7,0)`, respectively. These are evidence for numerical
|
|
26
|
+
conditioning/oracle investigation, not a demonstrated new runtime regression.
|
|
27
|
+
A simple componentwise residual bound also proved unsuitable for every
|
|
28
|
+
explicit-inverse position solve. The trial math migration and tentative oracle
|
|
29
|
+
changes were discarded; the checked-in math suite and runtime math remain
|
|
30
|
+
unchanged. The existing #138 deterministic composition counterexample and
|
|
31
|
+
extreme-scale checks remain covered.
|
|
32
|
+
|
|
33
|
+
Before migrating the math suite, choose and justify inverse/solve error checks
|
|
34
|
+
that distinguish conditioning from implementation errors, preserve the generated
|
|
35
|
+
domains and shrinking, and retain the recorded cases. Do not narrow generators
|
|
36
|
+
or discard difficult inputs merely to make the migration green.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Native Python cProfile statistics
|
|
2
|
+
|
|
3
|
+
Open an uncompressed `cProfile.Profile.dump_stats()` file named `.prof`, `.pstats`, or `.cprofile`. The importer reads a restricted, data-only subset of CPython's marshal format. It does not invoke Python, execute code, or accept pickle/code objects. A marshal dictionary signature and the complete cProfile record schema are required; the extension alone does not establish validity.
|
|
4
|
+
|
|
5
|
+
The primary profile, **flat self time**, preserves each function's measured self time in seconds, with filename and first source line. Its total is the sum of those self times. No call order is available. Functions with zero self time have no measured width in this projection.
|
|
6
|
+
|
|
7
|
+
The secondary profile, **immediate-caller self time; not full stacks**, assigns each function's self time to its recorded direct callers. A two-frame stack represents one direct edge only. Self time not attributed to a caller appears as a one-frame stack. Recursive edges remain two-frame edges; they are not expanded into hypothetical deep stacks. Both profiles are marked nonchronological, including after export.
|
|
8
|
+
|
|
9
|
+
cProfile stores an aggregate directed call graph. Shared callees and recursion mean the original full stack paths cannot be recovered from these records. This importer does not invent those paths or turn cumulative times into additive self time. Primitive/total call counts and cumulative times are validated, but are not separate displayed metrics. If caller self times exceed a function's self time beyond rounding tolerance, the importer keeps only the exact flat projection and marks its profile name **caller attribution unavailable**. Tiny floating-point excesses within relative tolerance `1e-12` are clipped to the remaining self time.
|
|
10
|
+
|
|
11
|
+
## Limits and cancellation
|
|
12
|
+
|
|
13
|
+
The native decoder accepts at most 32 MiB of input, one million decoded objects, 500,000 references, 8 MiB of decoded string bytes in total, 64 KiB per source string, depth 16, 100,000 functions, and 200,000 direct caller edges. All limits apply together; a smaller object/string limit can be reached before the function/edge ceiling. The reader checks lengths before allocation, rejects incomplete/cyclic references, duplicate source identities, trailing data, unsafe integer counts, invalid UTF-8, unsupported object types, and nonfinite/negative measurements. Decoding/building yields periodically and supports cancellation. The parsed marshal graph and both output projections coexist during import; this is a bounded in-memory importer, not a streaming or out-of-core format.
|
|
14
|
+
|
|
15
|
+
Oversized **raw** native files are checked using a six-byte signature slice before reading their body. Generic gzip/zlib decompression happens before binary format detection and is not currently bounded by this native decoder's input limit. Compressed `.prof` files can also be pprof recordings, so those generic wrappers are retained. For predictable memory use with native cProfile, supply the uncompressed marshal file within the size limit. Do not treat the 32 MiB decoder limit as a generic compressed-input expansion limit.
|
|
16
|
+
|
|
17
|
+
## Compatibility and evidence
|
|
18
|
+
|
|
19
|
+
The fixtures were produced by CPython 3.14.3's actual cProfile profiler, with a deterministic timer, a shared callee, builtins, and recursion. The same statistics are additionally serialized with marshal wire versions 0–5. These fixtures verify the supported data encodings; they do not establish compatibility with every historical or future Python release. Python explicitly reserves the right to change marshal and profiler file formats. Python 2 byte-string labels, pure-Python `profile`'s different caller schema, arbitrary marshal values, and future unsupported encodings are rejected rather than guessed.
|
|
20
|
+
|
|
21
|
+
- [CPython 3.14.3 cProfile implementation](https://github.com/python/cpython/blob/v3.14.3/Lib/cProfile.py): `snapshot_stats()` defines function and caller tuples.
|
|
22
|
+
- [CPython 3.14.3 marshal implementation](https://github.com/python/cpython/blob/v3.14.3/Python/marshal.c): numeric/string/container/reference encodings.
|
|
23
|
+
- [Python marshal documentation](https://docs.python.org/3.14/library/marshal.html): version limitations and the hazards of unrestricted native unmarshalling.
|
|
24
|
+
- [Python pstats documentation](https://docs.python.org/3/library/pstats.html): self/cumulative time and call-count meanings.
|
|
25
|
+
- [Synthetic fixture source and regeneration](../sample/profiles/python-cprofile/README.md).
|
package/docs/RELEASING.md
CHANGED
|
@@ -51,8 +51,10 @@ For a new version, it attaches the newly built npm tarball as well.
|
|
|
51
51
|
|
|
52
52
|
## npm trusted publishing after the first publication
|
|
53
53
|
|
|
54
|
-
The npm trusted publisher
|
|
55
|
-
|
|
54
|
+
The original npm trusted publisher, created on 2026-11-18, expired before its
|
|
55
|
+
first automated publication. It was recreated on 2026-11-21 and successfully
|
|
56
|
+
published **2.1.0** through the [release workflow retry](https://github.com/node-projects/speedscope/actions/runs/44884626601/attempts/2).
|
|
57
|
+
This validates end-to-end OIDC publication for the following GitHub Actions identity:
|
|
56
58
|
|
|
57
59
|
- Organization/user: `node-projects`
|
|
58
60
|
- Repository: `speedscope`
|
|
@@ -79,16 +81,27 @@ npm trust github @node-projects/speedscope --repository node-projects/speedscope
|
|
|
79
81
|
```
|
|
80
82
|
|
|
81
83
|
npm requires fresh two-factor authentication for these account operations. The
|
|
82
|
-
setup
|
|
83
|
-
|
|
84
|
+
original setup used the CLI's browser authentication flow; the replacement used
|
|
85
|
+
npm's package settings in the browser. No credentials were added to the repository.
|
|
86
|
+
Recreating an existing publisher is not a routine
|
|
84
87
|
release step.
|
|
85
88
|
|
|
86
89
|
New publisher configurations must complete their first successful automated
|
|
87
90
|
publish within **two days**, otherwise npm expires them. Creating a GitHub release
|
|
88
91
|
for an already-published version does not validate OIDC because this workflow
|
|
89
92
|
skips the npm publish step for that version. Use the next new version (for example
|
|
90
|
-
`v2.0.1`) when ready.
|
|
91
|
-
|
|
93
|
+
`v2.0.1`) when ready. The recreated connection completed this validation with
|
|
94
|
+
2.1.0; the two-day deadline applies to new, unvalidated connections.
|
|
95
|
+
|
|
96
|
+
If publication fails with `E404` while the package exists, inspect **Trusted
|
|
97
|
+
Publisher** in npm package settings. On 2026-11-21 this displayed **Expired**;
|
|
98
|
+
the runner's Node/npm versions and OIDC permission were already correct. Delete
|
|
99
|
+
the expired connection, recreate the same identity with direct publication
|
|
100
|
+
allowed, then retry the failed job or dispatch the existing release tag.
|
|
101
|
+
npm may require separate fresh authentication checks to view settings, delete
|
|
102
|
+
the expired connection and save its replacement. Verify the retry's publish
|
|
103
|
+
step and the registry's version/dist-tag afterward. No code or tag change was
|
|
104
|
+
needed for this recovery.
|
|
92
105
|
|
|
93
106
|
See [npm's trusted publisher setup](https://docs.npmjs.com/trusted-publishers/).
|
|
94
107
|
The repository URL in package.json points to this fork, as required for provenance.
|
|
@@ -1,5 +1,83 @@
|
|
|
1
1
|
# Search across profiles and arrange Sandwich panes
|
|
2
2
|
|
|
3
|
+
## Choose a profile with the keyboard
|
|
4
|
+
|
|
5
|
+
For a recording with several profiles, click the profile name in the toolbar or
|
|
6
|
+
press **t** to open the chooser. The **Filter profiles** combobox receives focus.
|
|
7
|
+
Type part of a thread/profile name to filter with the existing fuzzy matching.
|
|
8
|
+
Queries are limited to 256 characters. The result list identifies the currently
|
|
9
|
+
selected profile separately from the active keyboard result.
|
|
10
|
+
|
|
11
|
+
Use **Up/Down** to move the active result, **Home/End** to reach either end and
|
|
12
|
+
**Page Up/Page Down** to move by a results page. **Enter** selects the active
|
|
13
|
+
profile. **Escape** or **Close** dismisses the chooser and returns focus to its
|
|
14
|
+
trigger. Typing during an input-method composition does not activate results;
|
|
15
|
+
modified editing shortcuts such as Ctrl/Command+A retain their normal behavior.
|
|
16
|
+
Typing in the chooser does not trigger the viewer's global shortcuts.
|
|
17
|
+
|
|
18
|
+
The result list exposes a listbox with selected state, an active descendant and
|
|
19
|
+
each result's position in the full filtered set. Native buttons sort by index,
|
|
20
|
+
name or total non-idle weight and report the active direction. Tab can reach the
|
|
21
|
+
sort, page and Close controls; moving focus outside dismisses the chooser without
|
|
22
|
+
pulling focus back from the next control. Clicking an option also selects it.
|
|
23
|
+
|
|
24
|
+
At most **100 options** are mounted at a time. Keyboard navigation automatically
|
|
25
|
+
switches result pages, and **Previous/Next** page buttons make other results
|
|
26
|
+
available without rendering every profile row. The result range is displayed
|
|
27
|
+
explicitly. Filtered/sorted results retain numeric profile indices; highlight
|
|
28
|
+
ranges are calculated only for the displayed page. Filtering and sorting still
|
|
29
|
+
scan or arrange the recording's profile list, so the DOM bound is not a total
|
|
30
|
+
memory or processing-time guarantee. This improves the chooser's portion of
|
|
31
|
+
[#376](https://github.com/jlfwong/speedscope/issues/376); it does not make the
|
|
32
|
+
canvas charts or every viewer control fully accessible.
|
|
33
|
+
|
|
34
|
+
## Regular expression search
|
|
35
|
+
|
|
36
|
+
The viewer and Search all profiles offer **Regex (RE2)** alongside the existing
|
|
37
|
+
literal Contains, Whole word and Exact modes. Enter a pattern directly, such as
|
|
38
|
+
`^render|worker[0-9]+` or `\.tsx?$`, without JavaScript `/.../flags` delimiters.
|
|
39
|
+
Matching starts case-insensitive; RE2 inline flags can adjust it. Both function
|
|
40
|
+
names and source paths are searched in full, with no symbol truncation.
|
|
41
|
+
|
|
42
|
+
The engine is the pinned MIT-licensed
|
|
43
|
+
[`re2js` 2.10.0](https://github.com/le0pard/re2js/tree/2.10.0), a pure JavaScript
|
|
44
|
+
RE2 port. It uses linear-time matching rather than executing user patterns with
|
|
45
|
+
native JavaScript's backtracking engine. Backreferences and lookaround are
|
|
46
|
+
unsupported here and produce an error. RE2 syntax differs from JavaScript
|
|
47
|
+
RegExp syntax; the app does not translate unsupported expressions or silently
|
|
48
|
+
switch engines. Literal modes keep their previous behavior.
|
|
49
|
+
|
|
50
|
+
Patterns are limited to 256 UTF-16 characters. A conservative preflight rejects
|
|
51
|
+
counted-repeat bounds above 1,000 or estimated expansions above 4,096 states
|
|
52
|
+
before compilation; the compiled program also has a 4,096-state ceiling. This
|
|
53
|
+
can reject some otherwise valid RE2 expressions; simplify their repetitions.
|
|
54
|
+
Invalid syntax and limits appear as errors in the search UI, without replacing
|
|
55
|
+
the profile or crashing its rendering. Empty patterns match nothing. Zero-width
|
|
56
|
+
matches select frames but do not paint nonexistent characters. Highlight offsets
|
|
57
|
+
use UTF-16 indices, including after astral characters, as the existing label
|
|
58
|
+
renderer expects.
|
|
59
|
+
|
|
60
|
+
One compiled pattern is cached for validation/reuse; existing bounded frame and
|
|
61
|
+
highlight caches and navigation/result caps still apply. At most 64 match
|
|
62
|
+
attempts per visible label are used for highlights, counting zero-width matches
|
|
63
|
+
toward this budget. Boolean matching still scans the complete symbol. Search
|
|
64
|
+
across profiles yields between bounded batches; synchronous matching of an
|
|
65
|
+
individual exceptionally long symbol can still take time proportional to its
|
|
66
|
+
length. This is not a fixed wall-time guarantee or a cap on profile storage.
|
|
67
|
+
|
|
68
|
+
The dependency has no runtime dependencies or external WASM/network load. An
|
|
69
|
+
isolated esbuild minified browser import measured approximately 151 KB (46 KB
|
|
70
|
+
gzip); final app bundle size depends on bundling and compression.
|
|
71
|
+
|
|
72
|
+
A local PLC regression scanned 513,009 occurrences with a no-match regex in
|
|
73
|
+
30 ms and retained about 0.60 MiB of search state after collection. A broad
|
|
74
|
+
`^.*` query reached the existing 10,000-result navigation ceiling in 6 ms and
|
|
75
|
+
retained about 1.02 MiB. Both runs preserved four profiles, 17,510 exported
|
|
76
|
+
frames, 1,039,656 events and export hash
|
|
77
|
+
`522de77afbfc4dd94f1f30c3a9551979d12db506305ffef999db9c910ae8eddb`.
|
|
78
|
+
These are individual Windows ARM64 Node observations, not browser latency or
|
|
79
|
+
total-memory guarantees; they exclude import and initial flamechart creation.
|
|
80
|
+
|
|
3
81
|
## Search all profiles
|
|
4
82
|
|
|
5
83
|
Choose **Profile actions → Search all profiles…**, enter a function name or source
|
|
@@ -122,7 +200,7 @@ occurrences in depth-first order. If there are more, the count shows `10000+`
|
|
|
122
200
|
and a visible status asks you to refine your search. This is a lower bound,
|
|
123
201
|
not the full count. Previous/Next and Enter/Shift+Enter wrap within the retained
|
|
124
202
|
window. A selected frame outside that window shows `?` for its navigation index.
|
|
125
|
-
Use a more specific name/path or Whole word/Exact mode to narrow the query.
|
|
203
|
+
Use a more specific name/path or Whole word/Exact/Regex mode to narrow the query.
|
|
126
204
|
|
|
127
205
|
Matching and graph highlights still inspect full names and source paths, even
|
|
128
206
|
outside the navigation window. Sparse queries can find late occurrences: the
|
|
@@ -137,7 +215,7 @@ and 512 highlight lists, evicting old entries and recomputing them when needed.
|
|
|
137
215
|
Only labels/rows being drawn request name-highlight ranges, capped at the first
|
|
138
216
|
64 ranges per name. A long, repetitive name can therefore match beyond its
|
|
139
217
|
drawn underlines. File-only matches have no name underlines. Search input is
|
|
140
|
-
limited to 4,096 characters
|
|
218
|
+
limited to 4,096 characters in literal modes; Regex has the separate 256-character and compilation limits described above.
|
|
141
219
|
|
|
142
220
|
Search no longer builds a full per-symbol highlight map or a rectangle for
|
|
143
221
|
every matching call. Traversal uses O(depth) auxiliary storage and creates a
|
|
@@ -234,7 +312,54 @@ errors. A PLC streaming smoke retained four profiles, 17,510 frames and
|
|
|
234
312
|
2.4 seconds in that Node run. These UI changes add no per-frame context index or
|
|
235
313
|
profile copy. Source-name metadata is one bounded string per group.
|
|
236
314
|
|
|
237
|
-
##
|
|
315
|
+
## Refocus a search match
|
|
316
|
+
|
|
317
|
+
Graph search offers **Zoom to match** once a retained result is selected. After
|
|
318
|
+
zooming or panning away, use it to center that same match with a little context.
|
|
319
|
+
The action changes only the viewport: measured widths and profile weights stay
|
|
320
|
+
intact. Ordinary next/previous navigation is unchanged, and the existing 10,000
|
|
321
|
+
result cap and numerical zoom limits still apply. Very small matches may reach
|
|
322
|
+
those precision limits. Sandwich's table search does not add this graph action.
|
|
323
|
+
|
|
324
|
+
This partially addresses [#548](https://github.com/jlfwong/speedscope/issues/548);
|
|
325
|
+
artificially inflating tiles in an overview remains separate work.
|
|
326
|
+
|
|
327
|
+
## Share function links
|
|
328
|
+
|
|
329
|
+
Select a function in Time Order, Left Heavy or Sandwich, then choose **Profile
|
|
330
|
+
actions → Link to selected function…**. Review and copy the generated URL in the
|
|
331
|
+
dialog. When opened with the same recording, it selects the matching profile and
|
|
332
|
+
function in Sandwich. Local files are not uploaded or embedded: the recipient
|
|
333
|
+
must import the same recording after opening the link. For an HTTP recording,
|
|
334
|
+
the link retains its URL and Accept setting only when associated with the actual
|
|
335
|
+
loaded profile. Opening another local file does not reuse an old remote URL.
|
|
336
|
+
|
|
337
|
+
The link stores a versioned profile index/name/unit/total and function
|
|
338
|
+
name/file/line/column identity. Importer-assigned frame keys can change without
|
|
339
|
+
breaking it. Multiple identical source identities are rejected rather than
|
|
340
|
+
silently selecting another frame. Selection JSON is limited to 8,192 characters
|
|
341
|
+
and complete links to 65,536; existing data/file profile URLs and local paths are
|
|
342
|
+
not copied. Function/source names and an HTTP URL's credentials can appear in the
|
|
343
|
+
reviewable link. It cannot grant access to a remote recording.
|
|
344
|
+
|
|
345
|
+
Matching scans the chosen profile's frames once, without a retained frame index.
|
|
346
|
+
Only the first successful restoration for a link is applied; later imports do not
|
|
347
|
+
jump back to that selection. Navigating to another function link in the same tab,
|
|
348
|
+
including browser Back/Forward, restores its selection against the current
|
|
349
|
+
recording without reimporting it. Missing or ambiguous matches show a status
|
|
350
|
+
message and remain pending until the original recording is imported.
|
|
351
|
+
Changing the HTTP profile source or Accept setting starts a cancellable import.
|
|
352
|
+
A new remote link takes precedence over a pending import of another recording;
|
|
353
|
+
selection-only changes during import apply when that import finishes.
|
|
354
|
+
Derived profiles must be exported and reopened first. Symbol-remapped copies
|
|
355
|
+
conservatively generate links requiring local reimport.
|
|
356
|
+
|
|
357
|
+
This partially addresses [#506](https://github.com/jlfwong/speedscope/issues/506).
|
|
358
|
+
Exact call instances, graph view/zoom/time range and profile transformations are
|
|
359
|
+
not restored. Function links select the matching symbol in Sandwich, rather than
|
|
360
|
+
restoring a specific call occurrence or graph viewport.
|
|
361
|
+
|
|
362
|
+
## Upstream review history
|
|
238
363
|
|
|
239
364
|
The 2026-11-21 shared-selection, Java text-dump, hosted-offline and numerical
|
|
240
365
|
test follow-up passed all 393 Jest tests across 68 suites (307 snapshots), five
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Single-HTML build
|
|
2
|
+
|
|
3
|
+
From a repository checkout with dependencies installed, run:
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm run build:single-file
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
The result is `dist/speedscope-standalone.html`. Application code, CSS, fonts,
|
|
10
|
+
icons, the example recording, import-worker code and WebAssembly decoders are
|
|
11
|
+
embedded in that document. It needs no companion assets or source maps. The
|
|
12
|
+
license texts included in the existing standalone release remain in the HTML
|
|
13
|
+
as inert JSON, alongside bundle license comments. CI builds this option on
|
|
14
|
+
Windows/Linux and uploads it with each standalone artifact.
|
|
15
|
+
|
|
16
|
+
Combined validation passed 413 Jest tests in 71 suites, 307 snapshots, five
|
|
17
|
+
Node tests, type checking, lint and schema/backlog checks. Browser QA imported
|
|
18
|
+
the embedded example, local JFR and the private PLC gzip from this one document;
|
|
19
|
+
the preview server logged only the document request and browser errors were
|
|
20
|
+
empty. The browser tool blocks file-protocol navigation, so no `file://` startup
|
|
21
|
+
claim is made here.
|
|
22
|
+
|
|
23
|
+
Serve the document from your own HTTP server or copy it for portable use. It
|
|
24
|
+
registers no service worker and contains no recording supplied by the user.
|
|
25
|
+
Local imports stay in the browser. Explicit remote recording links still need
|
|
26
|
+
their server and CORS permissions. The existing multi-file standalone ZIP,
|
|
27
|
+
CLI and hosted Pages builds remain available independently.
|
|
28
|
+
|
|
29
|
+
## Content Security Policy
|
|
30
|
+
|
|
31
|
+
One document simplifies deployment but does not remove the app's CSP needs.
|
|
32
|
+
The build prints the SHA-256 source hash for its inline application script;
|
|
33
|
+
use that exact build-specific value in `script-src` if allowing inline code
|
|
34
|
+
by hash. Rebuilding changes the hash. Workers use Blob URLs; decoders use
|
|
35
|
+
WebAssembly; fonts and icons use data URLs. Aphrodite and component styles
|
|
36
|
+
still require dynamically inserted styles and inline style attributes.
|
|
37
|
+
|
|
38
|
+
Browser verification used the following HTTP response policy, serving only
|
|
39
|
+
the HTML document and rejecting all other request paths:
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
default-src 'none'; script-src 'unsafe-inline' 'wasm-unsafe-eval' blob:; style-src 'unsafe-inline'; font-src data:; img-src data:; connect-src data:; worker-src blob:;
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
That policy allowed the embedded example and local JFR/PLC imports without
|
|
46
|
+
companion requests. It blocks remote recordings and source-map network fetches;
|
|
47
|
+
add only the required remote origins to your own deployment's `connect-src`.
|
|
48
|
+
This is an observed deployment example, not a recommendation to relax an
|
|
49
|
+
existing application's policy. Strict policies forbidding inline styles still
|
|
50
|
+
need a style-engine/attribute integration strategy. Browser file-URL startup
|
|
51
|
+
could not be checked by the browser automation tool, which permits HTTP(S) only.
|
|
52
|
+
|
|
53
|
+
This extends [#108](https://github.com/jlfwong/speedscope/issues/108) with a true
|
|
54
|
+
single-document option. Strict-CSP embedding and a supported multi-instance
|
|
55
|
+
library API remain separate work.
|
|
@@ -1,4 +1,82 @@
|
|
|
1
|
-
# Source-code links and compact graph labels
|
|
1
|
+
# Source maps, source-code links and compact graph labels
|
|
2
|
+
|
|
3
|
+
## Load a linked JavaScript source map
|
|
4
|
+
|
|
5
|
+
Choose **Profile actions → Load linked source map…** after loading a recording.
|
|
6
|
+
Enter the generated JavaScript's HTTP(S) URL as it appears in the recording.
|
|
7
|
+
The dialog suggests the selected function's HTTP(S) source URL when available.
|
|
8
|
+
Opening the dialog or selecting a function performs no network request.
|
|
9
|
+
|
|
10
|
+
1. Choose **Load preview** to fetch that script and its linked source map.
|
|
11
|
+
2. Review the generated-script URL, resolved map URL and number of frames that
|
|
12
|
+
would change. The recording remains unchanged during preview.
|
|
13
|
+
3. Choose **Apply source map** to update matching symbols and source locations
|
|
14
|
+
across the loaded profiles. Weights, profile flags and recording metadata
|
|
15
|
+
remain intact. Editing the URL invalidates the preview.
|
|
16
|
+
|
|
17
|
+
The map applies only to the chosen generated-script URL, including its query
|
|
18
|
+
string. It may have a different or hashed filename. Relative original-source
|
|
19
|
+
URLs are resolved against the fetched map URL; original source files are never
|
|
20
|
+
fetched. A script's exposed `SourceMap` response header takes precedence over
|
|
21
|
+
`X-SourceMap` and its trailing `sourceMappingURL` comment. JavaScript comments
|
|
22
|
+
are located with a tokenizer, so annotation-like text inside strings and
|
|
23
|
+
templates cannot initiate a map request. The script is never executed.
|
|
24
|
+
|
|
25
|
+
Both requests omit cookies and other credentials, use CORS and `no-store`, and
|
|
26
|
+
reject redirects. Use a direct URL whose server allows cross-origin access.
|
|
27
|
+
For a cross-origin `SourceMap` header, the server must also expose that header
|
|
28
|
+
with `Access-Control-Expose-Headers`. HTTP errors, CORS failures, missing links
|
|
29
|
+
and unmatched source positions stay visible in the dialog. **Cancel load**,
|
|
30
|
+
Escape and Close abort pending work. Importing another recording or changing
|
|
31
|
+
the profile models closes the dialog and invalidates its captured preview.
|
|
32
|
+
|
|
33
|
+
The downloaded script body is limited to 8 MiB when it must be inspected; an
|
|
34
|
+
exposed map header allows its body to be cancelled immediately. A map is limited
|
|
35
|
+
to 2 MiB. Before decoding mappings, the loader limits their encoded segment
|
|
36
|
+
count to 100,000 across nested index maps, with at most 1,000 indexed sections,
|
|
37
|
+
32 nesting levels and 128 encoded characters in one VLQ segment. The preview
|
|
38
|
+
retains at most 100,000 changed frames. Loading has a 30-second timeout and yields
|
|
39
|
+
between token/preview batches so cancellation can be handled. These limits
|
|
40
|
+
bound the additional work; they do not make the underlying recording independent
|
|
41
|
+
of browser memory limits.
|
|
42
|
+
|
|
43
|
+
For local scripts/maps, choose **Import** and open the `.map` file after loading
|
|
44
|
+
your recording. This also provides a fallback when CORS or credentials prevent
|
|
45
|
+
remote loading, a limit is exceeded, or the generated script cannot be fetched.
|
|
46
|
+
Both workflows need usable recorded line and column positions.
|
|
47
|
+
The browser does not read arbitrary local paths from a recording. Inline
|
|
48
|
+
`data:` maps, non-HTTP(S) links and URLs containing embedded credentials are
|
|
49
|
+
unsupported in the linked-map dialog. JavaScript syntax unrecognized by its
|
|
50
|
+
ES2020 tokenizer requires an exposed map header or local-map import.
|
|
51
|
+
|
|
52
|
+
This is explicit linked-map discovery for upstream
|
|
53
|
+
[#446](https://github.com/jlfwong/speedscope/issues/446), not automatic filesystem
|
|
54
|
+
discovery for Node/esbuild logs. Logs without usable source positions still
|
|
55
|
+
cannot be mapped. The linking/header behavior follows
|
|
56
|
+
[ECMA-426](https://tc39.es/ecma426/2024/#sec-retrieving-source-maps).
|
|
57
|
+
|
|
58
|
+
## Embedded source-line lookup
|
|
59
|
+
|
|
60
|
+
Unnamed source-map entries can infer a symbol from embedded original-source
|
|
61
|
+
text. Lookup now uses sparse newline checkpoints instead of repeatedly scanning
|
|
62
|
+
from the start or splitting the entire source into a line array. A per-remapper
|
|
63
|
+
LRU retains at most 16 source indexes, each with at most 4,096 Uint32 checkpoints:
|
|
64
|
+
**256 KiB maximum retained checkpoint storage**, excluding source strings and
|
|
65
|
+
the mapping consumer. Checkpoints begin every 64 lines and become coarser for
|
|
66
|
+
very long local sources. Arbitrary query order, CRLF, empty/final lines and
|
|
67
|
+
replacement source contents preserve the same inferred names.
|
|
68
|
+
|
|
69
|
+
Preview checks elapsed time as well as frame count, yielding after 8 ms or 128
|
|
70
|
+
frames. SourceMapConsumer decoding remains synchronous under the existing linked
|
|
71
|
+
map size/mapping limits; these changes do not make all map loading interruptible.
|
|
72
|
+
|
|
73
|
+
Run `npx tsx scripts/benchmark-source-maps.ts` for the deterministic comparison.
|
|
74
|
+
One Node 24.19.0 ARM64 run used 100,000 source lines (2,488,889 characters) and
|
|
75
|
+
5,000 shuffled line queries: the old scan took 2,722 ms and indexed lookup 11 ms,
|
|
76
|
+
with identical checksums and an 8 KiB index. Mapping 100,000 shuffled frames took
|
|
77
|
+
169 ms with no mismatches. This is a local-source lookup/remapping measurement,
|
|
78
|
+
excluding network and browser rendering. The synthetic embedded source is larger
|
|
79
|
+
than the linked-map download cap; local-map imports do not use that download cap.
|
|
2
80
|
|
|
3
81
|
## Open a source location
|
|
4
82
|
|
|
@@ -47,6 +125,43 @@ search and exports. Function signatures containing path-like punctuation are
|
|
|
47
125
|
preserved. Search still matches the full name: a match entirely inside a hidden
|
|
48
126
|
prefix can highlight a frame without underlining text in its displayed suffix.
|
|
49
127
|
|
|
128
|
+
## Producer-selected frame colors
|
|
129
|
+
|
|
130
|
+
Native `.speedscope.json` producers can set an optional `color` on each shared
|
|
131
|
+
frame. Use exactly six RGB hex digits, such as `"color": "#8A2BE2"`. Short hex,
|
|
132
|
+
alpha channels, named colors and CSS expressions are rejected. Frames without
|
|
133
|
+
this field keep the normal generated theme colors.
|
|
134
|
+
|
|
135
|
+
```json
|
|
136
|
+
{"name": "compiled method", "file": "example.rb", "line": 12, "color": "#8A2BE2"}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
The main flamechart, minimap and function color indicators honor the supplied
|
|
140
|
+
color in both themes. If a color would hide the normal frame label, its displayed
|
|
141
|
+
RGB is mixed toward the active theme background until the label has at least
|
|
142
|
+
4.5:1 contrast. Unmatched search labels retain the existing dimmed style, and
|
|
143
|
+
search highlights and selection outlines remain visible above the frame color.
|
|
144
|
+
Comparison flamegraphs continue to use their signed-difference colors.
|
|
145
|
+
|
|
146
|
+
The original RGB spelling survives imports, worker transport and both export
|
|
147
|
+
paths unchanged; theme adjustments affect presentation only. Producers can use
|
|
148
|
+
separate shared-frame entries for the same function when it needs different
|
|
149
|
+
colors. Combining profiles preserves different RGB identities while treating
|
|
150
|
+
upper- and lowercase spellings of the same RGB as equivalent.
|
|
151
|
+
|
|
152
|
+
Each graph renderer retains at most 65,025 distinct custom colors in one fixed
|
|
153
|
+
256 KiB palette, allocated only when a custom color occurs. Additional colors
|
|
154
|
+
fall back to generated colors in that graph, with one console warning. Their raw
|
|
155
|
+
RGB values still survive export, and table indicators can still display them.
|
|
156
|
+
Vertex buffers retain their existing stride, and cached and direct graph draws
|
|
157
|
+
use the same palette. This does not impose a bound on the recording itself.
|
|
158
|
+
|
|
159
|
+
This implements the producer-color request in upstream
|
|
160
|
+
[#351](https://github.com/jlfwong/speedscope/issues/351). It does not add an editor
|
|
161
|
+
for assigning colors to frames in an already loaded recording. See
|
|
162
|
+
[`custom-colors.speedscope.json`](../sample/profiles/speedscope/custom-colors.speedscope.json)
|
|
163
|
+
for a complete example.
|
|
164
|
+
|
|
50
165
|
## Large traces
|
|
51
166
|
|
|
52
167
|
Neither setting reimports or transforms a recording. Labels are shortened only
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@node-projects/speedscope",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.2.0",
|
|
4
4
|
"description": "A fast, interactive performance profile viewer with large-trace improvements, an accessible call tree and offline CLI.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
"backlog:generate": "node scripts/generate-issue-backlog.mjs",
|
|
26
26
|
"backlog:check": "node scripts/generate-issue-backlog.mjs --check",
|
|
27
27
|
"build:pages": "node scripts/prepare-release.mjs --protocol http",
|
|
28
|
+
"build:single-file": "tsx scripts/build-single-file.ts",
|
|
28
29
|
"deploy": "gh workflow run pages.yml --ref main",
|
|
29
30
|
"release:version": "node scripts/set-release-version.mjs",
|
|
30
31
|
"prepack": "node scripts/prepare-release.mjs",
|
|
@@ -43,10 +44,19 @@
|
|
|
43
44
|
"docs/RELEASING.md",
|
|
44
45
|
"docs/LARGE_TRACE_PERFORMANCE.md",
|
|
45
46
|
"docs/PROFILE_FILTERS.md",
|
|
47
|
+
"docs/PROFILE_COMPARISON.md",
|
|
48
|
+
"docs/PPROF_IMPORT.md",
|
|
49
|
+
"docs/PYTHON_CPROFILE.md",
|
|
46
50
|
"docs/SEARCH_AND_LAYOUT.md",
|
|
47
51
|
"docs/SOURCE_AND_LABELS.md",
|
|
48
52
|
"docs/JAVA_THREAD_DUMPS.md",
|
|
53
|
+
"docs/JAVA_THREAD_DUMP_ZIP.md",
|
|
54
|
+
"docs/IMPORT_FORMATS.md",
|
|
55
|
+
"docs/PERF_IMPORT.md",
|
|
56
|
+
"docs/OTEL_PROFILES.md",
|
|
49
57
|
"docs/OFFLINE.md",
|
|
58
|
+
"docs/SINGLE_FILE.md",
|
|
59
|
+
"docs/PROPERTY_TESTS.md",
|
|
50
60
|
"bin/cli.mjs",
|
|
51
61
|
"bin/server.mjs",
|
|
52
62
|
"dist/release/**",
|
|
@@ -76,6 +86,7 @@
|
|
|
76
86
|
"eslint": "8.0.0",
|
|
77
87
|
"eslint-plugin-prettier": "5.1.2",
|
|
78
88
|
"eslint-plugin-react-hooks": "4.6.0",
|
|
89
|
+
"fast-check": "4.10.3",
|
|
79
90
|
"jest": "30.2.0",
|
|
80
91
|
"jest-environment-jsdom": "29.7.0",
|
|
81
92
|
"jfrview": "0.2.0",
|
|
@@ -120,6 +131,7 @@
|
|
|
120
131
|
]
|
|
121
132
|
},
|
|
122
133
|
"dependencies": {
|
|
123
|
-
"open": "10.1.0"
|
|
134
|
+
"open": "10.1.0",
|
|
135
|
+
"re2js": "2.10.0"
|
|
124
136
|
}
|
|
125
137
|
}
|