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
|
@@ -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 |
|