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/dist/cli/index.mjs +1923 -1485
- package/dist/index.d.mts +256 -23
- package/dist/index.js +2 -2
- 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/go.md +2 -2
- package/docs/languages/javascript.md +34 -0
- package/examples/bun.cpuprofile.md +67 -89
- package/examples/deno.cpuprofile.md +2 -9
- package/examples/jsc-heap-snapshot.json.md +509 -0
- package/examples/node.cpuprofile.md +59 -73
- package/examples/node.heapprofile.md +174 -219
- package/examples/node.heapsnapshot.md +250 -248
- package/examples/node.pprof.md +33 -42
- package/examples/node.speedscope.json.md +57 -65
- package/examples/{rust1.pprof.md → rust.pprof.md} +31 -34
- package/examples/webkit-timeline-recording.json.md +434 -0
- package/package.json +13 -4
- package/readme.md +132 -70
- package/examples/rust2.pprof.md +0 -480
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" />
|
|
@@ -28,13 +28,7 @@
|
|
|
28
28
|
|
|
29
29
|
## Features
|
|
30
30
|
|
|
31
|
-
- **
|
|
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
|
|
47
|
-
|
|
|
48
|
-
| [C](docs/languages/c.md)
|
|
49
|
-
| [Go](docs/languages/go.md)
|
|
50
|
-
| [Java](docs/languages/java.md)
|
|
51
|
-
| [JavaScript](docs/languages/javascript.md)
|
|
52
|
-
| [PHP](docs/languages/php.md)
|
|
53
|
-
| [Python](docs/languages/python.md)
|
|
54
|
-
| [Ruby](docs/languages/ruby.md)
|
|
55
|
-
| [Rust](docs/languages/rust.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
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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 {
|
|
102
|
+
import { openAsBlob } from 'node:fs'
|
|
106
103
|
import {
|
|
107
|
-
|
|
108
|
-
|
|
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(
|
|
124
|
-
console.log(
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
console.log(
|
|
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
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
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(
|
|
145
|
-
console.log(
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|