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.
- package/dist/cli/index.mjs +2787 -1669
- package/dist/index.d.mts +249 -78
- package/dist/index.js +2 -2
- package/docs/formats/collapsed.md +12 -0
- package/docs/formats/jsc-heap-snapshot.md +13 -0
- package/docs/formats/webkit-timeline-recording.md +9 -0
- package/docs/languages/c.md +1 -1
- package/docs/languages/cpp.md +136 -0
- package/docs/languages/csharp.md +49 -0
- package/docs/languages/elixir.md +42 -0
- package/docs/languages/erlang.md +42 -0
- package/docs/languages/fsharp.md +49 -0
- package/docs/languages/go.md +2 -2
- package/docs/languages/java.md +10 -7
- package/docs/languages/javascript.md +69 -0
- package/docs/languages/julia.md +42 -0
- package/docs/languages/kotlin.md +120 -0
- package/docs/languages/python.md +10 -4
- package/docs/languages/typescript.md +254 -0
- package/examples/bun.cpuprofile.md +94 -116
- package/examples/deno.cpuprofile.md +11 -18
- package/examples/jsc-heap-snapshot.base.json.md +507 -0
- package/examples/jsc-heap-snapshot.current.json.md +504 -0
- package/examples/jsc-heap-snapshot.diff.json.md +119 -0
- package/examples/node.base.cpuprofile.md +451 -0
- package/examples/node.current.cpuprofile.md +449 -0
- package/examples/node.diff.cpuprofile.md +82 -0
- package/examples/node.heapprofile.md +178 -223
- package/examples/node.heapsnapshot.md +268 -266
- package/examples/node.pprof.md +36 -45
- package/examples/python.base.collapsed.md +116 -0
- package/examples/python.current.collapsed.md +125 -0
- package/examples/python.diff.collapsed.md +51 -0
- package/examples/{rust1.pprof.md → rust.base.pprof.md} +223 -226
- package/examples/{rust2.pprof.md → rust.current.pprof.md} +199 -199
- package/examples/rust.diff.pprof.md +117 -0
- package/examples/webkit-timeline-recording.json.md +434 -0
- package/package.json +30 -18
- package/readme.md +173 -85
- package/examples/node.cpuprofile.md +0 -499
- 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/
|
|
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
|
|
23
|
+
> This package is in **beta** and I'm excited for you to try it!
|
|
24
24
|
>
|
|
25
|
-
> I'd love your feedback! Share
|
|
26
|
-
>
|
|
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
|
-
- **
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
- **
|
|
37
|
-
|
|
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:**
|
|
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
|
|
47
|
-
|
|
|
48
|
-
| [C](docs/languages/c.md)
|
|
49
|
-
| [
|
|
50
|
-
| [
|
|
51
|
-
| [
|
|
52
|
-
| [
|
|
53
|
-
| [
|
|
54
|
-
| [
|
|
55
|
-
| [
|
|
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
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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 {
|
|
124
|
+
import { openAsBlob, readFileSync } from 'node:fs'
|
|
106
125
|
import {
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
126
|
+
defaultCategorizeEntry,
|
|
127
|
+
defaultMatchEntry,
|
|
128
|
+
defaultShowEntry,
|
|
129
|
+
diffProfiles,
|
|
130
|
+
diffProfilesAsync,
|
|
131
|
+
profileToMd,
|
|
132
|
+
profileToMdAsync,
|
|
114
133
|
} from 'profiler-md'
|
|
115
134
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
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(
|
|
145
|
-
console.log(
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|
|
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
|
|
162
|
-
itself!
|
|
250
|
+
Fun fact: the skill has profiled and optimized `profiler-md` itself!
|
|
163
251
|
|
|
164
252
|
## Contributing
|
|
165
253
|
|