profiler-md 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/dist/cli/index.mjs +2787 -1669
  2. package/dist/index.d.mts +249 -78
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/formats/jsc-heap-snapshot.md +13 -0
  6. package/docs/formats/webkit-timeline-recording.md +9 -0
  7. package/docs/languages/c.md +1 -1
  8. package/docs/languages/cpp.md +136 -0
  9. package/docs/languages/csharp.md +49 -0
  10. package/docs/languages/elixir.md +42 -0
  11. package/docs/languages/erlang.md +42 -0
  12. package/docs/languages/fsharp.md +49 -0
  13. package/docs/languages/go.md +2 -2
  14. package/docs/languages/java.md +10 -7
  15. package/docs/languages/javascript.md +69 -0
  16. package/docs/languages/julia.md +42 -0
  17. package/docs/languages/kotlin.md +120 -0
  18. package/docs/languages/python.md +10 -4
  19. package/docs/languages/typescript.md +254 -0
  20. package/examples/bun.cpuprofile.md +94 -116
  21. package/examples/deno.cpuprofile.md +11 -18
  22. package/examples/jsc-heap-snapshot.base.json.md +507 -0
  23. package/examples/jsc-heap-snapshot.current.json.md +504 -0
  24. package/examples/jsc-heap-snapshot.diff.json.md +119 -0
  25. package/examples/node.base.cpuprofile.md +451 -0
  26. package/examples/node.current.cpuprofile.md +449 -0
  27. package/examples/node.diff.cpuprofile.md +82 -0
  28. package/examples/node.heapprofile.md +178 -223
  29. package/examples/node.heapsnapshot.md +268 -266
  30. package/examples/node.pprof.md +36 -45
  31. package/examples/python.base.collapsed.md +116 -0
  32. package/examples/python.current.collapsed.md +125 -0
  33. package/examples/python.diff.collapsed.md +51 -0
  34. package/examples/{rust1.pprof.md → rust.base.pprof.md} +223 -226
  35. package/examples/{rust2.pprof.md → rust.current.pprof.md} +199 -199
  36. package/examples/rust.diff.pprof.md +117 -0
  37. package/examples/webkit-timeline-recording.json.md +434 -0
  38. package/package.json +30 -18
  39. package/readme.md +173 -85
  40. package/examples/node.cpuprofile.md +0 -499
  41. package/examples/node.speedscope.json.md +0 -416
package/readme.md CHANGED
@@ -6,8 +6,8 @@
6
6
  <a href="https://npmjs.org/package/profiler-md">
7
7
  <img src="https://badgen.net/npm/v/profiler-md" alt="version" />
8
8
  </a>
9
- <a href="https://github.com/TomerAberbach/profiler-md/actions">
10
- <img src="https://github.com/TomerAberbach/profiler-md/workflows/CI/badge.svg" alt="CI" />
9
+ <a href="https://github.com/TomerAberbach/profiler-md/actions/workflows/ci.yml">
10
+ <img src="https://github.com/TomerAberbach/profiler-md/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" />
11
11
  </a>
12
12
  <a href="https://github.com/sponsors/TomerAberbach">
13
13
  <img src="https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86" alt="Sponsor" />
@@ -20,137 +20,226 @@
20
20
 
21
21
  > [!NOTE]
22
22
  >
23
- > This package is in a **beta** state and I'm excited for you to try it out!
23
+ > This package is in **beta** and I'm excited for you to try it!
24
24
  >
25
- > I'd love your feedback! Share any suggestions, bug reports, feature requests,
26
- > or general thoughts by
25
+ > I'd love your feedback! Share suggestions, bug reports, feature requests, or
26
+ > other thoughts by
27
27
  > [filing an issue](https://github.com/TomerAberbach/profiler-md/issues/new).
28
28
 
29
29
  ## Features
30
30
 
31
- - **Multi-format:** supports [pprof](https://github.com/google/pprof),
32
- [Speedscope](https://github.com/jlfwong/speedscope),
33
- [V8 CPU profiles](https://nodejs.org/api/cli.html#cpu-prof),
34
- [V8 heap profiles](https://nodejs.org/api/cli.html#--heap-prof), and
35
- [V8 heap snapshots](https://nodejs.org/api/cli.html#heapsnapshot-near-heap-limitmax-count)
36
- - **Multi-language:** JS/TS via V8 formats (Node.js, Bun, Deno); Go, Python,
37
- Rust, Java, and more via pprof and Speedscope
31
+ - **Polyglot:** supports many profile and heap snapshot formats across many
32
+ languages
33
+ - **Diffing:** compare two profiles or two heap snapshots to see what changed
34
+ - **Heap analysis:** reports self and retained size with dominator-based
35
+ retention for heap snapshots
36
+ - **Source maps:** resolves minified and transpiled locations back to original
37
+ sources
38
+ - **Zero config:** auto-detects the format, transparently decompresses
39
+ gzip/brotli, and reads from stdin
40
+ - **Readable in the terminal:** ANSI syntax highlighting with heat-map coloring
41
+ and automatic paging
38
42
  - **Configurable:** control the number of top entries shown, working directory
39
43
  for relative paths, third-party detection, and entry filtering
40
- - **CLI and API:** usable on the command-line or programmatically
44
+ - **CLI and API:** use it from the command line or programmatically
41
45
 
42
46
  ## Languages and formats
43
47
 
48
+ We list a format for a language only if its ecosystem's tools natively generate
49
+ it. Third-party tools can often convert others, though.
50
+
44
51
  <!-- LANGUAGE_MATRIX START -->
45
52
 
46
- | Language | Formats |
47
- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
48
- | [C](docs/languages/c.md)/[C++](docs/languages/cpp.md) | [pprof](docs/formats/pprof.md) |
49
- | [Go](docs/languages/go.md) | [pprof](docs/formats/pprof.md) |
50
- | [Java](docs/languages/java.md)/[Kotlin](docs/languages/kotlin.md) | [pprof](docs/formats/pprof.md), [Speedscope](docs/formats/speedscope.md) |
51
- | [JavaScript](docs/languages/javascript.md)/[TypeScript](docs/languages/typescript.md) | [V8 CPU profile](docs/formats/v8-cpu-profile.md) (examples: [Node.js](examples/node.cpuprofile.md), [Deno](examples/deno.cpuprofile.md), [Bun](examples/bun.cpuprofile.md)), [V8 heap profile](docs/formats/v8-heap-profile.md) (examples: [Node.js](examples/node.heapprofile.md)), [V8 heap snapshot](docs/formats/v8-heap-snapshot.md) (examples: [Node.js](examples/node.heapsnapshot.md)), [pprof](docs/formats/pprof.md) (examples: [Node.js](examples/node.pprof.md)), [Speedscope](docs/formats/speedscope.md) (examples: [Node.js](examples/node.speedscope.json.md)) |
52
- | [PHP](docs/languages/php.md) | [Speedscope](docs/formats/speedscope.md) |
53
- | [Python](docs/languages/python.md) | [pprof](docs/formats/pprof.md), [Speedscope](docs/formats/speedscope.md) |
54
- | [Ruby](docs/languages/ruby.md) | [Speedscope](docs/formats/speedscope.md) |
55
- | [Rust](docs/languages/rust.md) | [pprof](docs/formats/pprof.md) (examples: [1](examples/rust1.pprof.md), [2](examples/rust2.pprof.md)), [Speedscope](docs/formats/speedscope.md) |
53
+ | Language | Formats |
54
+ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
55
+ | [C](docs/languages/c.md)⁠/⁠[C++](docs/languages/cpp.md) | [pprof](docs/formats/pprof.md) |
56
+ | [C#](docs/languages/csharp.md)⁠/⁠[F#](docs/languages/fsharp.md) | [Speedscope](docs/formats/speedscope.md) |
57
+ | [Elixir](docs/languages/elixir.md)⁠/⁠[Erlang](docs/languages/erlang.md) | [Collapsed stacks](docs/formats/collapsed.md) |
58
+ | [Go](docs/languages/go.md) | [pprof](docs/formats/pprof.md) |
59
+ | [Java](docs/languages/java.md)⁠/⁠[Kotlin](docs/languages/kotlin.md) | [Collapsed stacks](docs/formats/collapsed.md)<br>[pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
60
+ | [JavaScript](docs/languages/javascript.md)⁠/⁠[TypeScript](docs/languages/typescript.md) | [JSC heap snapshot](docs/formats/jsc-heap-snapshot.md) ([Safari](examples/jsc-heap-snapshot.base.json.md), [Safari diff](examples/jsc-heap-snapshot.diff.json.md))<br>[pprof](docs/formats/pprof.md) ([Node.js](examples/node.pprof.md))<br>[V8 CPU profile](docs/formats/v8-cpu-profile.md) ([Node.js](examples/node.base.cpuprofile.md), [Node.js diff](examples/node.diff.cpuprofile.md), [Deno](examples/deno.cpuprofile.md), [Bun](examples/bun.cpuprofile.md))<br>[V8 heap profile](docs/formats/v8-heap-profile.md) ([Node.js](examples/node.heapprofile.md))<br>[V8 heap snapshot](docs/formats/v8-heap-snapshot.md) ([Node.js](examples/node.heapsnapshot.md))<br>[WebKit timeline recording](docs/formats/webkit-timeline-recording.md) ([example](examples/webkit-timeline-recording.json.md)) |
61
+ | [Julia](docs/languages/julia.md) | [pprof](docs/formats/pprof.md) |
62
+ | [PHP](docs/languages/php.md) | [Speedscope](docs/formats/speedscope.md) |
63
+ | [Python](docs/languages/python.md) | [Collapsed stacks](docs/formats/collapsed.md) ([Tachyon](examples/python.base.collapsed.md), [Tachyon diff](examples/python.diff.collapsed.md))<br>[pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
64
+ | [Ruby](docs/languages/ruby.md) | [Speedscope](docs/formats/speedscope.md) |
65
+ | [Rust](docs/languages/rust.md) | [pprof](docs/formats/pprof.md) ([base](examples/rust.base.pprof.md), [diff](examples/rust.diff.pprof.md)) |
56
66
 
57
67
  <!-- LANGUAGE_MATRIX END -->
58
68
 
59
69
  ## Install
60
70
 
61
71
  ```sh
62
- $ npm i profiler-md
72
+ $ npm i -g profiler-md
63
73
  ```
64
74
 
65
75
  ## Usage
66
76
 
67
77
  ### CLI
68
78
 
79
+ <!-- prettier-ignore-start -->
80
+
69
81
  <!-- CLI_HELP START -->
70
82
 
71
83
  ```sh
72
84
  $ profiler-md --help
73
-
74
- Converts performance profiles to human and LLM friendly Markdown.
75
-
76
- Usage: profiler-md [options] [file]
77
- profiler-md --help [format|language]
78
-
79
- Options:
80
- -f, --format <format> Profile format, auto-detected from content if omitted
81
- -o, --output <file> Output file (default: - for stdout)
82
- --top-n <n> Number of top entries to show (default: 20)
83
- --cwd <path> Working directory for relative file paths in output
84
- --third-party <glob> Mark URLs matching this glob as third-party
85
- (repeatable; default: node_modules)
86
- --source-maps <glob> Apply source maps matching this glob to profile
87
- locations; files may be source map JSON or contain
88
- inline source map comments (repeatable)
89
- --no-pager Disable paging of stdout output (default: paged when
90
- stdout is a TTY, using $PAGER or less)
91
- --color, --no-color Force-enable or force-disable ANSI syntax highlighting
92
- (default: auto, on when stdout is a TTY; honors
93
- NO_COLOR and FORCE_COLOR)
94
- --help [format|language] Show this help message or topic docs
95
-
96
- Formats: speedscope, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, pprof
97
- Languages: c, cpp, go, java, kotlin, javascript, typescript, php, python, ruby, rust
85
+ Usage: profiler-md [(-h/--help [TOPIC])] [-f/--format FORMAT] [-o/--output FILE]
86
+ [--top-n N] [--base-url STRING] [--source-maps GLOB...] [--match
87
+ REGEX=REPLACEMENT...] [--third-party GLOB...] [--no-pager] [(--color |
88
+ --no-color)] ([FILE] | BASE CURRENT)
89
+
90
+ Converts performance profiles to human and LLM friendly Markdown.
91
+
92
+ -h, --help [TOPIC] Show this help message or topic docs
93
+ -f, --format FORMAT Input profile format (default: auto)
94
+ -o, --output FILE Output file (default: - for stdout)
95
+ --top-n N Number of top entries to show (default: 20)
96
+ --base-url STRING Base URL or path to show paths relative to
97
+ (default: cwd)
98
+ --source-maps GLOB Source maps (JSON or inline) to apply to profile
99
+ locations (repeatable)
100
+ --match REGEX=REPLACEMENT Treat locations matching REGEX as REPLACEMENT
101
+ when matching entries across diffed profiles
102
+ (repeatable)
103
+ --third-party GLOB Additional URLs or paths to consider third-party
104
+ (repeatable)
105
+ --no-pager Disable stdout output paging (default: auto)
106
+ --color Enable or disable ANSI syntax highlighting
107
+ (default: auto)
108
+ --no-color
109
+ FILE Profile to convert (reads from stdin if omitted)
110
+ BASE Base profile to diff
111
+ CURRENT Current profile to diff against the base
112
+
113
+ Formats: collapsed, jsc-heap-snapshot, pprof, speedscope, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, webkit-timeline-recording
114
+ Languages: c, cpp, csharp, fsharp, elixir, erlang, go, java, kotlin, javascript, typescript, julia, php, python, ruby, rust
98
115
  ```
99
116
 
100
117
  <!-- CLI_HELP END -->
101
118
 
119
+ <!-- prettier-ignore-end -->
120
+
102
121
  ### API
103
122
 
104
123
  ```js
105
- import { readFile } from 'node:fs/promises'
124
+ import { openAsBlob, readFileSync } from 'node:fs'
106
125
  import {
107
- defaultIncludeEntry,
108
- defaultIsThirdPartyEntry,
109
- pprofToMd,
110
- speedscopeProfileToMd,
111
- v8CpuProfileToMd,
112
- v8HeapProfileToMd,
113
- v8HeapSnapshotToMd,
126
+ defaultCategorizeEntry,
127
+ defaultMatchEntry,
128
+ defaultShowEntry,
129
+ diffProfiles,
130
+ diffProfilesAsync,
131
+ profileToMd,
132
+ profileToMdAsync,
114
133
  } from 'profiler-md'
115
134
 
116
- const pprofData = await readFile(`example.pprof`)
117
- const speedscopeProfileData = await readFile(`example.speedscope.json`)
118
- const v8CpuProfileData = await readFile(`example.cpuprofile`)
119
- const v8HeapProfileData = await readFile(`example.heapprofile`)
120
- const v8HeapSnapshotData = await readFile(`example.heapsnapshot`)
121
-
122
- // Basic usage
123
- console.log(pprofToMd(pprofData))
124
- console.log(speedscopeProfileToMd(speedscopeProfileData))
125
- console.log(v8CpuProfileToMd(v8CpuProfileData))
126
- console.log(v8HeapProfileToMd(v8HeapProfileData))
127
- console.log(v8HeapSnapshotToMd(v8HeapSnapshotData))
135
+ // Auto-detect format (async)
136
+ console.log(await profileToMdAsync(await openAsBlob(`example.cpuprofile`)))
137
+ console.log(await profileToMdAsync(await openAsBlob(`example.pprof`)))
138
+
139
+ // Explicit format
140
+ console.log(
141
+ await profileToMdAsync({
142
+ data: await openAsBlob(`example.pprof`),
143
+ format: `pprof`,
144
+ }),
145
+ )
146
+
147
+ // Synchronous usage (auto-detect)
148
+ console.log(profileToMd(readFileSync(`example.cpuprofile`, `utf8`)))
149
+ console.log(profileToMd(readFileSync(`example.pprof`)))
150
+
151
+ // Synchronous usage with explicit format
152
+ console.log(
153
+ profileToMd({ data: readFileSync(`example.pprof`), format: `pprof` }),
154
+ )
155
+
156
+ // Diff two profiles or two heap snapshots (async, auto-detect)
157
+ console.log(
158
+ await diffProfilesAsync(
159
+ await openAsBlob(`base.cpuprofile`),
160
+ await openAsBlob(`current.cpuprofile`),
161
+ ),
162
+ )
163
+ console.log(
164
+ await diffProfilesAsync(
165
+ await openAsBlob(`base.heapsnapshot`),
166
+ await openAsBlob(`current.heapsnapshot`),
167
+ ),
168
+ )
169
+
170
+ // Synchronous diff with explicit format
171
+ console.log(
172
+ diffProfiles(
173
+ { data: readFileSync(`base.pprof`), format: `pprof` },
174
+ { data: readFileSync(`current.pprof`), format: `pprof` },
175
+ ),
176
+ )
128
177
 
129
178
  // Complex usage
130
179
  const options = {
131
180
  // Show top 10 functions instead of the default 20.
132
181
  topN: 10,
133
- // Make paths relative to a custom directory.
134
- cwd: `/path/to/project`,
135
- isThirdPartyEntry: entry =>
136
- defaultIsThirdPartyEntry(entry) ||
137
- // Treat an additional vendor directory as third-party.
138
- !!entry.location?.url.pathname.includes(`/vendor/`),
139
- includeEntry: entry =>
140
- defaultIncludeEntry(entry) &&
182
+ // Make paths relative to a custom base URL or directory.
183
+ baseURL: `/path/to/project`,
184
+ matchEntry: entry => {
185
+ if (entry.location?.url.pathname.includes(`/bundle.`)) {
186
+ // Match bundled entries when diffing by name only, ignoring
187
+ // content-hashed filenames.
188
+ return { name: entry.name }
189
+ }
190
+ return defaultMatchEntry(entry)
191
+ },
192
+ categorizeEntry: entry => {
193
+ if (entry.location?.url.pathname.includes(`/vendor/`)) {
194
+ // Treat an additional vendor directory as third-party.
195
+ return `third-party`
196
+ }
197
+ return defaultCategorizeEntry(entry)
198
+ },
199
+ showEntry: entry =>
200
+ defaultShowEntry(entry) &&
141
201
  // Exclude entries from a specific file.
142
202
  !entry.location?.includes(`/path/to/project/src/noisy`),
143
203
  }
144
- console.log(pprofToMd(pprofData, options))
145
- console.log(speedscopeProfileToMd(speedscopeProfileData, options))
146
- console.log(v8CpuProfileToMd(v8CpuProfileData, options))
147
- console.log(v8HeapProfileToMd(v8HeapProfileData, options))
148
- console.log(v8HeapSnapshotToMd(v8HeapSnapshotData, options))
204
+ console.log(await profileToMdAsync(await openAsBlob(`example.pprof`), options))
205
+ console.log(
206
+ await profileToMdAsync(await openAsBlob(`example.cpuprofile`), options),
207
+ )
208
+
209
+ // The same options also apply to diffs. `matchEntry` only takes effect here,
210
+ // where it controls which entries are considered the same across the two sides.
211
+ console.log(
212
+ await diffProfilesAsync(
213
+ await openAsBlob(`base.pprof`),
214
+ await openAsBlob(`current.pprof`),
215
+ options,
216
+ ),
217
+ )
218
+ ```
219
+
220
+ ## Shell completions
221
+
222
+ ```sh
223
+ # Bash (Linux)
224
+ $ profiler-md --completion bash > ~/.local/share/bash-completion/completions/profiler-md
225
+
226
+ # Bash (macOS/Homebrew)
227
+ $ profiler-md --completion bash > $(brew --prefix)/etc/bash_completion.d/profiler-md
228
+
229
+ # Fish
230
+ $ profiler-md --completion fish > ~/.config/fish/completions/profiler-md.fish
231
+
232
+ # Zsh
233
+ $ profiler-md --completion zsh > ~/.zfunc/_profiler-md
234
+
235
+ # PowerShell
236
+ $ profiler-md --completion pwsh >> $PROFILE.CurrentUserCurrentHost
149
237
  ```
150
238
 
151
239
  ## Skills
152
240
 
153
- Use this `profiler-md` skill to have an agent profile and optimize your code:
241
+ Use the [`profiler-md` skill](./skills/profile-optimize/SKILL.md) to have an
242
+ agent profile and optimize your code:
154
243
 
155
244
  ```sh
156
245
  $ npx skills add TomerAberbach/profiler-md --skill profile-optimize
@@ -158,8 +247,7 @@ $ npx skills add TomerAberbach/profiler-md --skill profile-optimize
158
247
 
159
248
  See [skills.sh](https://skills.sh/docs) for more info.
160
249
 
161
- Fun fact: the skill has been used to profile and optimize `profiler-md` using
162
- itself!
250
+ Fun fact: the skill has profiled and optimized `profiler-md` itself!
163
251
 
164
252
  ## Contributing
165
253