profiler-md 0.3.0 → 0.5.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.
Files changed (225) hide show
  1. package/dist/cli/index.mjs +5331 -2044
  2. package/dist/index.d.mts +738 -229
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/formats/jfr.md +16 -0
  6. package/docs/formats/jsc-heap-snapshot.md +2 -2
  7. package/docs/languages/c.md +31 -7
  8. package/docs/languages/cpp.md +160 -0
  9. package/docs/languages/csharp.md +52 -0
  10. package/docs/languages/elixir.md +46 -0
  11. package/docs/languages/erlang.md +46 -0
  12. package/docs/languages/fsharp.md +52 -0
  13. package/docs/languages/go.md +11 -6
  14. package/docs/languages/java.md +110 -57
  15. package/docs/languages/javascript.md +69 -12
  16. package/docs/languages/julia.md +54 -0
  17. package/docs/languages/kotlin.md +170 -0
  18. package/docs/languages/php.md +64 -20
  19. package/docs/languages/python.md +13 -68
  20. package/docs/languages/ruby.md +17 -27
  21. package/docs/languages/typescript.md +276 -0
  22. package/examples/output/c.gperftools.cpu.base.pprof.md +324 -0
  23. package/examples/output/c.gperftools.cpu.current.pprof.md +271 -0
  24. package/examples/output/c.gperftools.cpu.diff.pprof.md +98 -0
  25. package/examples/output/c.gperftools.heap.base.pprof.md +362 -0
  26. package/examples/output/c.gperftools.heap.current.pprof.md +362 -0
  27. package/examples/output/c.gperftools.heap.diff.pprof.md +28 -0
  28. package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
  29. package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
  30. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
  31. package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
  32. package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
  33. package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
  34. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
  35. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
  36. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
  37. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
  38. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
  39. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
  40. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
  41. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
  42. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
  43. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
  44. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
  45. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
  46. package/examples/output/go.pprof.block.base.pprof.md +86 -0
  47. package/examples/output/go.pprof.block.current.pprof.md +83 -0
  48. package/examples/output/go.pprof.block.diff.pprof.md +42 -0
  49. package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
  50. package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
  51. package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
  52. package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
  53. package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
  54. package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
  55. package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
  56. package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
  57. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
  58. package/examples/output/go.pprof.heap.base.pprof.md +154 -0
  59. package/examples/output/go.pprof.heap.current.pprof.md +146 -0
  60. package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
  61. package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
  62. package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
  63. package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
  64. package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
  65. package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
  66. package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
  67. package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
  68. package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
  69. package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
  70. package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
  71. package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
  72. package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
  73. package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
  74. package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
  75. package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
  76. package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
  77. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
  78. package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
  79. package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
  80. package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
  81. package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
  82. package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
  83. package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
  84. package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
  85. package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
  86. package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
  87. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
  88. package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
  89. package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
  90. package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
  91. package/examples/output/java.jdk.all.base.jfr.md +1024 -0
  92. package/examples/output/java.jdk.all.current.jfr.md +1010 -0
  93. package/examples/output/java.jdk.all.diff.jfr.md +311 -0
  94. package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
  95. package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
  96. package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
  97. package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
  98. package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
  99. package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
  100. package/examples/output/java.jdk.live.base.jfr.md +1029 -0
  101. package/examples/output/java.jdk.live.current.jfr.md +1035 -0
  102. package/examples/output/java.jdk.live.diff.jfr.md +289 -0
  103. package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
  104. package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
  105. package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
  106. package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
  107. package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
  108. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
  109. package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
  110. package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
  111. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
  112. package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
  113. package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
  114. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
  115. package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
  116. package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
  117. package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
  118. package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
  119. package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
  120. package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
  121. package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
  122. package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
  123. package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
  124. package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
  125. package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
  126. package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
  127. package/examples/output/javascript.node.base.cpuprofile.md +136 -0
  128. package/examples/output/javascript.node.base.heapprofile.md +56 -0
  129. package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
  130. package/examples/output/javascript.node.current.cpuprofile.md +119 -0
  131. package/examples/output/javascript.node.current.heapprofile.md +52 -0
  132. package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
  133. package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
  134. package/examples/output/javascript.node.diff.heapprofile.md +34 -0
  135. package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
  136. package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
  137. package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
  138. package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
  139. package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
  140. package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
  141. package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
  142. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
  143. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
  144. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
  145. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
  146. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
  147. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
  148. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
  149. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
  150. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
  151. package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
  152. package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
  153. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
  154. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
  155. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
  156. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
  157. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
  158. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
  159. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
  160. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
  161. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
  162. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
  163. package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
  164. package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
  165. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
  166. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
  167. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
  168. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
  169. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
  170. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
  171. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
  172. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
  173. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
  174. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
  175. package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
  176. package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
  177. package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
  178. package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
  179. package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
  180. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
  181. package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
  182. package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
  183. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
  184. package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
  185. package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
  186. package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
  187. package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
  188. package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
  189. package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
  190. package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
  191. package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
  192. package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
  193. package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
  194. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
  195. package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
  196. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
  197. package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
  198. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
  199. package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
  200. package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
  201. package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
  202. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
  203. package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
  204. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
  205. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
  206. package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
  207. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
  208. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
  209. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
  210. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
  211. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
  212. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
  213. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
  214. package/package.json +27 -20
  215. package/readme.md +201 -87
  216. package/examples/bun.cpuprofile.md +0 -475
  217. package/examples/deno.cpuprofile.md +0 -481
  218. package/examples/jsc-heap-snapshot.json.md +0 -509
  219. package/examples/node.cpuprofile.md +0 -485
  220. package/examples/node.heapprofile.md +0 -281
  221. package/examples/node.heapsnapshot.md +0 -694
  222. package/examples/node.pprof.md +0 -441
  223. package/examples/node.speedscope.json.md +0 -408
  224. package/examples/rust.pprof.md +0 -477
  225. package/examples/webkit-timeline-recording.json.md +0 -434
@@ -1,66 +1,33 @@
1
1
  # Python
2
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.
3
+ Python profiling uses [py-spy](https://github.com/benfred/py-spy), a sampling
4
+ profiler that attaches to a running process or wraps a script.
6
5
 
7
6
  ## CPU profiling
8
7
 
9
8
  Periodically samples the call stack. Useful for finding CPU hot spots.
10
9
 
11
10
  ```sh
12
- # pprof format (wrap a script)
13
- py-spy record -f pprof -o cpu.pprof -- python script.py
11
+ # Collapsed format (wrap a script)
12
+ py-spy record -f raw -o cpu.collapsed -- python script.py
14
13
 
15
- # pprof format (attach to a running process)
16
- py-spy record -f pprof -o cpu.pprof --pid <pid>
14
+ # Speedscope format (wrap a script)
15
+ py-spy record -f speedscope -o cpu.speedscope.json -- python script.py
17
16
 
18
- # Speedscope format
19
- py-spy record -f speedscope -o profile.speedscope -- python script.py
17
+ # Attach to a running process
18
+ py-spy record -f raw -o cpu.collapsed --pid <pid>
20
19
 
21
20
  # Include native extensions written in Cython or C
22
- py-spy record -f pprof -o cpu.pprof --native -- python script.py
21
+ py-spy record -f raw -o cpu.collapsed --native -- python script.py
23
22
  ```
24
23
 
25
24
  ## Wall-clock profiling
26
25
 
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
26
+ Samples wall-clock time rather than CPU time, including time threads spend
27
+ waiting. Useful for I/O-bound or latency-sensitive code.
44
28
 
45
29
  ```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
30
+ py-spy record -f raw -o wall.collapsed --idle -- python script.py
64
31
  ```
65
32
 
66
33
  ## Call stack dump
@@ -68,8 +35,6 @@ with memray.Tracker("mem.bin"):
68
35
  Captures the current call stacks of all threads in a running process. Useful for
69
36
  diagnosing hangs, deadlocks, or unexpected blocking.
70
37
 
71
- ### CLI
72
-
73
38
  ```sh
74
39
  # Dump call stacks of a running process (text output)
75
40
  py-spy dump --pid <pid>
@@ -78,21 +43,11 @@ py-spy dump --pid <pid>
78
43
  py-spy dump --pid <pid> --locals
79
44
  ```
80
45
 
81
- ### Programmatic API
82
-
83
- ```python
84
- import faulthandler
85
-
86
- faulthandler.dump_traceback() # all threads to stderr
87
- ```
88
-
89
46
  ## CLI flags
90
47
 
91
- ### `py-spy`
92
-
93
48
  | Flag | Default | Description |
94
49
  | ------------------- | ------------ | ---------------------------------------------------------- |
95
- | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`, `pprof` |
50
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope` |
96
51
  | `-o` / `--output` | — | Output file path |
97
52
  | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
98
53
  | `-r` / `--rate` | `100` | Sampling rate in Hz |
@@ -100,13 +55,3 @@ faulthandler.dump_traceback() # all threads to stderr
100
55
  | `--native` | off | Profile native extensions written in Cython or C |
101
56
  | `--nonblocking` | off | Don't pause the process to collect samples (less accurate) |
102
57
  | `--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 |
@@ -11,10 +11,16 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
11
11
 
12
12
  ```sh
13
13
  # Profile a command (speedscope format)
14
- rbspy record --format speedscope -o profile.speedscope -- ruby script.rb
14
+ rbspy record --format speedscope -o cpu.speedscope.json -- ruby script.rb
15
+
16
+ # Collapsed stacks
17
+ rbspy record --format collapsed -o cpu.collapsed -- ruby script.rb
18
+
19
+ # pprof
20
+ rbspy record --format pprof -o cpu.pprof -- ruby script.rb
15
21
 
16
22
  # Attach to a running process
17
- rbspy record --format speedscope -o profile.speedscope --pid <pid>
23
+ rbspy record --format speedscope -o cpu.speedscope.json --pid <pid>
18
24
 
19
25
  # Profile for a fixed duration
20
26
  rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
@@ -23,21 +29,6 @@ rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
23
29
  rbspy record --format speedscope -o profile.speedscope --subprocesses --pid <pid>
24
30
  ```
25
31
 
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
32
  ## Snapshot
42
33
 
43
34
  Captures a single stack trace from a running process. Useful for quickly
@@ -55,13 +46,12 @@ rbspy snapshot --nonblocking --pid <pid>
55
46
 
56
47
  ## CLI flags
57
48
 
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) |
49
+ | Flag | Default | Description |
50
+ | ------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
51
+ | `-p` / `--pid` | — | PID of a running process to attach to |
52
+ | `-d` / `--duration` | — | Duration in seconds; records until Ctrl-C if omitted |
53
+ | `-r` / `--rate` | `100` | Samples per second |
54
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `collapsed`, `pprof`, `speedscope`, `callgrind`, `summary`, `summary_by_line` |
55
+ | `-o` / `--file` | — | Output file path |
56
+ | `--subprocesses` | — | Also profile child processes |
57
+ | `--nonblocking` | — | Don't pause the process while reading its stack (lower overhead, may miss frames) |
@@ -0,0 +1,276 @@
1
+ # JavaScript
2
+
3
+ Profile JavaScript across Node.js, Deno, Bun, Chrome, and Safari, capturing CPU
4
+ profiles, heap profiles, and heap snapshots in V8 and JavaScriptCore formats.
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 V8 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
+ `node:v8`'s `writeHeapSnapshot` writes a V8-format snapshot and works in
131
+ Node.js, Deno, and Bun:
132
+
133
+ ```js
134
+ import { writeHeapSnapshot } from 'node:v8'
135
+
136
+ // Code to capture...
137
+ writeHeapSnapshot(`heap.heapsnapshot`)
138
+ ```
139
+
140
+ Bun also offers
141
+ [`Bun.generateHeapSnapshot()`](https://bun.com/reference/bun/generateHeapSnapshot),
142
+ which emits _both_ heap snapshot formats, selectable by argument:
143
+
144
+ ```js
145
+ import { generateHeapSnapshot } from 'bun'
146
+
147
+ const jsc = generateHeapSnapshot() // Or generateHeapSnapshot(`jsc`)
148
+ await Bun.write(`heap.json`, JSON.stringify(jsc))
149
+
150
+ const v8 = generateHeapSnapshot(`v8`)
151
+ await Bun.write(`heap.heapsnapshot`, v8)
152
+ ```
153
+
154
+ ## pprof
155
+
156
+ Node.js can also emit [pprof](https://github.com/google/pprof) profiles via the
157
+ [`@datadog/pprof`](https://www.npmjs.com/package/@datadog/pprof) package, which
158
+ profiles a section of code rather than the whole process.
159
+
160
+ ### CPU profiling
161
+
162
+ Samples wall-clock time across all threads. Useful for finding CPU hot spots and
163
+ time spent waiting.
164
+
165
+ ```js
166
+ import { writeFile } from 'node:fs/promises'
167
+ import { encode, time } from '@datadog/pprof'
168
+
169
+ const profile = await time.profile({ durationMillis: 10_000 })
170
+ await writeFile(`cpu.pb.gz`, await encode(profile))
171
+ ```
172
+
173
+ ### Memory profiling
174
+
175
+ Samples heap allocations by stack trace. Useful for finding allocation hot spots
176
+ and reducing GC pressure.
177
+
178
+ ```js
179
+ import { writeFile } from 'node:fs/promises'
180
+ import { encode, heap } from '@datadog/pprof'
181
+
182
+ heap.start(512 * 1024, 64) // Sampling interval in bytes, max stack depth
183
+
184
+ // Code to profile...
185
+
186
+ await writeFile(`heap.pb.gz`, await encode(await heap.profile()))
187
+ ```
188
+
189
+ ## Chrome DevTools
190
+
191
+ Chrome DevTools can profile JavaScript running in the browser or connected to
192
+ Node.js or Deno via `--inspect`. The panels and workflow are identical.
193
+
194
+ ### Connecting
195
+
196
+ **In the browser:** open DevTools with ⌥⌘I (macOS) or Ctrl+Shift+I
197
+ (Windows/Linux).
198
+
199
+ **Via `--inspect` (Node.js, Deno):** start the process with the inspector
200
+ enabled, then open `chrome://inspect` in Chrome and click **Open dedicated
201
+ DevTools for Node**.
202
+
203
+ ```sh
204
+ # Node.js (default port 9229)
205
+ node --inspect script.js
206
+
207
+ # Deno (default port 9229)
208
+ deno run --inspect script.ts
209
+ ```
210
+
211
+ #### Flags (all runtimes)
212
+
213
+ | Flag | Description |
214
+ | ------------------------------ | ----------------------------------------------------------- |
215
+ | `--inspect[=<host:port>]` | Start the inspector; code runs immediately |
216
+ | `--inspect-wait[=<host:port>]` | Wait for a debugger to attach before running |
217
+ | `--inspect-brk[=<host:port>]` | Wait for a debugger to attach, then break on the first line |
218
+
219
+ ### CPU profiling
220
+
221
+ Open the **Performance** panel and click **Record**. Stop recording when done.
222
+
223
+ ### Heap allocation profiling
224
+
225
+ Open the **Memory** panel, select **Allocation sampling**, and click **Start**.
226
+ Stop when done to see allocation hot spots by call stack.
227
+
228
+ ### Heap snapshots
229
+
230
+ Open the **Memory** panel, select **Heap snapshot**, and click **Take
231
+ snapshot**.
232
+
233
+ ## debug.bun.sh
234
+
235
+ Bun's inspector speaks the WebKit Inspector Protocol rather than V8's, so it
236
+ connects through [debug.bun.sh](https://debug.bun.sh) instead of Chrome
237
+ DevTools. Start the process with `--inspect` and open the URL printed to stderr.
238
+
239
+ ```sh
240
+ # Bun (auto-assigned port)
241
+ bun --inspect script.ts
242
+ ```
243
+
244
+ ## Safari Web Inspector
245
+
246
+ Safari's Web Inspector records a timeline that combines CPU sampling, browser
247
+ activity, and optionally memory readings and heap allocations, all exported as a
248
+ single file.
249
+
250
+ ### Connecting
251
+
252
+ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
253
+
254
+ ### Recording
255
+
256
+ 1. Click the **Timelines** tab.
257
+ 2. Enable the instruments you want: **JavaScript & Events** (always), and
258
+ optionally **Memory** and **JavaScript Allocations**.
259
+ 3. Click **Start Recording** (or ⌘R).
260
+ 4. Reproduce the scenario you want to profile.
261
+ 5. Click **Stop Recording**.
262
+ 6. Click the **Export** button (arrow icon) and save as a `.json` file.
263
+
264
+ ### Heap snapshots
265
+
266
+ Open the **Memory** panel, select **Heap Snapshot**, and click **Take
267
+ Snapshot**.
268
+
269
+ #### Programmatic API
270
+
271
+ `console.takeHeapSnapshot()` is a non-standard WebKit extension that takes a
272
+ heap snapshot from JavaScript and adds it to the **Memory** panel:
273
+
274
+ ```js
275
+ console.takeHeapSnapshot()
276
+ ```