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.
@@ -0,0 +1,219 @@
1
+ # JavaScript
2
+
3
+ Profiling JavaScript works across Node.js, Deno, Bun, and Chrome via V8 CPU
4
+ profiles, V8 heap profiles, and V8 heap snapshots.
5
+
6
+ ## CPU profiling
7
+
8
+ Periodically samples the call stack. Useful for finding CPU hot spots.
9
+
10
+ ### CLI
11
+
12
+ ```sh
13
+ # Node.js
14
+ node --cpu-prof script.js
15
+
16
+ # Deno
17
+ deno run --cpu-prof script.ts
18
+
19
+ # Bun (output was incorrect before v1.3.13)
20
+ bun --cpu-prof script.ts
21
+ ```
22
+
23
+ #### Flags
24
+
25
+ | Flag | Default | Description |
26
+ | -------------------------- | ---------------------------------- | --------------------------------------------- |
27
+ | `--cpu-prof` | — | Write a CPU profile on exit; enabled when set |
28
+ | `--cpu-prof-interval=<µs>` | `1000` | Sampling interval in microseconds |
29
+ | `--cpu-prof-dir=<dir>` | `.` | Directory to write the profile to |
30
+ | `--cpu-prof-name=<name>` | `CPU.<timestamp>.<pid>.cpuprofile` | Filename for the profile |
31
+
32
+ ### Programmatic API
33
+
34
+ Profile a specific section of code rather than the whole process:
35
+
36
+ ```js
37
+ import { writeFileSync } from 'node:fs'
38
+ import { Session } from 'node:inspector/promises'
39
+
40
+ const session = new Session()
41
+ session.connect()
42
+ await session.post(`Profiler.enable`)
43
+ await session.post(`Profiler.setSamplingInterval`, { interval: 100 })
44
+ await session.post(`Profiler.start`)
45
+
46
+ // Code to profile...
47
+
48
+ const { profile } = await session.post(`Profiler.stop`)
49
+ writeFileSync(`cpu.cpuprofile`, JSON.stringify(profile))
50
+ ```
51
+
52
+ ## Memory profiling
53
+
54
+ Samples heap allocations by stack trace. Useful for finding allocation hot spots
55
+ and reducing GC pressure.
56
+
57
+ `bun --heap-prof` generates a heap _snapshot_ on exit, not a heap _profile_.
58
+ Deno has no equivalent.
59
+
60
+ ### CLI
61
+
62
+ ```sh
63
+ # Node.js
64
+ node --heap-prof script.js
65
+ ```
66
+
67
+ #### Flags
68
+
69
+ | Flag | Default | Description |
70
+ | ------------------------------ | -------- | ---------------------------------------------- |
71
+ | `--heap-prof` | — | Write a heap profile on exit; enabled when set |
72
+ | `--heap-prof-interval=<bytes>` | `524288` | Sampling interval in bytes (default 512 KB) |
73
+ | `--heap-prof-dir=<dir>` | `.` | Directory to write the profile to |
74
+ | `--heap-prof-name=<name>` | — | Filename for the profile |
75
+
76
+ ### Programmatic API
77
+
78
+ ```js
79
+ import { writeFileSync } from 'node:fs'
80
+ import { Session } from 'node:inspector/promises'
81
+
82
+ const session = new Session()
83
+ session.connect()
84
+ await session.post(`HeapProfiler.enable`)
85
+ await session.post(`HeapProfiler.startSamplingHeapProfiler`, {
86
+ samplingInterval: 524_288,
87
+ })
88
+
89
+ // Code to profile...
90
+
91
+ const { profile } = await session.post(`HeapProfiler.stopSamplingHeapProfiler`)
92
+ writeFileSync(`heap.heapprofile`, JSON.stringify(profile))
93
+ ```
94
+
95
+ ## Heap snapshots
96
+
97
+ Captures a snapshot of all live objects on the heap. Useful for diagnosing
98
+ memory leaks.
99
+
100
+ ### CLI
101
+
102
+ ```sh
103
+ # Trigger on OOM
104
+ node --heapsnapshot-near-heap-limit=1 script.js
105
+
106
+ # Trigger on signal
107
+ node --heapsnapshot-signal=USR2 script.js # then: kill -USR2 <pid>
108
+
109
+ # Bun (on exit)
110
+ bun --heap-prof script.ts
111
+ ```
112
+
113
+ #### Node.js flags
114
+
115
+ | Flag | Default | Description |
116
+ | ------------------------------------ | ------- | ---------------------------------------------------------- |
117
+ | `--heapsnapshot-near-heap-limit=<n>` | — | Write up to n snapshots when the heap approaches its limit |
118
+ | `--heapsnapshot-signal=<signal>` | — | Signal that triggers a snapshot on demand (e.g. `USR2`) |
119
+
120
+ #### Bun flags
121
+
122
+ | Flag | Default | Description |
123
+ | ------------------------- | ------- | ----------------------------------------------- |
124
+ | `--heap-prof` | — | Write a heap snapshot on exit; enabled when set |
125
+ | `--heap-prof-dir=<dir>` | `.` | Directory to write the snapshot to |
126
+ | `--heap-prof-name=<name>` | — | Filename for the snapshot |
127
+
128
+ ### Programmatic API
129
+
130
+ ```js
131
+ import { writeHeapSnapshot } from 'node:v8'
132
+
133
+ // Code to capture...
134
+ writeHeapSnapshot(`heap.heapsnapshot`)
135
+ ```
136
+
137
+ ## Chrome DevTools
138
+
139
+ Chrome DevTools can profile JavaScript running in the browser or connected to
140
+ Node.js, Deno, or Bun via `--inspect`. The panels and workflow are the same in
141
+ both cases.
142
+
143
+ ### Connecting
144
+
145
+ **In the browser:** open DevTools with ⌥⌘I (macOS) or Ctrl+Shift+I
146
+ (Windows/Linux).
147
+
148
+ **Via `--inspect` (Node.js, Deno, Bun):** start the process with the inspector
149
+ enabled, then open `chrome://inspect` in Chrome and click **Open dedicated
150
+ DevTools for Node**. For Bun, open the URL printed to stderr in
151
+ [debug.bun.sh](https://debug.bun.sh) — Bun uses the WebKit Inspector Protocol
152
+ rather than V8's.
153
+
154
+ ```sh
155
+ # Node.js (default port 9229)
156
+ node --inspect script.js
157
+
158
+ # Deno (default port 9229)
159
+ deno run --inspect script.ts
160
+
161
+ # Bun (auto-assigned port)
162
+ bun --inspect script.ts
163
+ ```
164
+
165
+ #### Flags (all runtimes)
166
+
167
+ | Flag | Description |
168
+ | ------------------------------ | ----------------------------------------------------------- |
169
+ | `--inspect[=<host:port>]` | Start the inspector; code runs immediately |
170
+ | `--inspect-wait[=<host:port>]` | Wait for a debugger to attach before running |
171
+ | `--inspect-brk[=<host:port>]` | Wait for a debugger to attach, then break on the first line |
172
+
173
+ ### CPU profiling
174
+
175
+ Open the **Performance** panel and click **Record**. Stop recording when done.
176
+
177
+ ### Heap allocation profiling
178
+
179
+ Open the **Memory** panel, select **Allocation sampling**, and click **Start**.
180
+ Stop when done to see allocation hot spots by call stack.
181
+
182
+ ### Heap snapshots
183
+
184
+ Open the **Memory** panel, select **Heap snapshot**, and click **Take
185
+ snapshot**.
186
+
187
+ ## Safari Web Inspector
188
+
189
+ Safari's Web Inspector records a timeline that combines CPU sampling, browser
190
+ activity, and optionally memory readings and heap allocations, all exported as a
191
+ single file.
192
+
193
+ ### Connecting
194
+
195
+ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
196
+
197
+ ### Recording
198
+
199
+ 1. Click the **Timelines** tab.
200
+ 2. Enable the instruments you want: **JavaScript & Events** (always), and
201
+ optionally **Memory** and **JavaScript Allocations**.
202
+ 3. Click **Start Recording** (or ⌘R).
203
+ 4. Reproduce the scenario you want to profile.
204
+ 5. Click **Stop Recording**.
205
+ 6. Click the **Export** button (arrow icon) and save as a `.json` file.
206
+
207
+ ### Heap snapshots
208
+
209
+ Open the **Memory** panel, select **Heap Snapshot**, and click **Take
210
+ Snapshot**.
211
+
212
+ #### Programmatic API
213
+
214
+ `console.takeHeapSnapshot()` is a non-standard WebKit extension that takes a
215
+ heap snapshot from JavaScript and adds it to the **Memory** panel:
216
+
217
+ ```js
218
+ console.takeHeapSnapshot()
219
+ ```
@@ -0,0 +1,31 @@
1
+ # PHP
2
+
3
+ PHP profiling uses [phpspy](https://github.com/adsr/phpspy), a low overhead
4
+ sampling profiler for PHP processes.
5
+
6
+ ## CPU profiling
7
+
8
+ Periodically samples the call stack. Useful for finding CPU hot spots.
9
+
10
+ ```sh
11
+ # Profile a command (speedscope format)
12
+ phpspy -d 30 --output-format=speedscope -f cpu.speedscope -- php script.php
13
+
14
+ # Attach to a running process (speedscope format)
15
+ phpspy -d 30 --output-format=speedscope --pid <pid> -f cpu.speedscope
16
+
17
+ # Attach to a running process (callgrind format, for KCachegrind)
18
+ phpspy -d 30 --output-format=callgrind --pid <pid> > cpu.callgrind
19
+ ```
20
+
21
+ ### Flags
22
+
23
+ | Flag | Default | Description |
24
+ | -------------------- | ------- | ------------------------------------------------------------------ |
25
+ | `--pid` / `-p` | — | PID of the PHP process to profile |
26
+ | `--duration` / `-d` | — | Duration in seconds; profiles indefinitely when not set |
27
+ | `--sleep-us` / `-s` | `10000` | Sampling interval in microseconds |
28
+ | `--num-samples` | — | Maximum number of samples to collect |
29
+ | `--max-depth` / `-l` | `64` | Maximum stack frames per sample |
30
+ | `--output-format` | `raw` | Output format: `raw`, `callgrind`, `speedscope`, `valgrind`, `rep` |
31
+ | `--output-file` | stdout | Write output to this file instead of stdout |
@@ -0,0 +1,112 @@
1
+ # Python
2
+
3
+ Python profiling uses [py-spy](https://github.com/benford/py-spy), a sampling
4
+ profiler that attaches to a running process or wraps a script, and
5
+ [memray](https://github.com/bloomberg/memray) for memory profiling.
6
+
7
+ ## CPU profiling
8
+
9
+ Periodically samples the call stack. Useful for finding CPU hot spots.
10
+
11
+ ```sh
12
+ # pprof format (wrap a script)
13
+ py-spy record -f pprof -o cpu.pprof -- python script.py
14
+
15
+ # pprof format (attach to a running process)
16
+ py-spy record -f pprof -o cpu.pprof --pid <pid>
17
+
18
+ # Speedscope format
19
+ py-spy record -f speedscope -o profile.speedscope -- python script.py
20
+
21
+ # Include native extensions written in Cython or C
22
+ py-spy record -f pprof -o cpu.pprof --native -- python script.py
23
+ ```
24
+
25
+ ## Wall-clock profiling
26
+
27
+ Samples wall-clock time rather than CPU time. Useful for I/O-bound code where
28
+ threads spend time sleeping or waiting.
29
+
30
+ ```sh
31
+ # Wrap a script
32
+ py-spy record -f pprof -o profile.pprof --idle -- python script.py
33
+
34
+ # Attach to a running process
35
+ py-spy record -f pprof -o profile.pprof --idle --pid <pid>
36
+ ```
37
+
38
+ ## Memory profiling
39
+
40
+ Tracks heap allocations. Useful for finding allocation hot spots and memory
41
+ leaks.
42
+
43
+ ### CLI
44
+
45
+ ```sh
46
+ # Record a memory profile (wrap a script)
47
+ memray run -o mem.bin script.py
48
+
49
+ # Attach to a running process
50
+ memray attach -o mem.bin <pid>
51
+
52
+ # Convert to pprof format
53
+ memray pprof mem.bin
54
+ ```
55
+
56
+ ### Programmatic API
57
+
58
+ ```python
59
+ import memray
60
+
61
+ with memray.Tracker("mem.bin"):
62
+ # Code to profile...
63
+ pass
64
+ ```
65
+
66
+ ## Call stack dump
67
+
68
+ Captures the current call stacks of all threads in a running process. Useful for
69
+ diagnosing hangs, deadlocks, or unexpected blocking.
70
+
71
+ ### CLI
72
+
73
+ ```sh
74
+ # Dump call stacks of a running process (text output)
75
+ py-spy dump --pid <pid>
76
+
77
+ # Include local variables in each frame
78
+ py-spy dump --pid <pid> --locals
79
+ ```
80
+
81
+ ### Programmatic API
82
+
83
+ ```python
84
+ import faulthandler
85
+
86
+ faulthandler.dump_traceback() # all threads to stderr
87
+ ```
88
+
89
+ ## CLI flags
90
+
91
+ ### `py-spy`
92
+
93
+ | Flag | Default | Description |
94
+ | ------------------- | ------------ | ---------------------------------------------------------- |
95
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`, `pprof` |
96
+ | `-o` / `--output` | — | Output file path |
97
+ | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
98
+ | `-r` / `--rate` | `100` | Sampling rate in Hz |
99
+ | `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
100
+ | `--native` | off | Profile native extensions written in Cython or C |
101
+ | `--nonblocking` | off | Don't pause the process to collect samples (less accurate) |
102
+ | `--subprocesses` | off | Also profile subprocesses of the target |
103
+
104
+ ### `memray`
105
+
106
+ | Flag | Default | Description |
107
+ | --------------------------- | ------- | --------------------------------------------------- |
108
+ | `-o` / `--output` | — | Output file path |
109
+ | `--native` | off | Also capture native (C extension) stack frames |
110
+ | `--follow-fork` | off | Also profile child processes after `fork()` |
111
+ | `--aggregate` | off | Aggregate allocations to reduce output file size |
112
+ | `--trace-python-allocators` | off | Trace Python allocator calls for finer-grained data |
@@ -0,0 +1,67 @@
1
+ # Ruby
2
+
3
+ Ruby profiling uses [rbspy](https://rbspy.github.io), a sampling profiler that
4
+ attaches to a running Ruby process.
5
+
6
+ ## CPU profiling
7
+
8
+ Periodically samples the call stack. Useful for finding CPU hot spots.
9
+
10
+ ### CLI
11
+
12
+ ```sh
13
+ # Profile a command (speedscope format)
14
+ rbspy record --format speedscope -o profile.speedscope -- ruby script.rb
15
+
16
+ # Attach to a running process
17
+ rbspy record --format speedscope -o profile.speedscope --pid <pid>
18
+
19
+ # Profile for a fixed duration
20
+ rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
21
+
22
+ # Profile including child processes
23
+ rbspy record --format speedscope -o profile.speedscope --subprocesses --pid <pid>
24
+ ```
25
+
26
+ ## Memory profiling
27
+
28
+ Records RSS memory alongside call stack samples. Useful for correlating memory
29
+ growth with specific code paths.
30
+
31
+ ### CLI
32
+
33
+ ```sh
34
+ # Record CPU and memory together
35
+ rbspy record --memory --format speedscope -o profile.speedscope --pid <pid>
36
+
37
+ # Profile a command with memory tracking
38
+ rbspy record --memory --format speedscope -o profile.speedscope -- ruby script.rb
39
+ ```
40
+
41
+ ## Snapshot
42
+
43
+ Captures a single stack trace from a running process. Useful for quickly
44
+ checking what a process is currently executing without starting a full
45
+ recording.
46
+
47
+ ### CLI
48
+
49
+ ```sh
50
+ rbspy snapshot --pid <pid>
51
+
52
+ # Don't pause the process while reading its stack
53
+ rbspy snapshot --nonblocking --pid <pid>
54
+ ```
55
+
56
+ ## CLI flags
57
+
58
+ | Flag | Default | Description |
59
+ | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
60
+ | `-p` / `--pid` | — | PID of a running process to attach to |
61
+ | `-d` / `--duration` | — | Duration in seconds; records until Ctrl-C if omitted |
62
+ | `-r` / `--rate` | `100` | Samples per second |
63
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `speedscope`, `callgrind`, `summary`, `summary_by_line`, `raw_call_stack` |
64
+ | `-o` / `--file` | — | Output file path |
65
+ | `-m` / `--memory` | — | Also record RSS memory usage alongside stack samples |
66
+ | `--subprocesses` | — | Also profile child processes |
67
+ | `--nonblocking` | — | Don't pause the process while reading its stack (lower overhead, may miss frames) |
@@ -0,0 +1,44 @@
1
+ # Rust
2
+
3
+ Rust CPU profiling uses [pprof-rs](https://github.com/tikv/pprof-rs), a sampling
4
+ profiler that integrates directly into your binary.
5
+
6
+ ## CPU profiling
7
+
8
+ Periodically samples the call stack. Useful for finding CPU hot spots.
9
+
10
+ Add to `Cargo.toml`:
11
+
12
+ ```toml
13
+ [dependencies]
14
+ pprof = { version = "...", features = ["prost-codec", "frame-pointer"] }
15
+ ```
16
+
17
+ The `frame-pointer` feature is required on macOS (the default stack unwinder
18
+ crashes with SIGBUS). Also add the following rustflag to make frame-pointer
19
+ unwinding reliable:
20
+
21
+ ```sh
22
+ RUSTFLAGS="-C force-frame-pointers=yes" cargo build ...
23
+ ```
24
+
25
+ ```rust
26
+ use pprof::protos::Message;
27
+
28
+ let guard = pprof::ProfilerGuardBuilder::default()
29
+ .frequency(1000)
30
+ .build()?;
31
+
32
+ // Code to profile...
33
+
34
+ let mut buf = Vec::new();
35
+ guard.report().build()?.pprof()?.encode(&mut buf)?;
36
+ std::fs::write("cpu.pprof", &buf)?;
37
+ ```
38
+
39
+ ### `ProfilerGuardBuilder` options
40
+
41
+ | Method | Default | Description |
42
+ | -------------------- | ------- | ---------------------------------------- |
43
+ | `.frequency(hz)` | `100` | Samples per second |
44
+ | `.blocklist(frames)` | `[]` | Stack frames to exclude from the profile |