profiler-md 0.7.0 → 0.8.1

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.
@@ -62,6 +62,14 @@ and reducing GC pressure.
62
62
  `bun --heap-prof` generates a V8 heap _snapshot_ on exit, not a heap _profile_.
63
63
  Deno has no equivalent.
64
64
 
65
+ The profiler reports only the sampled objects still alive when the profile is
66
+ written, so a workload that frees most of what it allocates leaves few samples.
67
+ `HeapProfiler.startSampling` takes `includeObjectsCollectedByMajorGC` and
68
+ `includeObjectsCollectedByMinorGC`, which keep the objects a major or a minor
69
+ garbage collection freed. Set both to profile allocation hot spots, and leave
70
+ them off to profile what stays in memory. `--heap-prof` sets neither and has no
71
+ flag for them, so use the programmatic API to set them.
72
+
65
73
  ### CLI
66
74
 
67
75
  ```sh
@@ -90,7 +98,11 @@ import { Session } from 'node:inspector/promises'
90
98
  const session = new Session()
91
99
  session.connect()
92
100
  await session.post(`HeapProfiler.enable`)
93
- await session.post(`HeapProfiler.startSampling`, { samplingInterval: 524_288 })
101
+ await session.post(`HeapProfiler.startSampling`, {
102
+ samplingInterval: 524_288,
103
+ includeObjectsCollectedByMajorGC: true,
104
+ includeObjectsCollectedByMinorGC: true,
105
+ })
94
106
 
95
107
  // Code to profile...
96
108
 
@@ -70,6 +70,17 @@ register_shutdown_function(function () use ($prof) {
70
70
  php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optimize
71
71
  ```
72
72
 
73
+ ## Output formats
74
+
75
+ `getSpeedscopeData()` writes the sampled time alongside each frame's file, and
76
+ `formatCollapsed()` writes sample counts with each frame's file packed into its
77
+ name. Prefer speedscope, because a collapsed frame names a method by its
78
+ declaring class rather than its file.
79
+
80
+ ```php
81
+ file_put_contents('wall.collapsed', $prof->getLog()->formatCollapsed());
82
+ ```
83
+
73
84
  ## API
74
85
 
75
86
  | Method | Description |
@@ -79,3 +90,4 @@ php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optim
79
90
  | `setMaxDepth($depth)` | Maximum stack frames per sample |
80
91
  | `start()` / `stop()` | Begin and end profiling |
81
92
  | `getLog()->getSpeedscopeData()` | The collected profile as Speedscope-format data |
93
+ | `getLog()->formatCollapsed()` | The collected profile as collapsed stacks |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "profiler-md",
3
- "version": "0.7.0",
3
+ "version": "0.8.1",
4
4
  "author": {
5
5
  "name": "Tomer Aberbach",
6
6
  "email": "tomer@aberba.ch",
package/readme.md CHANGED
@@ -224,8 +224,8 @@ Converts performance profiles to human and LLM friendly Markdown.
224
224
 
225
225
  Formats: callgrind, collapsed, ghc-eventlog, ghc-json-profile, hprof, jfr, jsc-heap-snapshot, memray, perf, pprof, speedscope, systing, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, webkit-timeline-recording
226
226
  Origins: async-profiler, bun, chrome, deno, dotnet-trace, eflambe, excimer, ghc, go, gperftools, jdk, memray, node, node-pprof, perf, pprof-jl, pprof-rs, profile-jl, py-spy, pyinstrument, rbspy, safari, simpleperf, systing, tachyon, unknown, valgrind
227
- Function categories (--category, --hide-category, --show-category): ours, third-party, stdlib, native, unknown, garbage collector, compiler, jit, regexp, kernel, idle
228
- Heap snapshot categories (--hide-category, --show-category): object, array, string, concatenated string, sliced string, function, code, regexp, number, big number, symbol, native, object shape, internal, synthetic, unknown
227
+ Function categories: ours, third-party, stdlib, native, unknown, garbage-collector, compiler, jit, regexp, kernel, idle
228
+ Heap snapshot categories: object, array, string, concatenated-string, sliced-string, function, code, regexp, number, big-number, symbol, native, object-shape, internal, synthetic, unknown
229
229
  Languages: c/cpp, csharp/fsharp, elixir/erlang, fortran, go, haskell, java/kotlin/groovy, javascript/typescript, julia, php, python, ruby, rust, swift, zig
230
230
  ```
231
231
 
@@ -314,7 +314,7 @@ and read it.
314
314
  <tr>
315
315
  <td><a href="docs/languages/go.md">Go</a></td>
316
316
  <td>
317
- <details><summary><a href="docs/formats/pprof.md">pprof</a></summary><ul><li>Go pprof block (<a href="examples/output/go.go.block.base.pprof.md">base</a>, <a href="examples/output/go.go.block.current.pprof.md">current</a>, <a href="examples/output/go.go.block.diff.pprof.md">diff</a>)</li><li>Go pprof CPU (<a href="examples/output/go.go.cpu.base.pprof.md">base</a>, <a href="examples/output/go.go.cpu.current.pprof.md">current</a>, <a href="examples/output/go.go.cpu.diff.pprof.md">diff</a>)</li><li>Go pprof goroutine (<a href="examples/output/go.go.goroutine.base.pprof.md">base</a>, <a href="examples/output/go.go.goroutine.current.pprof.md">current</a>, <a href="examples/output/go.go.goroutine.diff.pprof.md">diff</a>)</li><li>Go pprof goroutine leak (<a href="examples/output/go.go.goroutineleak.base.pprof.md">base</a>, <a href="examples/output/go.go.goroutineleak.current.pprof.md">current</a>, <a href="examples/output/go.go.goroutineleak.diff.pprof.md">diff</a>)</li><li>Go pprof heap (<a href="examples/output/go.go.heap.base.pprof.md">base</a>, <a href="examples/output/go.go.heap.current.pprof.md">current</a>, <a href="examples/output/go.go.heap.diff.pprof.md">diff</a>)</li><li>Go pprof heap-alloc (<a href="examples/output/go.go.heap-alloc.base.pprof.md">base</a>, <a href="examples/output/go.go.heap-alloc.current.pprof.md">current</a>, <a href="examples/output/go.go.heap-alloc.diff.pprof.md">diff</a>)</li><li>Go pprof mutex (<a href="examples/output/go.go.mutex.base.pprof.md">base</a>, <a href="examples/output/go.go.mutex.current.pprof.md">current</a>, <a href="examples/output/go.go.mutex.diff.pprof.md">diff</a>)</li><li>Go pprof threadcreate (<a href="examples/output/go.go.threadcreate.base.pprof.md">base</a>, <a href="examples/output/go.go.threadcreate.current.pprof.md">current</a>, <a href="examples/output/go.go.threadcreate.diff.pprof.md">diff</a>)</li></ul></details>
317
+ <details><summary><a href="docs/formats/pprof.md">pprof</a></summary><ul><li>Go pprof block (<a href="examples/output/go.go.block.base.pprof.md">base</a>, <a href="examples/output/go.go.block.current.pprof.md">current</a>, <a href="examples/output/go.go.block.diff.pprof.md">diff</a>)</li><li>Go pprof CPU (<a href="examples/output/go.go.cpu.base.pprof.md">base</a>, <a href="examples/output/go.go.cpu.current.pprof.md">current</a>, <a href="examples/output/go.go.cpu.diff.pprof.md">diff</a>)</li><li>Go pprof CPU (-trimpath) (<a href="examples/output/go.go.cpu-trimpath.base.pprof.md">base</a>, <a href="examples/output/go.go.cpu-trimpath.current.pprof.md">current</a>, <a href="examples/output/go.go.cpu-trimpath.diff.pprof.md">diff</a>)</li><li>Go pprof goroutine (<a href="examples/output/go.go.goroutine.base.pprof.md">base</a>, <a href="examples/output/go.go.goroutine.current.pprof.md">current</a>, <a href="examples/output/go.go.goroutine.diff.pprof.md">diff</a>)</li><li>Go pprof goroutine leak (<a href="examples/output/go.go.goroutineleak.base.pprof.md">base</a>, <a href="examples/output/go.go.goroutineleak.current.pprof.md">current</a>, <a href="examples/output/go.go.goroutineleak.diff.pprof.md">diff</a>)</li><li>Go pprof heap (<a href="examples/output/go.go.heap.base.pprof.md">base</a>, <a href="examples/output/go.go.heap.current.pprof.md">current</a>, <a href="examples/output/go.go.heap.diff.pprof.md">diff</a>)</li><li>Go pprof heap-alloc (<a href="examples/output/go.go.heap-alloc.base.pprof.md">base</a>, <a href="examples/output/go.go.heap-alloc.current.pprof.md">current</a>, <a href="examples/output/go.go.heap-alloc.diff.pprof.md">diff</a>)</li><li>Go pprof mutex (<a href="examples/output/go.go.mutex.base.pprof.md">base</a>, <a href="examples/output/go.go.mutex.current.pprof.md">current</a>, <a href="examples/output/go.go.mutex.diff.pprof.md">diff</a>)</li><li>Go pprof threadcreate (<a href="examples/output/go.go.threadcreate.base.pprof.md">base</a>, <a href="examples/output/go.go.threadcreate.current.pprof.md">current</a>, <a href="examples/output/go.go.threadcreate.diff.pprof.md">diff</a>)</li></ul></details>
318
318
  </td>
319
319
  </tr>
320
320
  <tr>
@@ -338,7 +338,7 @@ and read it.
338
338
  <details><summary><a href="docs/formats/jsc-heap-snapshot.md">JSC heap snapshot</a></summary><ul><li>JavaScript Bun (<a href="examples/output/javascript.bun.base.jsc-heap-snapshot.json.md">base</a>, <a href="examples/output/javascript.bun.current.jsc-heap-snapshot.json.md">current</a>, <a href="examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md">diff</a>)</li><li>JavaScript Safari (<a href="examples/output/javascript.safari.base.jsc-heap-snapshot.json.md">base</a>, <a href="examples/output/javascript.safari.current.jsc-heap-snapshot.json.md">current</a>, <a href="examples/output/javascript.safari.diff.jsc-heap-snapshot.json.md">diff</a>)</li></ul></details>
339
339
  <details><summary><a href="docs/formats/pprof.md">pprof</a></summary><ul><li>JavaScript node-pprof CPU (<a href="examples/output/javascript.node-pprof.cpu.base.pprof.md">base</a>, <a href="examples/output/javascript.node-pprof.cpu.current.pprof.md">current</a>, <a href="examples/output/javascript.node-pprof.cpu.diff.pprof.md">diff</a>)</li><li>JavaScript node-pprof heap (<a href="examples/output/javascript.node-pprof.heap.base.pprof.md">base</a>, <a href="examples/output/javascript.node-pprof.heap.current.pprof.md">current</a>, <a href="examples/output/javascript.node-pprof.heap.diff.pprof.md">diff</a>)</li></ul></details>
340
340
  <details><summary><a href="docs/formats/v8-cpu-profile.md">V8 CPU profile</a></summary><ul><li>JavaScript Bun (<a href="examples/output/javascript.bun.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.bun.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.bun.diff.cpuprofile.md">diff</a>)</li><li>JavaScript Chrome (<a href="examples/output/javascript.chrome.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.chrome.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.chrome.diff.cpuprofile.md">diff</a>)</li><li>JavaScript Deno (<a href="examples/output/javascript.deno.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.deno.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.deno.diff.cpuprofile.md">diff</a>)</li><li>JavaScript Node.js (<a href="examples/output/javascript.node.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.node.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.node.diff.cpuprofile.md">diff</a>)</li></ul></details>
341
- <details><summary><a href="docs/formats/v8-heap-profile.md">V8 heap profile</a></summary><ul><li>JavaScript Chrome (<a href="examples/output/javascript.chrome.base.heapprofile.md">base</a>, <a href="examples/output/javascript.chrome.current.heapprofile.md">current</a>, <a href="examples/output/javascript.chrome.diff.heapprofile.md">diff</a>)</li><li>JavaScript Node.js (<a href="examples/output/javascript.node.base.heapprofile.md">base</a>, <a href="examples/output/javascript.node.current.heapprofile.md">current</a>, <a href="examples/output/javascript.node.diff.heapprofile.md">diff</a>)</li></ul></details>
341
+ <details><summary><a href="docs/formats/v8-heap-profile.md">V8 heap profile</a></summary><ul><li>JavaScript Chrome (<a href="examples/output/javascript.chrome.base.heapprofile.md">base</a>, <a href="examples/output/javascript.chrome.current.heapprofile.md">current</a>, <a href="examples/output/javascript.chrome.diff.heapprofile.md">diff</a>)</li><li>JavaScript Node.js (<a href="examples/output/javascript.node.base.heapprofile.md">base</a>, <a href="examples/output/javascript.node.current.heapprofile.md">current</a>, <a href="examples/output/javascript.node.diff.heapprofile.md">diff</a>)</li><li>JavaScript Node.js all allocations (<a href="examples/output/javascript.node.all-allocations.base.heapprofile.md">base</a>, <a href="examples/output/javascript.node.all-allocations.current.heapprofile.md">current</a>, <a href="examples/output/javascript.node.all-allocations.diff.heapprofile.md">diff</a>)</li></ul></details>
342
342
  <details><summary><a href="docs/formats/v8-heap-snapshot.md">V8 heap snapshot</a></summary><ul><li>JavaScript Bun (<a href="examples/output/javascript.bun.base.heapsnapshot.md">base</a>, <a href="examples/output/javascript.bun.current.heapsnapshot.md">current</a>, <a href="examples/output/javascript.bun.diff.heapsnapshot.md">diff</a>)</li><li>JavaScript Chrome (<a href="examples/output/javascript.chrome.base.heapsnapshot.md">base</a>, <a href="examples/output/javascript.chrome.current.heapsnapshot.md">current</a>, <a href="examples/output/javascript.chrome.diff.heapsnapshot.md">diff</a>)</li><li>JavaScript Node.js (<a href="examples/output/javascript.node.base.heapsnapshot.md">base</a>, <a href="examples/output/javascript.node.current.heapsnapshot.md">current</a>, <a href="examples/output/javascript.node.diff.heapsnapshot.md">diff</a>)</li></ul></details>
343
343
  <details><summary><a href="docs/formats/webkit-timeline-recording.md">WebKit timeline recording</a></summary><ul><li>JavaScript Safari (<a href="examples/output/javascript.safari.base.webkit-timeline-recording.json.md">base</a>, <a href="examples/output/javascript.safari.current.webkit-timeline-recording.json.md">current</a>, <a href="examples/output/javascript.safari.diff.webkit-timeline-recording.json.md">diff</a>)</li></ul></details>
344
344
  </td>
@@ -353,6 +353,7 @@ and read it.
353
353
  <tr>
354
354
  <td><a href="docs/languages/php.md">PHP</a></td>
355
355
  <td>
356
+ <details><summary><a href="docs/formats/collapsed.md">Collapsed stacks</a></summary><ul><li>PHP Excimer wall (<a href="examples/output/php.excimer.wall.base.collapsed.md">base</a>, <a href="examples/output/php.excimer.wall.current.collapsed.md">current</a>, <a href="examples/output/php.excimer.wall.diff.collapsed.md">diff</a>)</li></ul></details>
356
357
  <details><summary><a href="docs/formats/speedscope.md">Speedscope</a></summary><ul><li>PHP Excimer wall (<a href="examples/output/php.excimer.wall.base.speedscope.json.md">base</a>, <a href="examples/output/php.excimer.wall.current.speedscope.json.md">current</a>, <a href="examples/output/php.excimer.wall.diff.speedscope.json.md">diff</a>)</li></ul></details>
357
358
  </td>
358
359
  </tr>