@node-projects/speedscope 2.0.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.
@@ -0,0 +1,58 @@
1
+ # Hosted offline use
2
+
3
+ The hosted HTTP build caches its application shell after a successful online
4
+ visit in a service-worker-capable secure browser. Once installation has finished,
5
+ the app's entry page can reopen without a network connection. Import a recording
6
+ from your computer again after reopening; an open recording remains in memory
7
+ when the network disconnects.
8
+
9
+ This caches application code, styles, fonts, icons and WebAssembly decoders only.
10
+ Imported recordings, remote `profileURL` responses, the CLI's local profile
11
+ endpoint, source maps supplied by users, the built-in example recording and
12
+ arbitrary network responses are not saved. A `profileURL` link can open the
13
+ offline app shell, but its remote recording still needs a network connection.
14
+ The built-in example also needs the network. Application caching is not a saved
15
+ recording feature.
16
+
17
+ Use the app's ordinary entry URL, such as `/speedscope/` or
18
+ `/speedscope/index.html`. Hash parameters are supported; query-string entry URLs
19
+ are not intercepted. Neither arbitrary paths within the scope nor cross-origin
20
+ URLs are intercepted. Explicit `no-store` requests and range requests bypass
21
+ the worker as well.
22
+
23
+ ## Updates
24
+
25
+ Shell revisions are derived from the generated HTML, immutable asset contents
26
+ and worker policy. An update is installed in the background and waits for all
27
+ tabs using the previous app version to close. Open recordings are not reloaded
28
+ or replaced automatically. Close all app tabs, then reopen the app to adopt a
29
+ waiting update. Offline reopening can continue to use the last installed shell
30
+ if no newer version has been downloaded.
31
+
32
+ Each application scope owns at most three shell generations: the active shell,
33
+ the previous waiting shell and the newest installation/waiting shell. One small
34
+ metadata cache holds only active/waiting cache names. A failed new install keeps
35
+ the active and previously waiting versions usable. Activation removes obsolete
36
+ owned shell caches; caches belonging to other apps/scopes are left untouched.
37
+ There is no runtime cache insertion. Builds reject more than 64 shell files or
38
+ more than 16 MiB of shell assets.
39
+
40
+ Browser storage restrictions, quota pressure or manually clearing site data can
41
+ remove the offline copy. The app continues to work online if registration or
42
+ installation is unavailable. The worker uses the browser's ordinary
43
+ [installation and waiting lifecycle](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)
44
+ without `skipWaiting`, `clients.claim` or forced reloads.
45
+
46
+ ## Build and local behavior
47
+
48
+ `npm run build:pages` emits the worker and hosted registration script.
49
+ `npm run prepack` retains the existing portable standalone ZIP behavior and
50
+ does not emit/register a service worker. The ordinary development server also
51
+ does not register one. File-protocol pages remain independent of service workers.
52
+
53
+ Localhost root pages are excluded to avoid controlling another local app or CLI
54
+ session. A deliberate hosted-build preview under a subdirectory such as
55
+ `http://127.0.0.1:PORT/app/` can register a worker limited to that directory.
56
+ For browser verification, complete an online visit there, stop the server, then
57
+ reload the same entry URL. Use a dedicated preview origin/port and clear its
58
+ site storage afterward if you no longer need the preview's offline shell.
@@ -0,0 +1,117 @@
1
+ # OpenTelemetry Profiles JSON
2
+
3
+ The importer accepts the lower-camel-case JSON representation of current
4
+ `opentelemetry.proto.profiles.v1development.ProfilesData` and
5
+ `collector.profiles.v1development.ExportProfilesServiceRequest`. Both have
6
+ `resourceProfiles` and one shared `dictionary`. This is **sampled stack data**,
7
+ not OpenTelemetry distributed traces (`resourceSpans`).
8
+
9
+ The supported schema is pinned to OpenTelemetry Proto commit
10
+ [`d31f7acf9d461fd0601077de516ac1eb7051422f`](https://github.com/open-telemetry/opentelemetry-proto/blob/d31f7acf9d461fd0601077de516ac1eb7051422f/opentelemetry/proto/profiles/v1development/profiles.proto),
11
+ OTLP Profiles **development version 1**. This development schema is unstable.
12
+ Older per-profile dictionaries, `ProfileContainer`, singular `sample`, repeated
13
+ `sampleType`, and future incompatible schemas are unsupported.
14
+
15
+ Development version normally belongs to OTLP transport metadata, not JSON.
16
+ The transport specification defaults absent metadata to version 1. A standalone
17
+ file can optionally advertise `developmentVersion: 1`; other advertised values
18
+ are rejected. This annotation is an importer extension, not a standard schema
19
+ field. Unversioned files must match the documented current dictionary layout;
20
+ the importer cannot identify future incompatible changes that retain that shape.
21
+
22
+ ## Dictionary and stacks
23
+
24
+ All seven tables must be present: `stringTable`, `mappingTable`, `locationTable`,
25
+ `functionTable`, `linkTable`, `attributeTable`, and `stackTable`. The official
26
+ schema requires a default-value entry at index zero even in unused tables.
27
+ Default fields inside these entries can be omitted. Link-zero trace/span IDs
28
+ may also be all-zero hexadecimal IDs. References are nonnegative in-range
29
+ int32 indices; zero represents an unset reference.
30
+
31
+ `stackTable[].locationIndices` and inline `locationTable[].lines` are leaf-first;
32
+ the viewer reverses both to retain the full caller/inline chain. Function names
33
+ fall back to system names. File, line and column identify symbolized frames.
34
+ Unsymbolized locations retain their binary filename and exact uint64 hexadecimal
35
+ address. Equal frame values merge independently of dictionary index.
36
+
37
+ Profile/sample `attributeIndices` resolve through `attributeTable`.
38
+ Resource/scope attributes accept direct keys or `keyStrindex`, and values accept
39
+ direct strings, `stringValueStrindex`, exact int64 integers and booleans. Complex
40
+ attributes are ignored for grouping. Duplicate attribute keys are rejected.
41
+ Sample `thread.id`/`thread.name` override profile attributes and create separate
42
+ thread profiles. Integer thread IDs remain exact decimal strings. Input profile
43
+ objects, resources and scopes remain separate even when names or IDs match;
44
+ labels include the service (or executable), scope, metric, profile ordinal and
45
+ thread. Generic attributes, scope versions, profile IDs and span links are not
46
+ preserved in viewer/export metadata. Links never become stack frames.
47
+
48
+ ## Values, units and time
49
+
50
+ Each sample needs `values`, `timestampsUnixNano`, or both. Both populated arrays
51
+ must have equal length. Values sum directly; timestamp-only observations each
52
+ contribute **one in the declared sample unit**, exactly as specified by OTLP.
53
+ `period` and `periodType` are informational and never multiply weights.
54
+
55
+ Supported units are `nanoseconds`/`ns`, `microseconds`/`us`/`µs`/`μs`,
56
+ `milliseconds`/`ms`, `seconds`/`s`, `bytes`/`By`, and raw counts
57
+ (`count`, `1`, `{count}`, or empty unit). Unknown units are rejected. Values are
58
+ not rescaled when selecting the formatter. Negative differential weights and
59
+ weights/totals exceeding JavaScript's exact integer range are rejected.
60
+
61
+ Profiles are imported as **aggregate**, with measured stack weights. Epoch
62
+ timestamps do not become a duration axis, and gaps do not generate idle stacks.
63
+ Timestamps and addresses use exact uint64 parsing; decimal strings are required
64
+ for values beyond JavaScript's safe integer range. Timestamp validation uses
65
+ the exact epoch. A nonzero profile duration requires samples within the declared
66
+ half-open time range; zero-duration instant profiles skip this range check.
67
+ Overflowing time ranges are rejected. Timestamps and period metadata are not
68
+ retained in exports.
69
+
70
+ ## Limits and remaining support
71
+
72
+ The JSON document is currently parsed in memory; this is not a streaming JSON or
73
+ protobuf importer. Import processing avoids an expanded observation/record array
74
+ and does not retain flattened copies of every dictionary stack. Memory consists
75
+ of the parsed JSON, output profiles, per-thread builder state and one stack.
76
+ Main-thread processing yields every 4,096 counted operations and checks
77
+ cancellation. The dedicated import worker explicitly disables these timer
78
+ yields, because cancelling the worker terminates its execution externally.
79
+ The worker keeps the same limits and weight checks. Main-thread fallback keeps
80
+ cooperative yielding, including when no cancellation signal was supplied; the
81
+ optimization never infers worker execution from the presence of a signal.
82
+
83
+ Limits are one million dictionary entries total; one million elements per input
84
+ array; 100,000 expanded frames per stack; 4,096 attributes per set; 4,096
85
+ output profiles; 4,096 characters per grouping attribute value; and ten million
86
+ counted hierarchy/sample/observation/location/inline operations. Limits fail
87
+ explicitly rather than silently dropping samples. The parsed JSON and output
88
+ itself still consume memory proportional to their size.
89
+
90
+ Binary OTLP protobuf, old development layouts, original payload decoding,
91
+ automatic network collection, and chronological OTLP visualization remain
92
+ unsupported. Binary protobuf has no unique identifying magic; the importer does
93
+ not guess it ahead of existing pprof detection. The synthetic fixture and its
94
+ provenance are in `sample/profiles/otel-profiles`.
95
+
96
+ ## Worker import performance check
97
+
98
+ On Windows on 2026-11-21, two fresh Node processes per case imported generated
99
+ current-schema JSON based on `synthetic.json`: its samples were replaced with
100
+ 100,000 or 1,000,000 distinct `{stackIndex: 1, values: [String(i % 3 + 1)]}`
101
+ objects. This exercises ordinary JSON detection and parsing, not a pre-parsed
102
+ importer call. The benchmark invoked `processTraceInWorker` directly, including
103
+ snapshot construction; it excludes browser worker startup and message transfer.
104
+ The before case restored timer yielding in the worker options only.
105
+
106
+ | Samples | JSON size | Main thread | Worker before | Worker without timer yields |
107
+ | --------- | --------- | ------------- | ------------- | --------------------------- |
108
+ | 100,000 | 3.05 MiB | 1.82–1.91 s | 1.94 s | 0.159–0.170 s |
109
+ | 1,000,000 | 30.52 MiB | 19.00–19.46 s | 19.51–19.75 s | 1.396–1.399 s |
110
+
111
+ The worker removes 122 and 1,220 timer waits respectively. Totals remained
112
+ 199,999 and 1,999,999 nanoseconds. Main-thread yielding remains enabled.
113
+ This is a timing optimization, not a new memory reduction: process high-water
114
+ RSS for the million-sample runs was 359–382 MiB before and 392–402 MiB after,
115
+ including fixture generation and all Node runtime allocations. Post-import
116
+ retained heap was comparable. There is no additional observation array or stack
117
+ cache; whole-document JSON parsing remains the dominant memory limitation.
@@ -0,0 +1,66 @@
1
+ # Linux perf imports and weight semantics
2
+
3
+ Import text from `perf script`. Include `comm`, thread/process identity, `time`,
4
+ `event`, `period`, `ip`, `sym` and `dso` fields when available. Regular callchains
5
+ and leaf-only `--hide-call-graph` output are supported. Keeping `period` is
6
+ important: timestamps alone do not measure a sampled function's CPU consumption.
7
+
8
+ ## Periods determine the weights
9
+
10
+ | Recorded event | Period present | Period absent |
11
+ | --- | --- | --- |
12
+ | `cpu-clock`, `task-clock` | Aggregate sampled CPU time, in nanoseconds | Legacy inferred timestamp timeline, explicitly labeled |
13
+ | `offcpu-time` | Aggregate sampled off-CPU time, in nanoseconds | Sample count, explicitly labeled |
14
+ | `cycles`, including hybrid CPU PMUs | Aggregate raw cycle periods | Legacy inferred timestamp timeline, explicitly labeled |
15
+ | Other hardware/software counters | Aggregate raw event periods | Sample count, explicitly labeled |
16
+
17
+ Event modifiers such as `:u` retain these rules. Hybrid `cpu_core/cycles/u` and
18
+ `cpu_atom/cycles/u` samples are combined under the normalized `cycles:u` event.
19
+ Different events, processes and threads remain separate. If some records have
20
+ periods while others omit them, their profiles remain separate too, so inferred
21
+ seconds, nanosecond periods and counts are never added together.
22
+
23
+ Period-weighted profiles use Left Heavy, Sandwich or Call Tree. Time Order is
24
+ disabled because accumulating sampled weights does not establish exact wall-time
25
+ intervals. Missing-period clock/cycle profiles retain the older timestamp
26
+ interpolation and are labeled **inferred timeline, period missing**. That view
27
+ assigns gaps between timestamps to adjacent stacks; do not interpret it as
28
+ measured CPU time or proof that a thread was running throughout those gaps.
29
+
30
+ Periods must be finite, non-negative integers within JavaScript's exact range
31
+ (`0` through `9007199254740991`). Larger individual periods fail with an
32
+ actionable error rather than being silently rounded. Totals still use the
33
+ project's ordinary floating-point weight model. Zero periods contribute zero
34
+ weight; they do not trigger timestamp inference or become a one-unit sample.
35
+
36
+ ## Why gaps are not CPU time
37
+
38
+ The public reproduction in [upstream #393](https://github.com/jlfwong/speedscope/issues/393#issuecomment-1200547074)
39
+ contains 13 samples for `DiscoveryClient` thread `2614953`, each with a
40
+ `cpu-clock` period of `20408163` nanoseconds. Its sampled CPU weight is therefore
41
+ `265306119` ns, about **0.265 seconds**, while its timestamps span about
42
+ **30.231 seconds**. The importer now uses the periods instead of attributing
43
+ those gaps to functions. A single clock sample also retains its real period
44
+ instead of becoming an arbitrary one-unit sample.
45
+
46
+ The checked-in [regression fixture](../sample/profiles/linux-perf/idle-clock-period.linux-perf.txt)
47
+ uses those timestamp/period facts with authored synthetic stacks. The source
48
+ archive was [profile.out.gz](https://github.com/jlfwong/speedscope/files/9230041/profile.out.gz),
49
+ 22,149 bytes, SHA-256
50
+ `40b9123046dc918018f40030426851d15622077843a8cd2923371750a6fa5efa`.
51
+
52
+ This fixes sampled aggregate attribution. Exact idle-gap placement and aligned
53
+ multithread timelines remain separate work: clock periods do not say exactly
54
+ when each fragment of CPU execution occurred within a timestamp gap. An
55
+ `offcpu-time` profile is kept separate and never added to CPU execution weights.
56
+ Scheduler-switch events and their associations need their own tested timeline
57
+ mapping; the importer does not invent those intervals.
58
+
59
+ ## Format references
60
+
61
+ Linux's [software-clock sampling implementation](https://github.com/torvalds/linux/blob/master/kernel/events/core.c)
62
+ initializes clock periods in nanoseconds and arms timers with
63
+ `ns_to_ktime(period)`. The kernel's [perf record documentation](https://github.com/torvalds/linux/blob/master/tools/perf/Documentation/perf-record.txt)
64
+ specifies that `--off-cpu` produces `offcpu-time` samples whose periods are sleep
65
+ time in nanoseconds. Other event periods remain counts in that event's own
66
+ units; cycle counts are not converted to seconds.
@@ -0,0 +1,50 @@
1
+ # pprof and signed heap deltas
2
+
3
+ Import binary protobuf pprof, including its usual gzip wrapper. The selected
4
+ metric is `default_sample_type`, or the last sample type when no usable default
5
+ is present. Positive-only recordings retain the ordinary single aggregate
6
+ profile. Time Order is unavailable: protobuf samples do not establish call order.
7
+
8
+ Go's `/debug/pprof/heap?seconds=N` can return a delta recording containing
9
+ negative values. Those values now import as two explicitly named profiles:
10
+
11
+ - **Negative contributions (magnitude; subtract)** contains the absolute values
12
+ of negative samples.
13
+ - **Positive contributions** contains positive samples.
14
+
15
+ These are signed contributions, not historical before/after heap snapshots.
16
+ Choose **Profile actions → Compare profiles…**, with negative contributions as
17
+ Baseline and positive contributions as Candidate, in **Absolute weights** mode.
18
+ Candidate minus baseline gives the net signed change for each call path. The
19
+ same-path contributions remain separate until comparison; cancellation to zero
20
+ does not discard either side. The graph's union widths represent gross
21
+ contribution magnitudes, not elapsed time or live-heap size. Normalized mode
22
+ instead compares relative composition and should not be read as net byte change.
23
+
24
+ For example, samples of -9, +12 and -2 bytes on one stack become 11 negative and
25
+ 12 positive bytes, yielding +1 net byte. All-negative recordings have an empty
26
+ positive side and remain comparable. Zero-valued samples have no width. Export
27
+ preserves both magnitude profiles in ordinary speedscope JSON; their names
28
+ describe the projection. Export does not recreate the original signed protobuf.
29
+
30
+ Selected sample values and the total on each side must fit exact JavaScript
31
+ integers (`Number.MAX_SAFE_INTEGER`). Larger values fail explicitly rather than
32
+ rounding or dropping negative values. This is not arbitrary-precision int64
33
+ support. Existing pprof limitations remain: only the selected metric is imported,
34
+ only the outermost inline location frame is retained, labels and mapping/address
35
+ metadata are not fully represented, and parsed input plus output trees scale
36
+ with capture size. Generic gzip decompression is not bounded by the text-stream
37
+ limits. This change does not make pprof streaming or out of core.
38
+
39
+ A local Go 1.24.1 `net/http/pprof` heap-delta check allocated then released 16 MiB
40
+ between collections. It imported 16,777,600 negative and 78,112 positive bytes,
41
+ giving -16,699,488 bytes net; browser comparison displayed -15.93 MiB. Allocation
42
+ overhead varies between runs. The ignored capture is an authored regression
43
+ observation, not the unavailable original upstream recording. Deterministic
44
+ checked-in tests cover both signs, same-path cancellation, all-negative values,
45
+ unit preservation, exact-range failures and export round trips.
46
+
47
+ - [Go HTTP pprof parameters](https://pkg.go.dev/net/http/pprof#hdr-Parameters)
48
+ define `seconds=N` delta recording behavior.
49
+ - [pprof protobuf schema](https://github.com/google/pprof/blob/main/proto/profile.proto)
50
+ defines sample type selection and signed int64 sample values.
@@ -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,73 @@
1
+ # Filter frames
2
+
3
+ Choose **Profile actions → Filter frames…** to create an aggregate view of your
4
+ code or hide framework frames. The original recording stays in the profile
5
+ selector. Select it to return to the complete profile. Filtering applies to the
6
+ active profile, and you can apply another filter to a derived profile.
7
+
8
+ Choose source file path, function name, or either. Enter one case-insensitive
9
+ literal substring per line. Slashes are interchangeable, so `src/app/` also
10
+ matches Windows paths. Multiple include rules are alternatives (OR); any exclude
11
+ match removes the frame, even if an include rule matches it. Leave include blank
12
+ to retain all frames except exclusions. Empty lines are ignored. File rules do
13
+ not match frames without a source path; use function names for those profiles.
14
+ Names match the displayed frame name, including any arguments that a trace
15
+ importer incorporates into it. There are no regular expressions or glob rules.
16
+
17
+ For example, include `src/` and exclude `node_modules/`. Or leave include empty
18
+ and exclude `vendor/` to remove framework frames while keeping unmapped code.
19
+ Up to 128 non-empty rules and 4,096 combined rule characters are accepted.
20
+
21
+ ## What the weights mean
22
+
23
+ This hides individual frames and joins their remaining ancestors/callees. It
24
+ does not discard an entire stack merely because it contains a hidden frame.
25
+ Each remaining stack retains its original weight. If a removed leaf has a kept
26
+ ancestor, its weight becomes self weight on the nearest kept ancestor. If no
27
+ frame remains in a stack, that stack's weight is omitted. Idle/empty-stack weight
28
+ is also omitted. Total/self values and percentages are recomputed from retained
29
+ stacks; they are not percentages of the unfiltered recording.
30
+
31
+ Suppose an 8 MiB allocation profile contains:
32
+
33
+ | Stack | Weight |
34
+ | --- | ---: |
35
+ | framework → render | 2 MiB |
36
+ | framework → render → vendorWork | 2 MiB |
37
+ | framework → helper | 2 MiB |
38
+ | framework | 2 MiB |
39
+
40
+ Including `src/` keeps render and helper, producing 6 MiB total. Render has
41
+ 4 MiB total and self: the hidden vendorWork leaf contributes to render's self
42
+ weight. Also excluding helper's file produces a 4 MiB profile containing render
43
+ alone. The original 8 MiB profile remains available.
44
+
45
+ ## Derived profile behavior
46
+
47
+ Filtered profiles are explicitly aggregate and derived. Time Order is disabled;
48
+ use Left Heavy, Sandwich or Call Tree. Existing Call Tree mode is preserved when
49
+ applying a filter. Filter rules are appended to the profile name, retaining a
50
+ visible history through further transformations and export/reimport. Exports
51
+ include both the original and filtered profiles, their units and aggregate flags.
52
+ “Combine original profiles” excludes derived profiles to avoid double counting.
53
+
54
+ No remaining frames is reported as an error without appending an empty profile.
55
+ Cancel or Escape discards unfinished work. Pasting rules stays inside the dialog
56
+ and does not invoke clipboard-profile import. Replacing the source recording
57
+ aborts/discards the pending result.
58
+
59
+ The implementation visits grouped call paths instead of every original trace
60
+ event, caches each frame's rule match, and yields between bounded batches of
61
+ traversal/stack work. Traversal and cancellation support a 20,000-frame deep-stack
62
+ regression without recursion. Final tree sorting remains synchronous, and the
63
+ original and derived models both occupy memory; this is not an out-of-core filter.
64
+ A local PLC smoke check filtered the selected profile from 16,231 frames to 40
65
+ in about 0.7 seconds, yielding 45 times. That is a single Node measurement, not a
66
+ general browser latency guarantee.
67
+
68
+ ## Memory-profile axes
69
+
70
+ Byte profiles now use power-of-two tick intervals in the main graph and minimap:
71
+ for example 512 KiB steps or whole MiB steps, rendered with the app's existing
72
+ KB/MB/GB labels. Other units retain decimal 1/2/5 spacing. Both axes adapt label
73
+ precision to zoom and skip overlapping labels.
@@ -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
@@ -34,9 +34,8 @@ gh workflow run pages.yml --repo node-projects/speedscope --ref main
34
34
 
35
35
  ## First publication: 2.0.0
36
36
 
37
- The first fork version is **2.0.0**, published manually by the maintainer. After
38
- the package has been prepared and checked, sign in to npm with an account allowed
39
- to publish under `@node-projects`, then run:
37
+ The first fork version, **2.0.0**, was published manually by the maintainer on
38
+ 2026-11-18. The bootstrap process was:
40
39
 
41
40
  ```sh
42
41
  npm ci
@@ -44,16 +43,18 @@ npm test
44
43
  npm publish --access public
45
44
  ```
46
45
 
47
- `prepack` builds the offline app automatically. This first publication does not
48
- require GitHub OIDC. Once it succeeds, configure the trusted publisher below.
46
+ `prepack` builds the offline app automatically. This first publication did not
47
+ require GitHub OIDC. The trusted publisher below is now configured.
49
48
  Creating a `v2.0.0` GitHub release afterward is safe: the workflow detects the
50
49
  existing npm version, attaches its standalone ZIP and skips re-publishing npm.
51
50
  For a new version, it attaches the newly built npm tarball as well.
52
51
 
53
52
  ## npm trusted publishing after the first publication
54
53
 
55
- The workflow is prepared for npm trusted publishing (OIDC), with Node.js 24 and
56
- `id-token: write`. Configure the package's trusted publisher on npm with:
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:
57
58
 
58
59
  - Organization/user: `node-projects`
59
60
  - Repository: `speedscope`
@@ -61,6 +62,47 @@ The workflow is prepared for npm trusted publishing (OIDC), with Node.js 24 and
61
62
  - Environment: leave empty (the npm job does not use an environment)
62
63
  - Allow the `npm publish` action.
63
64
 
65
+ The workflow already uses Node.js 24 and `id-token: write`, so future published
66
+ GitHub releases can authenticate through OIDC without an npm token secret.
67
+ The saved publisher also includes npm's default staging permission; the workflow
68
+ uses direct publication. No GitHub environment restriction is configured because
69
+ the publish job does not declare an environment.
70
+
71
+ To inspect the configuration, an authorized npm maintainer can run:
72
+
73
+ ```sh
74
+ npm trust list @node-projects/speedscope --json
75
+ ```
76
+
77
+ For recovery/recreation, npm 11.15+ supports the equivalent CLI setup:
78
+
79
+ ```sh
80
+ npm trust github @node-projects/speedscope --repository node-projects/speedscope --file release.yml --allow-publish
81
+ ```
82
+
83
+ npm requires fresh two-factor authentication for these account operations. The
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
87
+ release step.
88
+
89
+ New publisher configurations must complete their first successful automated
90
+ publish within **two days**, otherwise npm expires them. Creating a GitHub release
91
+ for an already-published version does not validate OIDC because this workflow
92
+ skips the npm publish step for that version. Use the next new version (for example
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.
105
+
64
106
  See [npm's trusted publisher setup](https://docs.npmjs.com/trusted-publishers/).
65
107
  The repository URL in package.json points to this fork, as required for provenance.
66
108
 
@@ -69,8 +111,8 @@ only be completed after the package exists and by an authorized npm maintainer.
69
111
  Keep the workflow filename and repository settings exact. Allow direct `npm publish`
70
112
  for this publisher. There is no npm credential included in this repository.
71
113
 
72
- The npm version badge and installation command become available after the first
73
- successful publication. Creating workflows alone does not register an npm package.
114
+ Version 2.0.0 is available from npm, and the README's npm badge and installation
115
+ command now refer to the published scoped package.
74
116
 
75
117
  ## Publish a release
76
118