profiler-md 0.1.3 → 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,78 +28,112 @@
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
41
35
 
36
+ ## Languages and formats
37
+
38
+ <!-- LANGUAGE_MATRIX START -->
39
+
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) |
50
+
51
+ <!-- LANGUAGE_MATRIX END -->
52
+
42
53
  ## Install
43
54
 
44
55
  ```sh
45
- $ npm i profiler-md
56
+ $ npm i -g profiler-md
46
57
  ```
47
58
 
48
59
  ## Usage
49
60
 
50
61
  ### CLI
51
62
 
63
+ <!-- prettier-ignore-start -->
64
+
52
65
  <!-- CLI_HELP START -->
53
66
 
54
67
  ```sh
55
68
  $ profiler-md --help
56
-
57
- Converts performance profiles to human and LLM friendly Markdown.
58
-
59
- Usage: profiler-md [options] [file]
60
-
61
- Options:
62
- -t, --type <type> Profile type, auto-detected from content if omitted
63
- [pprof|speedscope|v8-cpu-profile|v8-heap-profile|v8-heap-snapshot]
64
- -o, --output <file> Output file (default: - for stdout)
65
- --top-n <n> Number of top entries to show (default: 20)
66
- --cwd <path> Working directory for relative file paths in output
67
- --third-party <glob> Mark URLs matching this glob as third-party
68
- (repeatable; default: node_modules)
69
- --source-maps <glob> Apply source maps matching this glob to profile
70
- locations; files may be source map JSON or contain
71
- inline source map comments (repeatable)
72
- --help Show this help message
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
73
93
  ```
74
94
 
75
95
  <!-- CLI_HELP END -->
76
96
 
97
+ <!-- prettier-ignore-end -->
98
+
77
99
  ### API
78
100
 
79
101
  ```js
80
- import { readFile } from 'node:fs/promises'
102
+ import { openAsBlob } from 'node:fs'
81
103
  import {
82
- defaultIncludeEntry,
83
- defaultIsThirdPartyEntry,
104
+ defaultCategorizeEntry,
105
+ defaultShowEntry,
84
106
  pprofToMd,
107
+ pprofToMdAsync,
85
108
  speedscopeProfileToMd,
109
+ speedscopeProfileToMdAsync,
86
110
  v8CpuProfileToMd,
111
+ v8CpuProfileToMdAsync,
87
112
  v8HeapProfileToMd,
113
+ v8HeapProfileToMdAsync,
88
114
  v8HeapSnapshotToMd,
115
+ v8HeapSnapshotToMdAsync,
116
+ webkitTimelineRecordingToMd,
117
+ webkitTimelineRecordingToMdAsync,
89
118
  } from 'profiler-md'
90
119
 
91
- const pprofData = await readFile(`example.pprof`)
92
- const speedscopeProfileData = await readFile(`example.speedscope.json`)
93
- const v8CpuProfileData = await readFile(`example.cpuprofile`)
94
- const v8HeapProfileData = await readFile(`example.heapprofile`)
95
- const v8HeapSnapshotData = await readFile(`example.heapsnapshot`)
96
-
97
120
  // Basic usage
98
- console.log(pprofToMd(pprofData))
99
- console.log(speedscopeProfileToMd(speedscopeProfileData))
100
- console.log(v8CpuProfileToMd(v8CpuProfileData))
101
- console.log(v8HeapProfileToMd(v8HeapProfileData))
102
- 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
+ )
103
137
 
104
138
  // Complex usage
105
139
  const options = {
@@ -107,20 +141,73 @@ const options = {
107
141
  topN: 10,
108
142
  // Make paths relative to a custom directory.
109
143
  cwd: `/path/to/project`,
110
- isThirdPartyEntry: entry =>
111
- defaultIsThirdPartyEntry(entry) ||
112
- // Treat an additional vendor directory as third-party.
113
- !!entry.location?.url.pathname.includes(`/vendor/`),
114
- includeEntry: entry =>
115
- 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) &&
116
153
  // Exclude entries from a specific file.
117
154
  !entry.location?.includes(`/path/to/project/src/noisy`),
118
155
  }
119
- console.log(pprofToMd(pprofData, options))
120
- console.log(speedscopeProfileToMd(speedscopeProfileData, options))
121
- console.log(v8CpuProfileToMd(v8CpuProfileData, options))
122
- console.log(v8HeapProfileToMd(v8HeapProfileData, options))
123
- 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
124
211
  ```
125
212
 
126
213
  ## Skills