profiler-md 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/index.mjs +14155 -5081
- package/dist/index.d.mts +1312 -263
- package/dist/index.js +2 -2
- package/docs/api.md +138 -0
- package/docs/formats/callgrind.md +25 -0
- package/docs/formats/collapsed.md +5 -3
- package/docs/formats/ghc-eventlog.md +20 -0
- package/docs/formats/ghc-json-profile.md +23 -0
- package/docs/formats/hprof.md +21 -0
- package/docs/formats/jfr.md +3 -3
- package/docs/formats/jsc-heap-snapshot.md +11 -5
- package/docs/formats/memray.md +30 -0
- package/docs/formats/perf.md +74 -0
- package/docs/formats/pprof.md +10 -6
- package/docs/formats/speedscope.md +7 -5
- package/docs/formats/systing.md +27 -0
- package/docs/formats/v8-cpu-profile.md +4 -3
- package/docs/formats/v8-heap-profile.md +8 -5
- package/docs/formats/v8-heap-snapshot.md +10 -5
- package/docs/formats/webkit-timeline-recording.md +6 -0
- package/docs/languages/c.md +138 -18
- package/docs/languages/csharp.md +7 -7
- package/docs/languages/elixir.md +22 -15
- package/docs/languages/fortran.md +141 -0
- package/docs/languages/go.md +36 -13
- package/docs/languages/haskell.md +134 -0
- package/docs/languages/java.md +89 -34
- package/docs/languages/javascript.md +37 -31
- package/docs/languages/julia.md +96 -14
- package/docs/languages/php.md +10 -4
- package/docs/languages/python.md +121 -15
- package/docs/languages/ruby.md +19 -22
- package/docs/languages/rust.md +40 -10
- package/docs/languages/swift.md +135 -0
- package/docs/languages/zig.md +155 -0
- package/package.json +47 -46
- package/readme.md +306 -242
- package/skills/profile-optimize/SKILL.md +162 -0
- package/docs/languages/cpp.md +0 -160
- package/docs/languages/erlang.md +0 -46
- package/docs/languages/fsharp.md +0 -52
- package/docs/languages/kotlin.md +0 -170
- package/docs/languages/typescript.md +0 -276
- package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
- package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
- package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
- package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
- package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
- package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
- package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
- package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
- package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
- package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
- package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
- package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
- package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
- package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
- package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
- package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
- package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
- package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
- package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
- package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
- package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
- package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
- package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
- package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
- package/examples/output/go.pprof.block.base.pprof.md +0 -86
- package/examples/output/go.pprof.block.current.pprof.md +0 -83
- package/examples/output/go.pprof.block.diff.pprof.md +0 -42
- package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
- package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
- package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
- package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
- package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
- package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
- package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
- package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
- package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
- package/examples/output/go.pprof.heap.base.pprof.md +0 -154
- package/examples/output/go.pprof.heap.current.pprof.md +0 -146
- package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
- package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
- package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
- package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
- package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
- package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
- package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
- package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
- package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
- package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
- package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
- package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
- package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
- package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
- package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
- package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
- package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
- package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
- package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
- package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
- package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
- package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
- package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
- package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
- package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
- package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
- package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
- package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
- package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
- package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
- package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
- package/examples/output/java.jdk.all.base.jfr.md +0 -1024
- package/examples/output/java.jdk.all.current.jfr.md +0 -1010
- package/examples/output/java.jdk.all.diff.jfr.md +0 -311
- package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
- package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
- package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
- package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
- package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
- package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
- package/examples/output/java.jdk.live.base.jfr.md +0 -1029
- package/examples/output/java.jdk.live.current.jfr.md +0 -1035
- package/examples/output/java.jdk.live.diff.jfr.md +0 -289
- package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
- package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
- package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
- package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
- package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
- package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
- package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
- package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
- package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
- package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
- package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
- package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
- package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
- package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
- package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
- package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
- package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
- package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
- package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
- package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
- package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
- package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
- package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
- package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
- package/examples/output/javascript.node.base.cpuprofile.md +0 -136
- package/examples/output/javascript.node.base.heapprofile.md +0 -56
- package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
- package/examples/output/javascript.node.current.cpuprofile.md +0 -119
- package/examples/output/javascript.node.current.heapprofile.md +0 -52
- package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
- package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
- package/examples/output/javascript.node.diff.heapprofile.md +0 -34
- package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
- package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
- package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
- package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
- package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
- package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
- package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
- package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
- package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
- package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
- package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
- package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
- package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
- package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
- package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
- package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
- package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
- package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
- package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
- package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
- package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
- package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
- package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
- package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
- package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
- package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
- package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
- package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
- package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
- package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
- package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
- package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
- package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
- package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
- package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
- package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
- package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
- package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
- package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
- package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
- package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
- package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
- package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
- package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
- package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
- package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
- package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
- package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
- package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
- package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
- package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
- package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
- package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
- package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
- package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
- package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
- package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
- package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
- package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
- package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
- package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
- package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
- package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
- package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
- package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
- package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
- package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
- package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
- package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
- package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
- package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
- package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
- package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
- package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
- package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
- package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
- package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
- package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
- package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +0 -24
package/docs/api.md
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# API
|
|
2
|
+
|
|
3
|
+
The API accepts the same inputs and options as the CLI: pass a profile (or two,
|
|
4
|
+
to diff) and get Markdown back. Every function has a sync and an async variant.
|
|
5
|
+
The async variants accept a `Blob`, so large profiles stream instead of loading
|
|
6
|
+
into memory.
|
|
7
|
+
|
|
8
|
+
## Converting
|
|
9
|
+
|
|
10
|
+
The API auto-detects the format and origin by default:
|
|
11
|
+
|
|
12
|
+
```js
|
|
13
|
+
import { openAsBlob, readFileSync } from 'node:fs'
|
|
14
|
+
import { profileToMd, profileToMdAsync } from 'profiler-md'
|
|
15
|
+
|
|
16
|
+
// Async (streams the input)
|
|
17
|
+
console.log(await profileToMdAsync(await openAsBlob(`example.cpuprofile`)))
|
|
18
|
+
console.log(await profileToMdAsync(await openAsBlob(`example.pprof`)))
|
|
19
|
+
|
|
20
|
+
// Sync
|
|
21
|
+
console.log(profileToMd(readFileSync(`example.cpuprofile`, `utf8`)))
|
|
22
|
+
console.log(profileToMd(readFileSync(`example.pprof`)))
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Pass an object to specify the format or origin explicitly:
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
console.log(
|
|
29
|
+
await profileToMdAsync({
|
|
30
|
+
data: await openAsBlob(`example.pprof`),
|
|
31
|
+
format: `pprof`,
|
|
32
|
+
}),
|
|
33
|
+
)
|
|
34
|
+
console.log(
|
|
35
|
+
await profileToMdAsync({
|
|
36
|
+
data: await openAsBlob(`example.cpuprofile`),
|
|
37
|
+
origin: `deno`,
|
|
38
|
+
}),
|
|
39
|
+
)
|
|
40
|
+
console.log(
|
|
41
|
+
profileToMd({
|
|
42
|
+
data: readFileSync(`example.pprof`),
|
|
43
|
+
format: `pprof`,
|
|
44
|
+
origin: `node-pprof`,
|
|
45
|
+
}),
|
|
46
|
+
)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Diffing
|
|
50
|
+
|
|
51
|
+
Diff two profiles or two heap snapshots:
|
|
52
|
+
|
|
53
|
+
```js
|
|
54
|
+
import { openAsBlob, readFileSync } from 'node:fs'
|
|
55
|
+
import { diffProfiles, diffProfilesAsync } from 'profiler-md'
|
|
56
|
+
|
|
57
|
+
// Async, auto-detect
|
|
58
|
+
console.log(
|
|
59
|
+
await diffProfilesAsync(
|
|
60
|
+
await openAsBlob(`base.cpuprofile`),
|
|
61
|
+
await openAsBlob(`current.cpuprofile`),
|
|
62
|
+
),
|
|
63
|
+
)
|
|
64
|
+
console.log(
|
|
65
|
+
await diffProfilesAsync(
|
|
66
|
+
await openAsBlob(`base.heapsnapshot`),
|
|
67
|
+
await openAsBlob(`current.heapsnapshot`),
|
|
68
|
+
),
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
// Sync, explicit format
|
|
72
|
+
console.log(
|
|
73
|
+
diffProfiles(
|
|
74
|
+
{ data: readFileSync(`base.pprof`), format: `pprof` },
|
|
75
|
+
{ data: readFileSync(`current.pprof`), format: `pprof` },
|
|
76
|
+
),
|
|
77
|
+
)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Options
|
|
81
|
+
|
|
82
|
+
All functions take an options object as their last argument. The default for
|
|
83
|
+
each callback option is exported so a custom callback can build on it:
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
import { openAsBlob } from 'node:fs'
|
|
87
|
+
import {
|
|
88
|
+
defaultCategorizeFunctions,
|
|
89
|
+
defaultMatchEntry,
|
|
90
|
+
defaultShowEntry,
|
|
91
|
+
diffProfilesAsync,
|
|
92
|
+
profileToMdAsync,
|
|
93
|
+
} from 'profiler-md'
|
|
94
|
+
|
|
95
|
+
const options = {
|
|
96
|
+
// Show the top 10 functions of each ranking instead of the default 20.
|
|
97
|
+
topN: 10,
|
|
98
|
+
// Break a ranking down by category, one subsection per category accounting
|
|
99
|
+
// for at least 5% of the shown functions instead of the default 1%. Pass 0 to
|
|
100
|
+
// break down every category.
|
|
101
|
+
minCategoryShare: 0.05,
|
|
102
|
+
// Make paths relative to a custom base URL or directory, or pass `auto` to
|
|
103
|
+
// infer the profiled files' common ancestor directory.
|
|
104
|
+
baseURL: `/path/to/project`,
|
|
105
|
+
matchEntry: (entry, context) => {
|
|
106
|
+
if (entry.location?.url?.pathname.includes(`/bundle.`)) {
|
|
107
|
+
// Match bundled entries when diffing by name only, ignoring
|
|
108
|
+
// content-hashed filenames.
|
|
109
|
+
return { name: entry.name }
|
|
110
|
+
}
|
|
111
|
+
return defaultMatchEntry(entry, context)
|
|
112
|
+
},
|
|
113
|
+
categorizeFunctions: (entries, context) => {
|
|
114
|
+
const categories = defaultCategorizeFunctions(entries, context)
|
|
115
|
+
return entries.map((entry, index) =>
|
|
116
|
+
// Treat an additional vendor directory as third-party.
|
|
117
|
+
entry.location?.url?.pathname.includes(`/vendor/`)
|
|
118
|
+
? `third-party`
|
|
119
|
+
: categories[index],
|
|
120
|
+
)
|
|
121
|
+
},
|
|
122
|
+
showEntry: entry =>
|
|
123
|
+
defaultShowEntry(entry) &&
|
|
124
|
+
// Exclude entries from a specific file.
|
|
125
|
+
!entry.location?.url?.pathname.includes(`/path/to/project/src/noisy`),
|
|
126
|
+
}
|
|
127
|
+
console.log(await profileToMdAsync(await openAsBlob(`example.pprof`), options))
|
|
128
|
+
|
|
129
|
+
// The same options apply to diffs. `matchEntry` takes effect only here, where
|
|
130
|
+
// it controls which entries count as the same across the two sides.
|
|
131
|
+
console.log(
|
|
132
|
+
await diffProfilesAsync(
|
|
133
|
+
await openAsBlob(`base.pprof`),
|
|
134
|
+
await openAsBlob(`current.pprof`),
|
|
135
|
+
options,
|
|
136
|
+
),
|
|
137
|
+
)
|
|
138
|
+
```
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Callgrind
|
|
2
|
+
|
|
3
|
+
Callgrind is the plain-text call graph profiling format written by
|
|
4
|
+
[Valgrind](https://valgrind.org)'s
|
|
5
|
+
[Callgrind](https://valgrind.org/docs/manual/cl-manual.html) tool.
|
|
6
|
+
`callgrind_annotate` and KCachegrind/QCachegrind read it, and other profilers
|
|
7
|
+
(e.g. rbspy, R's proftools) emit it too.
|
|
8
|
+
|
|
9
|
+
A header declares the cost events (`events:`, e.g. `Ir` for instructions
|
|
10
|
+
executed) and position columns (`positions:`). The body attributes per-line
|
|
11
|
+
costs to functions (`fl=`/`fn=` specs followed by cost lines) and records each
|
|
12
|
+
call's count and inclusive cost (`cfn=`/`calls=`).
|
|
13
|
+
|
|
14
|
+
It stores a weighted call graph instead of call stacks, so the output shows
|
|
15
|
+
per-function and per-line self costs plus each function's callers and callees
|
|
16
|
+
with their recorded call counts and inclusive costs. A function's total is its
|
|
17
|
+
self cost plus its outgoing calls' inclusive costs. It excludes the calls within
|
|
18
|
+
a recursion cycle, which re-count the same work. Those calls still appear as
|
|
19
|
+
callers and callees, so their percentages can exceed 100%.
|
|
20
|
+
|
|
21
|
+
It supports arbitrary metric units, multiple metrics per call graph, and a
|
|
22
|
+
single call graph per file.
|
|
23
|
+
|
|
24
|
+
Files have no standard extension. `callgrind.out.<pid>` and `.callgrind` are
|
|
25
|
+
common.
|
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
# Collapsed stacks
|
|
2
2
|
|
|
3
3
|
Collapsed stacks is the plain-text interchange format from Brendan Gregg's
|
|
4
|
-
[FlameGraph](https://github.com/brendangregg/FlameGraph) tooling.
|
|
5
|
-
|
|
4
|
+
[FlameGraph](https://github.com/brendangregg/FlameGraph) tooling. Many profilers
|
|
5
|
+
emit it.
|
|
6
6
|
|
|
7
7
|
Each line is one call stack, written root-to-leaf and joined by `;`, followed by
|
|
8
8
|
a space and an integer sample count. Frames are opaque strings and carry no
|
|
9
9
|
units.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
It supports no metrics and a single profile per file.
|
|
12
|
+
|
|
13
|
+
Files have no standard extension. `.collapsed`, `.folded`, and `.txt` are
|
|
12
14
|
common.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# GHC eventlog
|
|
2
|
+
|
|
3
|
+
The binary event stream
|
|
4
|
+
[GHC](https://downloads.haskell.org/ghc/latest/docs/users_guide/eventlog-formats.html)'s
|
|
5
|
+
runtime writes for a program run with `+RTS -l`, recording what the runtime did
|
|
6
|
+
and when: garbage collections and thread scheduling. A program compiled with
|
|
7
|
+
`-prof` and run with `+RTS -p` adds one cost-centre sample per tick.
|
|
8
|
+
|
|
9
|
+
A log opens with a header declaring every event type the runtime can write, each
|
|
10
|
+
with its payload size. The events follow, in the order they happened: the
|
|
11
|
+
cost-centre definitions the runtime writes at startup, then the samples
|
|
12
|
+
referencing them.
|
|
13
|
+
|
|
14
|
+
The samples are the cost-centre stacks the profiler observed, so the log
|
|
15
|
+
converts to the time profile they record. It omits the allocation totals the
|
|
16
|
+
JSON report contains.
|
|
17
|
+
|
|
18
|
+
It supports a single metric per profile and a single profile per file.
|
|
19
|
+
|
|
20
|
+
Files use the `.eventlog` extension.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# GHC JSON profile
|
|
2
|
+
|
|
3
|
+
The GHC JSON profile is the machine-readable report
|
|
4
|
+
[GHC](https://downloads.haskell.org/ghc/latest/docs/users_guide/profiling.html)'s
|
|
5
|
+
runtime writes for a program compiled with `-prof` and run with `+RTS -pj`. It
|
|
6
|
+
contains the same measurements as the text report `+RTS -p` writes.
|
|
7
|
+
|
|
8
|
+
The report is a table of the program's cost centres, each a binding GHC
|
|
9
|
+
annotated, and a tree of cost-centre stacks. A node contains the costs of that
|
|
10
|
+
stack alone, excluding the stacks extending it: the ticks the profiler sampled,
|
|
11
|
+
the bytes the program allocated, and the times it entered the stack.
|
|
12
|
+
|
|
13
|
+
Ticks and allocation are measured differently, so each converts to its own
|
|
14
|
+
profile. A tick is one sample of the time profile, taken every millisecond by
|
|
15
|
+
default. The tick timer samples every capability whether or not it is running
|
|
16
|
+
Haskell, so the time profile measures wall time and attributes the idle ticks to
|
|
17
|
+
the built-in `IDLE` cost centre. The runtime counts bytes and entries exactly
|
|
18
|
+
and independently, so the allocation profile reports both as measured quantities
|
|
19
|
+
and states no rate.
|
|
20
|
+
|
|
21
|
+
It supports multiple metrics per profile and a single report per file.
|
|
22
|
+
|
|
23
|
+
Files use the `.prof` extension, named after the program as `<program>.prof`.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# HPROF
|
|
2
|
+
|
|
3
|
+
[HPROF](https://github.com/openjdk/jdk/blob/master/src/hotspot/share/services/heapDumper.cpp)
|
|
4
|
+
is the JVM's binary heap dump format, written by HotSpot's own heap dumper
|
|
5
|
+
behind `jmap -dump`, `jcmd GC.heap_dump`, `HotSpotDiagnosticMXBean.dumpHeap`,
|
|
6
|
+
and `-XX:+HeapDumpOnOutOfMemoryError`.
|
|
7
|
+
|
|
8
|
+
A dump begins with a format name (`JAVA PROFILE 1.0.2`), an identifier size, and
|
|
9
|
+
a timestamp, followed by tagged records: the runtime's symbols, the classes it
|
|
10
|
+
loaded, and heap dump segments holding a record per class, instance, and array,
|
|
11
|
+
plus the GC roots the live objects are reachable from.
|
|
12
|
+
|
|
13
|
+
It captures the object graph at a single point in time, so it shows what the
|
|
14
|
+
heap holds rather than where allocation happens. Sizes are the bytes the dump
|
|
15
|
+
records for each object. The dump omits object headers, so a class's instances
|
|
16
|
+
measure smaller here than the memory they occupy.
|
|
17
|
+
|
|
18
|
+
Android's ART writes a dialect of the format with records of its own, which this
|
|
19
|
+
tool doesn't read.
|
|
20
|
+
|
|
21
|
+
Files use the `.hprof` extension.
|
package/docs/formats/jfr.md
CHANGED
|
@@ -8,9 +8,9 @@ binary profiling format, written by the JDK's built-in
|
|
|
8
8
|
A recording splits into self-contained chunks of LEB128 varint-encoded events.
|
|
9
9
|
One recording can mix event kinds, so it converts to one profile per kind:
|
|
10
10
|
CPU/wall sampling measured by sample count, heap and native memory allocation
|
|
11
|
-
sampling measured by allocated bytes,
|
|
12
|
-
time.
|
|
11
|
+
sampling measured by allocated bytes, live-object sampling measured by retained
|
|
12
|
+
bytes, and lock contention measured by blocked time.
|
|
13
13
|
|
|
14
|
-
It supports
|
|
14
|
+
It supports a single metric per profile and multiple profiles per file.
|
|
15
15
|
|
|
16
16
|
Files use the `.jfr` extension.
|
|
@@ -2,12 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
The
|
|
4
4
|
[JSC heap snapshot](https://webkit.org/blog/6425/memory-debugging-with-web-inspector)
|
|
5
|
-
is a JSON format produced by JavaScriptCore, the engine
|
|
5
|
+
is a JSON format produced by JavaScriptCore, the JavaScript engine of Safari and
|
|
6
6
|
WebKit, that captures the full live object graph at a point in time.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
8
|
+
A snapshot is a flat integer array of node records (an id, a self size, a class
|
|
9
|
+
name, and flags marking VM-internal instances) and a flat integer array of edge
|
|
10
|
+
records (the two nodes it connects, a type, and a name), alongside the string
|
|
11
|
+
tables the class and edge names index into.
|
|
12
|
+
|
|
13
|
+
Snapshots show what objects exist in memory, unlike heap profiles, which sample
|
|
14
|
+
allocations. That makes them useful for diagnosing memory leaks rather than
|
|
15
|
+
allocation hotspots.
|
|
11
16
|
|
|
12
17
|
Files use the `.json` extension and contain `"type": "Inspector"` and a
|
|
13
|
-
`"version"
|
|
18
|
+
`"version"`: `3` in current WebKit and in Bun's `generateHeapSnapshot("jsc")`,
|
|
19
|
+
and `2` in the older Safari releases that wrote the previous revision.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# memray
|
|
2
|
+
|
|
3
|
+
The capture file [memray](https://github.com/bloomberg/memray), Bloomberg's
|
|
4
|
+
Python memory profiler, writes for its own reporters to read.
|
|
5
|
+
|
|
6
|
+
A capture is a binary stream of records describing a program's allocations: the
|
|
7
|
+
code objects its functions belong to, each thread's frame pushes and pops, and
|
|
8
|
+
every allocation and deallocation with its address, size, and allocator. A
|
|
9
|
+
capture written with `--aggregate` states each stack's peak and leaked totals
|
|
10
|
+
instead of every allocation. `memray run` compresses either one with LZ4, which
|
|
11
|
+
this tool decompresses itself.
|
|
12
|
+
|
|
13
|
+
A capture contains no totals, so both measures come from replaying the stream:
|
|
14
|
+
peak memory from the allocations live at the moment total memory was highest,
|
|
15
|
+
and leaked memory from those still live at the end. `memray flamegraph` and
|
|
16
|
+
`memray flamegraph --leaks` report those measures. The measures count different
|
|
17
|
+
allocations, so a capture converts to a profile each. Because memray records
|
|
18
|
+
every allocation, the output states bytes per allocation rather than a sampling
|
|
19
|
+
rate.
|
|
20
|
+
|
|
21
|
+
This tool skips native frames, recorded by `memray run --native`, because
|
|
22
|
+
resolving them means symbolizing instruction pointers against the binaries the
|
|
23
|
+
traced process ran. A capture recorded with them still converts, showing its
|
|
24
|
+
Python frames.
|
|
25
|
+
|
|
26
|
+
It supports a single byte metric per profile and multiple profiles per file.
|
|
27
|
+
|
|
28
|
+
Files use the `.bin` extension. This tool reads capture versions 12 and 13,
|
|
29
|
+
written by memray 1.19 and 1.20. In version 13 the header ends with the traced
|
|
30
|
+
process's module search paths, and the records are encoded as in version 12.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# perf.data
|
|
2
|
+
|
|
3
|
+
The binary file [Linux `perf`](https://perfwiki.github.io/main/) writes: the
|
|
4
|
+
on-disk form of the kernel's own `perf_event` records, specified by the kernel's
|
|
5
|
+
[`perf.data` file format documentation](https://github.com/torvalds/linux/blob/master/tools/perf/Documentation/perf.data-file-format.txt)
|
|
6
|
+
and
|
|
7
|
+
[`perf_event.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/perf_event.h).
|
|
8
|
+
Android's
|
|
9
|
+
[simpleperf](https://android.googlesource.com/platform/system/extras/+/refs/heads/main/simpleperf/doc/README.md)
|
|
10
|
+
records the same layout, with extra feature sections of its own.
|
|
11
|
+
|
|
12
|
+
A header names the recorded events and how they were sampled, a data section
|
|
13
|
+
holds the records the kernel produced (samples carrying an instruction pointer,
|
|
14
|
+
a call chain, a thread, and how many event units the sample stands for, plus the
|
|
15
|
+
memory mappings each process made), and feature sections hold the metadata
|
|
16
|
+
`perf` collected about the machine.
|
|
17
|
+
|
|
18
|
+
Each recorded event becomes its own profile, measured in the units its period
|
|
19
|
+
counts: nanoseconds for the `cpu-clock` and `task-clock` software events, and
|
|
20
|
+
the counted event otherwise (cycles, instructions, page faults).
|
|
21
|
+
|
|
22
|
+
It supports a single metric per profile and multiple profiles per file.
|
|
23
|
+
|
|
24
|
+
Files use the `perf.data` name and extension, optionally gzipped as
|
|
25
|
+
`perf.data.gz`.
|
|
26
|
+
|
|
27
|
+
## Addresses instead of function names
|
|
28
|
+
|
|
29
|
+
A `perf.data` file holds no symbol tables. `perf report` reads the recorded
|
|
30
|
+
program and its shared libraries off the machine that recorded them, so a file
|
|
31
|
+
alone resolves an address no further than the mapped file it fell in. Every
|
|
32
|
+
frame is therefore one address, named by its offset into that file and located
|
|
33
|
+
at the file's path, the same form `perf script` prints for a frame it cannot
|
|
34
|
+
symbolize. An address in memory a program obtained without a file (an `//anon`
|
|
35
|
+
mapping) is located at that name and categorized as JIT code.
|
|
36
|
+
|
|
37
|
+
Resolve an offset against the same build with `addr2line`:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
addr2line -fCe ./program 0x5f800
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The offset is file-relative rather than the address the code ran at, so it is
|
|
44
|
+
the same across runs of the same build, and a diff of two recordings pairs the
|
|
45
|
+
addresses that moved. A kernel frame's offset is from the start of the kernel's
|
|
46
|
+
text (`_text`), which the kernel randomizes on every boot, so it too pairs
|
|
47
|
+
across boots. Resolve one against the matching `vmlinux` by adding the address
|
|
48
|
+
of `_text` from its `System.map`, or from `/proc/kallsyms` on the recording
|
|
49
|
+
machine.
|
|
50
|
+
|
|
51
|
+
For function names in the output, symbolize while converting instead: pipe
|
|
52
|
+
`perf script` through FlameGraph's `stackcollapse-perf.pl` and pass the
|
|
53
|
+
collapsed stacks, which this tool also reads.
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
perf script -i perf.data | stackcollapse-perf.pl > profile.collapsed
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Recordings this tool reads
|
|
60
|
+
|
|
61
|
+
Record with `perf record -g`, which `profiler-md --help c` and
|
|
62
|
+
`profiler-md --help zig` cover. This tool reads only the call chains the kernel
|
|
63
|
+
walked, so it rejects a file recorded with `--call-graph dwarf`. That option
|
|
64
|
+
leaves the chain holding one user-space frame and copies the rest of the stack
|
|
65
|
+
into every sample for `perf report` to unwind. This tool also leaves
|
|
66
|
+
`--call-graph lbr` branch histories unread. simpleperf's `record -g` unwinds
|
|
67
|
+
that copy while recording and writes the frames into the chain, so this tool
|
|
68
|
+
reads its files. On arm64, `perf report` adds one caller below the innermost
|
|
69
|
+
frame by unwinding the sampled link register, so a stack there can name a caller
|
|
70
|
+
this tool leaves out.
|
|
71
|
+
|
|
72
|
+
It also rejects, with the reason, a file recorded with `perf record -z`
|
|
73
|
+
(compressed), streamed to a pipe (`perf record -o -`), or written on a machine
|
|
74
|
+
of the opposite byte order.
|
package/docs/formats/pprof.md
CHANGED
|
@@ -1,12 +1,16 @@
|
|
|
1
1
|
# pprof
|
|
2
2
|
|
|
3
3
|
[pprof](https://github.com/google/pprof) is a binary
|
|
4
|
-
([protobuf](https://github.com/protocolbuffers/protobuf))
|
|
5
|
-
|
|
6
|
-
|
|
4
|
+
([protobuf](https://github.com/protocolbuffers/protobuf)) sample-based profiling
|
|
5
|
+
format originally from Google. It is the de facto standard cross-language
|
|
6
|
+
profiling format.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
8
|
+
Locations support inlined call frames, meaning a single instruction address can
|
|
9
|
+
correspond to multiple logical stack frames.
|
|
10
|
+
|
|
11
|
+
It supports arbitrary metric units, multiple metrics per profile, and multiple
|
|
12
|
+
profiles per file. A file containing several counts (a heap profile's
|
|
13
|
+
`alloc_objects` and `inuse_objects`) becomes one profile per count, each
|
|
14
|
+
reporting the metrics measured over it.
|
|
11
15
|
|
|
12
16
|
Files are commonly gzip-compressed (extension `.pb.gz`).
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
# Speedscope
|
|
2
2
|
|
|
3
3
|
Speedscope is a JSON profiling format used by
|
|
4
|
-
[speedscope.app](https://www.speedscope.app), a flame graph visualizer.
|
|
5
|
-
profile within a file has a type: `sampled` (call stacks at points in time) or
|
|
6
|
-
`evented` (frame open/close timestamps).
|
|
4
|
+
[speedscope.app](https://www.speedscope.app), a flame graph visualizer.
|
|
7
5
|
|
|
8
|
-
|
|
9
|
-
|
|
6
|
+
Each profile within a file has a type: `sampled` (call stacks at points in time)
|
|
7
|
+
or `evented` (frame open/close timestamps).
|
|
8
|
+
|
|
9
|
+
It supports one metric per profile, measured in one of six units (nanoseconds,
|
|
10
|
+
microseconds, milliseconds, seconds, bytes, or none), and multiple profiles per
|
|
11
|
+
file.
|
|
10
12
|
|
|
11
13
|
Files use the `.speedscope.json` extension.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# systing profile export
|
|
2
|
+
|
|
3
|
+
The line-oriented profile export written by
|
|
4
|
+
[systing](https://github.com/josefbacik/systing), a Linux eBPF system profiler,
|
|
5
|
+
specified by its
|
|
6
|
+
[`docs/PROFILE_EXPORT_FORMAT.md`](https://github.com/josefbacik/systing/blob/main/docs/PROFILE_EXPORT_FORMAT.md).
|
|
7
|
+
`systing-util convert trace.duckdb --output profile.systing` writes one from an
|
|
8
|
+
existing trace database.
|
|
9
|
+
|
|
10
|
+
An export opens with a JSON header line describing the recording (sampling event
|
|
11
|
+
and period, event-type legend, system info), followed by one JSON array per
|
|
12
|
+
record: interned frames, interned leaf-first stacks, and per-thread sample
|
|
13
|
+
counts. Frames mix kernel, native user, and Python code, marked by systing's own
|
|
14
|
+
labels (`[kernel]`, `[gvisor:*]`, `[jit:*]`). The labels determine
|
|
15
|
+
categorization.
|
|
16
|
+
|
|
17
|
+
A recording samples on-CPU execution and takes a stack each time a thread
|
|
18
|
+
sleeps, so it converts to up to three profiles: CPU (measured in time for
|
|
19
|
+
`cpu-clock` sampling, cycles for `cpu-cycles`), uninterruptible sleep, and
|
|
20
|
+
interruptible sleep (both measured in sleep occurrences). Sleep stacks are taken
|
|
21
|
+
at the context switch, so they always end in the kernel's scheduler internals:
|
|
22
|
+
self costs fall on scheduler frames, and the total costs show which callers
|
|
23
|
+
slept.
|
|
24
|
+
|
|
25
|
+
It supports a single metric per profile and multiple profiles per file.
|
|
26
|
+
|
|
27
|
+
Files use the `.systing` extension, optionally gzipped as `.systing.gz`.
|
|
@@ -3,9 +3,10 @@
|
|
|
3
3
|
The V8 CPU profile is a JSON format produced by the
|
|
4
4
|
[V8 JavaScript engine's sampling profiler](https://v8.dev/docs/profile).
|
|
5
5
|
|
|
6
|
-
It stores
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
It stores a call tree (nodes) and the sequence of samples taken from it, each
|
|
7
|
+
sample with the microseconds elapsed since the one before it. A profile
|
|
8
|
+
therefore states how long every sample stood for, rather than leaving its reader
|
|
9
|
+
to derive that from a nominal sampling rate.
|
|
9
10
|
|
|
10
11
|
It supports a single microsecond metric per profile and a single profile per
|
|
11
12
|
file.
|
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
# V8 heap profile
|
|
2
2
|
|
|
3
3
|
The V8 heap profile is a JSON format produced by
|
|
4
|
-
[V8's sampling heap profiler](https://v8.dev/docs/profile).
|
|
5
|
-
|
|
4
|
+
[V8's sampling heap profiler](https://v8.dev/docs/profile). Node.js and Chrome
|
|
5
|
+
DevTools generate it.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
It stores an allocation call tree whose nodes each state the bytes allocated at
|
|
8
|
+
that call site, and a sequence of samples referencing those nodes.
|
|
9
|
+
|
|
10
|
+
Heap profiles sample allocations, unlike heap snapshots, which capture all live
|
|
11
|
+
objects at a point in time. That makes them useful for finding allocation
|
|
12
|
+
hotspots rather than diagnosing what is live in memory.
|
|
10
13
|
|
|
11
14
|
It supports a single byte metric per profile and a single profile per file.
|
|
12
15
|
|
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
# V8 heap snapshot
|
|
2
2
|
|
|
3
|
-
The V8 heap snapshot is a JSON format
|
|
4
|
-
at a point in time.
|
|
3
|
+
The V8 heap snapshot is a JSON format produced by the V8 JavaScript engine's
|
|
4
|
+
heap profiler that captures the full live object graph at a point in time.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
A snapshot is a `meta` object declaring the layout of the records that follow,
|
|
7
|
+
flat integer arrays of node and edge records, a strings table the node and edge
|
|
8
|
+
names index into, and a flat array of the source locations of the functions and
|
|
9
|
+
objects the nodes stand for.
|
|
10
|
+
|
|
11
|
+
Snapshots show what objects exist in memory, unlike heap profiles, which sample
|
|
12
|
+
allocations. That makes them useful for diagnosing memory leaks rather than
|
|
13
|
+
allocation hotspots.
|
|
9
14
|
|
|
10
15
|
Files use the `.heapsnapshot` extension.
|
|
@@ -6,4 +6,10 @@ from sampling, a browser activity breakdown (layout, rendering, script
|
|
|
6
6
|
execution, network requests), and optionally in-use memory readings and heap
|
|
7
7
|
allocation snapshots when those instruments are enabled.
|
|
8
8
|
|
|
9
|
+
The recording holds the sampled call stacks alongside the duration each sample
|
|
10
|
+
spans, so it converts to the time profile they record. This tool leaves the
|
|
11
|
+
activity breakdown and the memory readings unread.
|
|
12
|
+
|
|
13
|
+
It supports a single second metric per profile and a single profile per file.
|
|
14
|
+
|
|
9
15
|
Files use the `.json` extension.
|