profiler-md 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/readme.md 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" />
@@ -28,13 +28,7 @@
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 formats across many languages
38
32
  - **Configurable:** control the number of top entries shown, working directory
39
33
  for relative paths, third-party detection, and entry filtering
40
34
  - **CLI and API:** usable on the command-line or programmatically
@@ -43,88 +37,103 @@
43
37
 
44
38
  <!-- LANGUAGE_MATRIX START -->
45
39
 
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) |
40
+ | Language | Formats |
41
+ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42
+ | [C](docs/languages/c.md)⁠/⁠[C++](docs/languages/cpp.md) | [pprof](docs/formats/pprof.md) |
43
+ | [Go](docs/languages/go.md) | [pprof](docs/formats/pprof.md) |
44
+ | [Java](docs/languages/java.md)⁠/⁠[Kotlin](docs/languages/kotlin.md) | [pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
45
+ | [JavaScript](docs/languages/javascript.md)⁠/⁠[TypeScript](docs/languages/typescript.md) | [JSC heap snapshot](docs/formats/jsc-heap-snapshot.md) ([Safari](examples/jsc-heap-snapshot.json.md))<br>[pprof](docs/formats/pprof.md) ([Node.js](examples/node.pprof.md))<br>[Speedscope](docs/formats/speedscope.md) ([Node.js](examples/node.speedscope.json.md))<br>[V8 CPU profile](docs/formats/v8-cpu-profile.md) ([Node.js](examples/node.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)) |
46
+ | [PHP](docs/languages/php.md) | [Speedscope](docs/formats/speedscope.md) |
47
+ | [Python](docs/languages/python.md) | [pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
48
+ | [Ruby](docs/languages/ruby.md) | [Speedscope](docs/formats/speedscope.md) |
49
+ | [Rust](docs/languages/rust.md) | [pprof](docs/formats/pprof.md) ([example](examples/rust.pprof.md))<br>[Speedscope](docs/formats/speedscope.md) |
56
50
 
57
51
  <!-- LANGUAGE_MATRIX END -->
58
52
 
59
53
  ## Install
60
54
 
61
55
  ```sh
62
- $ npm i profiler-md
56
+ $ npm i -g profiler-md
63
57
  ```
64
58
 
65
59
  ## Usage
66
60
 
67
61
  ### CLI
68
62
 
63
+ <!-- prettier-ignore-start -->
64
+
69
65
  <!-- CLI_HELP START -->
70
66
 
71
67
  ```sh
72
68
  $ 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
69
+ Usage: profiler-md [(-h/--help [TOPIC])] [-f/--format FORMAT] [-o/--output FILE]
70
+ [--top-n N] [--cwd PATH] [--third-party GLOB...] [--source-maps GLOB...]
71
+ [--no-pager] [(--color | --no-color)] [FILE]
72
+
73
+ Converts performance profiles to human and LLM friendly Markdown.
74
+
75
+ -h, --help [TOPIC] Show this help message or topic docs
76
+ -f, --format FORMAT Input profile format (default: auto)
77
+ -o, --output FILE Output file (default: - for stdout)
78
+ --top-n N Number of top entries to show (default: 20)
79
+ --cwd PATH Directory to show paths relative to (default: cwd)
80
+ --third-party GLOB Additional URLs to consider third-party
81
+ (repeatable)
82
+ --source-maps GLOB Source maps (JSON or inline) to apply to profile
83
+ locations (repeatable)
84
+ --no-pager Disable stdout output paging (default: auto)
85
+ --color Enable or disable ANSI syntax highlighting
86
+ (default: auto)
87
+ --no-color
88
+ FILE Profile file to convert (reads from stdin if
89
+ omitted)
90
+
91
+ Formats: jsc-heap-snapshot, pprof, speedscope, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, webkit-timeline-recording
92
+ Languages: c, cpp, go, java, kotlin, javascript, typescript, php, python, ruby, rust
98
93
  ```
99
94
 
100
95
  <!-- CLI_HELP END -->
101
96
 
97
+ <!-- prettier-ignore-end -->
98
+
102
99
  ### API
103
100
 
104
101
  ```js
105
- import { readFile } from 'node:fs/promises'
102
+ import { openAsBlob } from 'node:fs'
106
103
  import {
107
- defaultIncludeEntry,
108
- defaultIsThirdPartyEntry,
104
+ defaultCategorizeEntry,
105
+ defaultShowEntry,
109
106
  pprofToMd,
107
+ pprofToMdAsync,
110
108
  speedscopeProfileToMd,
109
+ speedscopeProfileToMdAsync,
111
110
  v8CpuProfileToMd,
111
+ v8CpuProfileToMdAsync,
112
112
  v8HeapProfileToMd,
113
+ v8HeapProfileToMdAsync,
113
114
  v8HeapSnapshotToMd,
115
+ v8HeapSnapshotToMdAsync,
116
+ webkitTimelineRecordingToMd,
117
+ webkitTimelineRecordingToMdAsync,
114
118
  } from 'profiler-md'
115
119
 
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
120
  // 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))
121
+ console.log(await pprofToMdAsync(await openAsBlob(`example.pprof`)))
122
+ console.log(
123
+ await speedscopeProfileToMdAsync(await openAsBlob(`example.speedscope.json`)),
124
+ )
125
+ console.log(await v8CpuProfileToMdAsync(await openAsBlob(`example.cpuprofile`)))
126
+ console.log(
127
+ await v8HeapProfileToMdAsync(await openAsBlob(`example.heapprofile`)),
128
+ )
129
+ console.log(
130
+ await v8HeapSnapshotToMdAsync(await openAsBlob(`example.heapsnapshot`)),
131
+ )
132
+ console.log(
133
+ await webkitTimelineRecordingToMdAsync(
134
+ await openAsBlob(`example.webkit-timeline-recording.json`),
135
+ ),
136
+ )
128
137
 
129
138
  // Complex usage
130
139
  const options = {
@@ -132,20 +141,73 @@ const options = {
132
141
  topN: 10,
133
142
  // Make paths relative to a custom directory.
134
143
  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) &&
144
+ categorizeEntry: entry => {
145
+ if (entry.location?.url.pathname.includes(`/vendor/`)) {
146
+ // Treat an additional vendor directory as third-party.
147
+ return `third-party`
148
+ }
149
+ return defaultCategorizeEntry(entry)
150
+ },
151
+ showEntry: entry =>
152
+ defaultShowEntry(entry) &&
141
153
  // Exclude entries from a specific file.
142
154
  !entry.location?.includes(`/path/to/project/src/noisy`),
143
155
  }
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))
156
+ console.log(await pprofToMdAsync(await openAsBlob(`example.pprof`), options))
157
+ console.log(
158
+ await speedscopeProfileToMdAsync(
159
+ await openAsBlob(`example.speedscope.json`),
160
+ options,
161
+ ),
162
+ )
163
+ console.log(
164
+ await v8CpuProfileToMdAsync(await openAsBlob(`example.cpuprofile`), options),
165
+ )
166
+ console.log(
167
+ await v8HeapProfileToMdAsync(
168
+ await openAsBlob(`example.heapprofile`),
169
+ options,
170
+ ),
171
+ )
172
+ console.log(
173
+ await v8HeapSnapshotToMdAsync(
174
+ await openAsBlob(`example.heapsnapshot`),
175
+ options,
176
+ ),
177
+ )
178
+ console.log(
179
+ await webkitTimelineRecordingToMdAsync(
180
+ await openAsBlob(`example.webkit-timeline-recording.json`),
181
+ options,
182
+ ),
183
+ )
184
+
185
+ // Synchronous usage
186
+ console.log(pprofToMd(pprofData))
187
+ console.log(speedscopeProfileToMd(speedscopeProfileData))
188
+ console.log(v8CpuProfileToMd(v8CpuProfileData))
189
+ console.log(v8HeapProfileToMd(v8HeapProfileData))
190
+ console.log(v8HeapSnapshotToMd(v8HeapSnapshotData))
191
+ console.log(webkitTimelineRecordingToMd(webkitTimelineRecordingData))
192
+ ```
193
+
194
+ ## Shell completions
195
+
196
+ ```sh
197
+ # Bash (Linux)
198
+ $ profiler-md --completion bash > ~/.local/share/bash-completion/completions/profiler-md
199
+
200
+ # Bash (macOS/Homebrew)
201
+ $ profiler-md --completion bash > $(brew --prefix)/etc/bash_completion.d/profiler-md
202
+
203
+ # Fish
204
+ $ profiler-md --completion fish > ~/.config/fish/completions/profiler-md.fish
205
+
206
+ # Zsh
207
+ $ profiler-md --completion zsh > ~/.zfunc/_profiler-md
208
+
209
+ # PowerShell
210
+ $ profiler-md --completion pwsh >> $PROFILE.CurrentUserCurrentHost
149
211
  ```
150
212
 
151
213
  ## Skills