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/dist/cli/index.mjs +3402 -0
- package/dist/index.d.mts +273 -73
- package/dist/index.js +2 -2
- package/docs/formats/jsc-heap-snapshot.md +13 -0
- package/docs/formats/pprof.md +12 -0
- package/docs/formats/speedscope.md +11 -0
- package/docs/formats/v8-cpu-profile.md +13 -0
- package/docs/formats/v8-heap-profile.md +13 -0
- package/docs/formats/v8-heap-snapshot.md +10 -0
- package/docs/formats/webkit-timeline-recording.md +9 -0
- package/docs/languages/c.md +136 -0
- package/docs/languages/go.md +187 -0
- package/docs/languages/java.md +117 -0
- package/docs/languages/javascript.md +219 -0
- package/docs/languages/php.md +31 -0
- package/docs/languages/python.md +112 -0
- package/docs/languages/ruby.md +67 -0
- package/docs/languages/rust.md +44 -0
- package/examples/bun.cpuprofile.md +475 -0
- package/examples/deno.cpuprofile.md +481 -0
- package/examples/jsc-heap-snapshot.json.md +509 -0
- package/examples/node.cpuprofile.md +485 -0
- package/examples/node.heapprofile.md +281 -0
- package/examples/node.heapsnapshot.md +694 -0
- package/examples/node.pprof.md +441 -0
- package/examples/node.speedscope.json.md +408 -0
- package/examples/rust.pprof.md +477 -0
- package/examples/webkit-timeline-recording.json.md +434 -0
- package/package.json +21 -5
- package/readme.md +139 -52
- package/dist/cli.mjs +0 -2346
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,78 +28,112 @@
|
|
|
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
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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 {
|
|
102
|
+
import { openAsBlob } from 'node:fs'
|
|
81
103
|
import {
|
|
82
|
-
|
|
83
|
-
|
|
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(
|
|
99
|
-
console.log(
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
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
|
+
)
|
|
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
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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(
|
|
120
|
-
console.log(
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|