profiler-md 0.4.0 → 0.6.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 (247) hide show
  1. package/dist/cli/index.mjs +5512 -2297
  2. package/dist/index.d.mts +974 -62
  3. package/dist/index.js +2 -2
  4. package/docs/formats/jfr.md +16 -0
  5. package/docs/formats/jsc-heap-snapshot.md +3 -3
  6. package/docs/formats/pprof.md +8 -6
  7. package/docs/formats/speedscope.md +5 -4
  8. package/docs/formats/systing.md +25 -0
  9. package/docs/formats/v8-heap-snapshot.md +2 -2
  10. package/docs/languages/c.md +66 -9
  11. package/docs/languages/csharp.md +4 -3
  12. package/docs/languages/elixir.md +10 -7
  13. package/docs/languages/go.md +17 -12
  14. package/docs/languages/java.md +110 -60
  15. package/docs/languages/javascript.md +41 -19
  16. package/docs/languages/julia.md +103 -12
  17. package/docs/languages/php.md +63 -20
  18. package/docs/languages/python.md +35 -81
  19. package/docs/languages/ruby.md +20 -32
  20. package/docs/languages/rust.md +37 -8
  21. package/examples/output/c.gperftools.cpu.base.pprof.md +324 -0
  22. package/examples/output/c.gperftools.cpu.current.pprof.md +271 -0
  23. package/examples/output/c.gperftools.cpu.diff.pprof.md +98 -0
  24. package/examples/output/c.gperftools.heap.base.pprof.md +362 -0
  25. package/examples/output/c.gperftools.heap.current.pprof.md +362 -0
  26. package/examples/output/c.gperftools.heap.diff.pprof.md +28 -0
  27. package/examples/output/c.systing.cpu.base.systing.md +824 -0
  28. package/examples/output/c.systing.cpu.current.systing.md +825 -0
  29. package/examples/output/c.systing.cpu.diff.systing.md +238 -0
  30. package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
  31. package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
  32. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
  33. package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
  34. package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
  35. package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
  36. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
  37. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
  38. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
  39. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
  40. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
  41. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
  42. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
  43. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
  44. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
  45. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
  46. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
  47. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
  48. package/examples/output/go.pprof.block.base.pprof.md +86 -0
  49. package/examples/output/go.pprof.block.current.pprof.md +83 -0
  50. package/examples/output/go.pprof.block.diff.pprof.md +42 -0
  51. package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
  52. package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
  53. package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
  54. package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
  55. package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
  56. package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
  57. package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
  58. package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
  59. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
  60. package/examples/output/go.pprof.heap.base.pprof.md +154 -0
  61. package/examples/output/go.pprof.heap.current.pprof.md +146 -0
  62. package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
  63. package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
  64. package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
  65. package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
  66. package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
  67. package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
  68. package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
  69. package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
  70. package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
  71. package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
  72. package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
  73. package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
  74. package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
  75. package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
  76. package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
  77. package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
  78. package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
  79. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
  80. package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
  81. package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
  82. package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
  83. package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
  84. package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
  85. package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
  86. package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
  87. package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
  88. package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
  89. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
  90. package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
  91. package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
  92. package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
  93. package/examples/output/java.jdk.all.base.jfr.md +1024 -0
  94. package/examples/output/java.jdk.all.current.jfr.md +1010 -0
  95. package/examples/output/java.jdk.all.diff.jfr.md +311 -0
  96. package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
  97. package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
  98. package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
  99. package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
  100. package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
  101. package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
  102. package/examples/output/java.jdk.live.base.jfr.md +1029 -0
  103. package/examples/output/java.jdk.live.current.jfr.md +1035 -0
  104. package/examples/output/java.jdk.live.diff.jfr.md +289 -0
  105. package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
  106. package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
  107. package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
  108. package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
  109. package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
  110. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
  111. package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
  112. package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
  113. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
  114. package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
  115. package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
  116. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
  117. package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
  118. package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
  119. package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
  120. package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
  121. package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
  122. package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
  123. package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
  124. package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
  125. package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
  126. package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
  127. package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
  128. package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
  129. package/examples/output/javascript.node.base.cpuprofile.md +136 -0
  130. package/examples/output/javascript.node.base.heapprofile.md +56 -0
  131. package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
  132. package/examples/output/javascript.node.current.cpuprofile.md +119 -0
  133. package/examples/output/javascript.node.current.heapprofile.md +52 -0
  134. package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
  135. package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
  136. package/examples/output/javascript.node.diff.heapprofile.md +34 -0
  137. package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
  138. package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
  139. package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
  140. package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
  141. package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
  142. package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
  143. package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
  144. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
  145. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
  146. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
  147. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
  148. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
  149. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
  150. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
  151. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
  152. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
  153. package/examples/output/julia.pprof-jl.wall.base.pprof.md +181 -0
  154. package/examples/output/julia.pprof-jl.wall.current.pprof.md +193 -0
  155. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +64 -0
  156. package/examples/output/julia.profile.base.heapsnapshot.md +590 -0
  157. package/examples/output/julia.profile.current.heapsnapshot.md +590 -0
  158. package/examples/output/julia.profile.diff.heapsnapshot.md +288 -0
  159. package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
  160. package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
  161. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
  162. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
  163. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
  164. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
  165. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
  166. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
  167. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
  168. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
  169. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
  170. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
  171. package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
  172. package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
  173. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
  174. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
  175. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
  176. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
  177. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
  178. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
  179. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
  180. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
  181. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
  182. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
  183. package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
  184. package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
  185. package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
  186. package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
  187. package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
  188. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
  189. package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
  190. package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
  191. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
  192. package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
  193. package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
  194. package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
  195. package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
  196. package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
  197. package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
  198. package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
  199. package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
  200. package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
  201. package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
  202. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
  203. package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
  204. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
  205. package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
  206. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
  207. package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
  208. package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
  209. package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
  210. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
  211. package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
  212. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
  213. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
  214. package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
  215. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
  216. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
  217. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
  218. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
  219. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
  220. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
  221. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
  222. package/package.json +17 -12
  223. package/readme.md +158 -48
  224. package/skills/profile-optimize/SKILL.md +160 -0
  225. package/docs/languages/cpp.md +0 -136
  226. package/docs/languages/erlang.md +0 -42
  227. package/docs/languages/fsharp.md +0 -49
  228. package/docs/languages/kotlin.md +0 -120
  229. package/docs/languages/typescript.md +0 -254
  230. package/examples/bun.cpuprofile.md +0 -475
  231. package/examples/deno.cpuprofile.md +0 -481
  232. package/examples/jsc-heap-snapshot.base.json.md +0 -507
  233. package/examples/jsc-heap-snapshot.current.json.md +0 -504
  234. package/examples/jsc-heap-snapshot.diff.json.md +0 -119
  235. package/examples/node.base.cpuprofile.md +0 -451
  236. package/examples/node.current.cpuprofile.md +0 -449
  237. package/examples/node.diff.cpuprofile.md +0 -82
  238. package/examples/node.heapprofile.md +0 -281
  239. package/examples/node.heapsnapshot.md +0 -694
  240. package/examples/node.pprof.md +0 -441
  241. package/examples/python.base.collapsed.md +0 -116
  242. package/examples/python.current.collapsed.md +0 -125
  243. package/examples/python.diff.collapsed.md +0 -51
  244. package/examples/rust.base.pprof.md +0 -477
  245. package/examples/rust.current.pprof.md +0 -480
  246. package/examples/rust.diff.pprof.md +0 -117
  247. package/examples/webkit-timeline-recording.json.md +0 -434
@@ -1,7 +1,7 @@
1
1
  # JavaScript
2
2
 
3
- Profiling JavaScript works across Node.js, Deno, Bun, and Chrome via V8 CPU
4
- profiles, V8 heap profiles, and V8 heap snapshots.
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
5
 
6
6
  ## CPU profiling
7
7
 
@@ -26,12 +26,12 @@ bun --cpu-prof script.ts
26
26
  | -------------------------- | ---------------------------------- | --------------------------------------------- |
27
27
  | `--cpu-prof` | — | Write a CPU profile on exit; enabled when set |
28
28
  | `--cpu-prof-interval=<µs>` | `1000` | Sampling interval in microseconds |
29
- | `--cpu-prof-dir=<dir>` | `.` | Directory to write the profile to |
29
+ | `--cpu-prof-dir=<dir>` | `.` | Directory for the profile |
30
30
  | `--cpu-prof-name=<name>` | `CPU.<timestamp>.<pid>.cpuprofile` | Filename for the profile |
31
31
 
32
32
  ### Programmatic API
33
33
 
34
- Profile a specific section of code rather than the whole process:
34
+ Profile a section of code rather than the whole process:
35
35
 
36
36
  ```js
37
37
  import { writeFileSync } from 'node:fs'
@@ -54,7 +54,7 @@ writeFileSync(`cpu.cpuprofile`, JSON.stringify(profile))
54
54
  Samples heap allocations by stack trace. Useful for finding allocation hot spots
55
55
  and reducing GC pressure.
56
56
 
57
- `bun --heap-prof` generates a heap _snapshot_ on exit, not a heap _profile_.
57
+ `bun --heap-prof` generates a V8 heap _snapshot_ on exit, not a heap _profile_.
58
58
  Deno has no equivalent.
59
59
 
60
60
  ### CLI
@@ -70,7 +70,7 @@ node --heap-prof script.js
70
70
  | ------------------------------ | -------- | ---------------------------------------------- |
71
71
  | `--heap-prof` | — | Write a heap profile on exit; enabled when set |
72
72
  | `--heap-prof-interval=<bytes>` | `524288` | Sampling interval in bytes (default 512 KB) |
73
- | `--heap-prof-dir=<dir>` | `.` | Directory to write the profile to |
73
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the profile |
74
74
  | `--heap-prof-name=<name>` | — | Filename for the profile |
75
75
 
76
76
  ### Programmatic API
@@ -122,11 +122,14 @@ bun --heap-prof script.ts
122
122
  | Flag | Default | Description |
123
123
  | ------------------------- | ------- | ----------------------------------------------- |
124
124
  | `--heap-prof` | — | Write a heap snapshot on exit; enabled when set |
125
- | `--heap-prof-dir=<dir>` | `.` | Directory to write the snapshot to |
125
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot |
126
126
  | `--heap-prof-name=<name>` | — | Filename for the snapshot |
127
127
 
128
128
  ### Programmatic API
129
129
 
130
+ `node:v8`'s `writeHeapSnapshot` writes a V8-format snapshot and works in
131
+ Node.js, Deno, and Bun:
132
+
130
133
  ```js
131
134
  import { writeHeapSnapshot } from 'node:v8'
132
135
 
@@ -134,6 +137,20 @@ import { writeHeapSnapshot } from 'node:v8'
134
137
  writeHeapSnapshot(`heap.heapsnapshot`)
135
138
  ```
136
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
+
137
154
  ## pprof
138
155
 
139
156
  Node.js can also emit [pprof](https://github.com/google/pprof) profiles via the
@@ -172,19 +189,16 @@ await writeFile(`heap.pb.gz`, await encode(await heap.profile()))
172
189
  ## Chrome DevTools
173
190
 
174
191
  Chrome DevTools can profile JavaScript running in the browser or connected to
175
- Node.js, Deno, or Bun via `--inspect`. The panels and workflow are the same in
176
- both cases.
192
+ Node.js or Deno via `--inspect`. The panels and workflow are identical.
177
193
 
178
194
  ### Connecting
179
195
 
180
196
  **In the browser:** open DevTools with ⌥⌘I (macOS) or Ctrl+Shift+I
181
197
  (Windows/Linux).
182
198
 
183
- **Via `--inspect` (Node.js, Deno, Bun):** start the process with the inspector
199
+ **Via `--inspect` (Node.js, Deno):** start the process with the inspector
184
200
  enabled, then open `chrome://inspect` in Chrome and click **Open dedicated
185
- DevTools for Node**. For Bun, open the URL printed to stderr in
186
- [debug.bun.sh](https://debug.bun.sh) — Bun uses the WebKit Inspector Protocol
187
- rather than V8's.
201
+ DevTools for Node**.
188
202
 
189
203
  ```sh
190
204
  # Node.js (default port 9229)
@@ -192,9 +206,6 @@ node --inspect script.js
192
206
 
193
207
  # Deno (default port 9229)
194
208
  deno run --inspect script.ts
195
-
196
- # Bun (auto-assigned port)
197
- bun --inspect script.ts
198
209
  ```
199
210
 
200
211
  #### Flags (all runtimes)
@@ -219,6 +230,17 @@ Stop when done to see allocation hot spots by call stack.
219
230
  Open the **Memory** panel, select **Heap snapshot**, and click **Take
220
231
  snapshot**.
221
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
+
222
244
  ## Safari Web Inspector
223
245
 
224
246
  Safari's Web Inspector records a timeline that combines CPU sampling, browser
@@ -232,10 +254,10 @@ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
232
254
  ### Recording
233
255
 
234
256
  1. Click the **Timelines** tab.
235
- 2. Enable the instruments you want: **JavaScript & Events** (always), and
236
- optionally **Memory** and **JavaScript Allocations**.
257
+ 2. Enable the instruments: **JavaScript & Events** (always), and optionally
258
+ **Memory** and **JavaScript Allocations**.
237
259
  3. Click **Start Recording** (or ⌘R).
238
- 4. Reproduce the scenario you want to profile.
260
+ 4. Reproduce the scenario to profile.
239
261
  5. Click **Stop Recording**.
240
262
  6. Click the **Export** button (arrow icon) and save as a `.json` file.
241
263
 
@@ -3,40 +3,131 @@
3
3
  Julia profiling uses [PProf.jl](https://github.com/JuliaPerf/PProf.jl), which
4
4
  exports profiles collected by Julia's built-in
5
5
  [`Profile`](https://docs.julialang.org/en/v1/manual/profile/) standard library
6
- to the pprof format.
6
+ to the pprof format. `Profile` can also write V8 heap snapshots directly.
7
7
 
8
8
  ## CPU profiling
9
9
 
10
- Periodically samples the call stack. Useful for finding CPU hot spots.
10
+ Periodically samples the call stacks of running tasks. Useful for finding CPU
11
+ hot spots.
11
12
 
12
13
  ```julia
13
14
  using Profile, PProf
14
15
 
16
+ # Warm up the JIT so the profile excludes compilation.
17
+ my_function()
18
+
15
19
  Profile.clear()
16
20
  @profile my_function()
17
21
 
18
- # Write profile.pb.gz without launching the web UI
19
- pprof(out = "cpu.pb.gz", web = false)
22
+ # `web = false` skips the UI. `from_c = false` drops C/runtime frames, leaving
23
+ # just your Julia code.
24
+ pprof(out = "cpu.pb.gz", web = false, from_c = false)
25
+ ```
26
+
27
+ ### Sampling settings
28
+
29
+ Samples every 1 ms by default (10 ms on Windows). Configure with `Profile.init`
30
+ before profiling; calling it with no arguments returns the current settings.
31
+
32
+ ```julia
33
+ Profile.init(n = 10^7, delay = 0.0005)
34
+ ```
35
+
36
+ | Option | Default | Description |
37
+ | ------- | ------- | --------------------------------------------------- |
38
+ | `n` | `10^6` | Buffer capacity in instruction pointers, per thread |
39
+ | `delay` | `0.001` | Seconds between samples |
40
+
41
+ If profiling warns that the buffer filled up, increase `n` or `delay` and
42
+ re-run.
43
+
44
+ ## Wall-time profiling
45
+
46
+ Periodically samples all live tasks regardless of scheduling state (Julia ≥
47
+ 1.12). Unlike CPU profiling, it samples blocked tasks too, counting time spent
48
+ waiting on IO, locks, channels, and the scheduler. Useful for I/O-bound or
49
+ latency-sensitive code.
50
+
51
+ ```julia
52
+ using Profile, PProf
53
+
54
+ # Warm up the JIT so the profile excludes compilation.
55
+ my_function()
56
+
57
+ Profile.clear()
58
+ Profile.@profile_walltime my_function()
59
+
60
+ # Wall-time samples land in the same buffer as `@profile`, so the same call
61
+ # exports them. Always `Profile.clear()` between runs so CPU and wall-time
62
+ # samples don't mix.
63
+ pprof(out = "wall.pb.gz", web = false, from_c = false)
20
64
  ```
21
65
 
66
+ Samples containing `failed_to_sample_task_fun` or `failed_to_stop_thread_fun`
67
+ indicate many short-lived tasks that completed before their backtraces could be
68
+ collected.
69
+
22
70
  ## Memory profiling
23
71
 
24
- Samples heap allocations. Useful for finding allocation hot spots and reducing
25
- GC pressure.
72
+ Samples heap allocations (Julia ≥ 1.8). Useful for finding allocation hot spots
73
+ and reducing GC pressure.
26
74
 
27
75
  ```julia
28
76
  using Profile, PProf
29
77
 
78
+ # Warm up the JIT so the profile excludes compilation.
79
+ my_function()
80
+
30
81
  Profile.Allocs.clear()
31
- Profile.Allocs.@profile my_function()
82
+ Profile.Allocs.@profile sample_rate = 0.01 my_function()
32
83
 
33
84
  PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
34
85
  ```
35
86
 
87
+ `sample_rate` is the fraction of allocations recorded: `1.0` records every
88
+ allocation, the default `0.1` records ~10%. Allocation-heavy workloads allocate
89
+ millions of times, so lower the rate until the run's overhead and the profile's
90
+ size are reasonable.
91
+
92
+ ## Heap snapshots
93
+
94
+ Captures a snapshot of all live objects on the heap (Julia ≥ 1.9), written
95
+ directly in the V8 heap snapshot format. Useful for diagnosing memory leaks.
96
+
97
+ ```julia
98
+ using Profile
99
+
100
+ # Code to capture...
101
+ Profile.take_heap_snapshot("heap.heapsnapshot")
102
+ ```
103
+
104
+ ### Options
105
+
106
+ | Option | Default | Description |
107
+ | ------------- | ------- | ------------------------------------------------------------------------ |
108
+ | `redact_data` | `true` | Omit the contents of Julia strings |
109
+ | `streaming` | `false` | Stream four intermediate files instead of holding the snapshot in memory |
110
+
111
+ A snapshot spans the entire runtime heap: `Base`, method tables, and every
112
+ loaded package. Expect files of hundreds of megabytes even for small programs.
113
+ They compress well: profiler-md accepts them gzipped as-is. For
114
+ memory-constrained processes, pass `streaming = true` and reassemble afterwards
115
+ with `Profile.HeapSnapshot.assemble_snapshot(prefix, "heap.heapsnapshot")`.
116
+
36
117
  ## `pprof` options
37
118
 
38
- | Option | Default | Description |
39
- | -------- | ----------------- | --------------------------------------------- |
40
- | `out` | `"profile.pb.gz"` | Output file path |
41
- | `web` | `true` | Launch the interactive web UI after exporting |
42
- | `from_c` | `true` | Include C and Julia runtime frames |
119
+ | Option | Default | Description |
120
+ | ----------------- | ----------------- | ------------------------------------------------ |
121
+ | `out` | `"profile.pb.gz"` | Output file path |
122
+ | `web` | `true` | Launch the interactive web UI after exporting |
123
+ | `from_c` | `true` | Include C and Julia runtime frames |
124
+ | `drop_frames` | `""` | Regex of function names to drop from stacks |
125
+ | `keep_frames` | `""` | Regex of function names to keep despite dropping |
126
+ | `full_signatures` | `true` | Use full method signatures as function names |
127
+
128
+ ## Tips
129
+
130
+ Run single-threaded (`julia -t 1 --gcthreads=1`). Otherwise idle GC and
131
+ scheduler threads fill the profile with wait frames (`__psynch_cvwait`); the
132
+ wall-time profiler samples those idle tasks even more eagerly, since it samples
133
+ tasks that aren't running.
@@ -1,31 +1,74 @@
1
1
  # PHP
2
2
 
3
- PHP profiling uses [phpspy](https://github.com/adsr/phpspy), a low overhead
4
- sampling profiler for PHP processes.
3
+ PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
4
+ extension. Excimer samples from a PHP-controlled timer, so you start and stop it
5
+ within the program or a prepended bootstrap script.
5
6
 
6
7
  ## CPU profiling
7
8
 
8
9
  Periodically samples the call stack. Useful for finding CPU hot spots.
9
10
 
10
- ```sh
11
- # Profile a command (speedscope format)
12
- phpspy -d 30 --output-format=speedscope -f cpu.speedscope -- php script.php
11
+ ```php
12
+ <?php
13
+ $prof = new ExcimerProfiler();
14
+ $prof->setEventType(EXCIMER_CPU);
15
+ $prof->setPeriod(0.001); // seconds
16
+ $prof->start();
17
+
18
+ // Code to profile...
19
+
20
+ $prof->stop();
21
+ file_put_contents('cpu.speedscope.json',
22
+ json_encode($prof->getLog()->getSpeedscopeData()));
23
+ ```
13
24
 
14
- # Attach to a running process (speedscope format)
15
- phpspy -d 30 --output-format=speedscope --pid <pid> -f cpu.speedscope
25
+ ## Wall-clock profiling
16
26
 
17
- # Attach to a running process (callgrind format, for KCachegrind)
18
- phpspy -d 30 --output-format=callgrind --pid <pid> > cpu.callgrind
27
+ Samples wall-clock time rather than CPU time, including time threads spend
28
+ waiting. Useful for I/O-bound or latency-sensitive code.
29
+
30
+ ```php
31
+ <?php
32
+ $prof = new ExcimerProfiler();
33
+ $prof->setEventType(EXCIMER_REAL);
34
+ $prof->setPeriod(0.001);
35
+ $prof->start();
36
+
37
+ // Code to profile...
38
+
39
+ $prof->stop();
40
+ file_put_contents('wall.speedscope.json',
41
+ json_encode($prof->getLog()->getSpeedscopeData()));
19
42
  ```
20
43
 
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 |
44
+ ## Profiling an existing program
45
+
46
+ To profile a program without editing it, point `auto_prepend_file` at a
47
+ bootstrap script that starts the profiler and writes the result on shutdown:
48
+
49
+ ```php
50
+ <?php // prepend.php
51
+ $prof = new ExcimerProfiler();
52
+ $prof->setEventType(EXCIMER_REAL);
53
+ $prof->setPeriod(0.001);
54
+ $prof->start();
55
+ register_shutdown_function(function () use ($prof) {
56
+ $prof->stop();
57
+ file_put_contents('profile.speedscope.json',
58
+ json_encode($prof->getLog()->getSpeedscopeData()));
59
+ });
60
+ ```
61
+
62
+ ```sh
63
+ php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optimize
64
+ ```
65
+
66
+ ## API
67
+
68
+ | Method | Description |
69
+ | ------------------------------- | ----------------------------------------------------- |
70
+ | `setEventType($type)` | `EXCIMER_REAL` (wall clock) or `EXCIMER_CPU` |
71
+ | `setPeriod($seconds)` | Sampling interval in seconds (e.g. `0.001` = 1000 Hz) |
72
+ | `setMaxDepth($depth)` | Maximum stack frames per sample |
73
+ | `start()` / `stop()` | Begin and end profiling |
74
+ | `getLog()->getSpeedscopeData()` | The collected profile as Speedscope-format data |
@@ -1,72 +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) or
4
+ [systing](https://github.com/josefbacik/systing).
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
- # Collapsed format (python 3.15+)
13
- python -m profiling.sampling run --collapsed -o cpu.collapsed script.py
14
-
15
11
  # Collapsed format (wrap a script)
16
12
  py-spy record -f raw -o cpu.collapsed -- python script.py
17
13
 
18
- # Collapsed format (attach to a running process)
19
- py-spy record -f raw -o cpu.collapsed --pid <pid>
20
-
21
- # pprof format
22
- py-spy record -f pprof -o cpu.pprof -- python script.py
14
+ # Speedscope format (wrap a script)
15
+ py-spy record -f speedscope -o cpu.speedscope.json -- python script.py
23
16
 
24
- # Speedscope format
25
- 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>
26
19
 
27
- # Include native extensions written in Cython or C
28
- py-spy record -f pprof -o cpu.pprof --native -- python script.py
20
+ # Include native Cython or C extensions
21
+ py-spy record -f raw -o cpu.collapsed --native -- python script.py
29
22
  ```
30
23
 
31
24
  ## Wall-clock profiling
32
25
 
33
- Samples wall-clock time rather than CPU time. Useful for I/O-bound code where
34
- threads spend time sleeping or waiting.
35
-
36
- ```sh
37
- # Wrap a script
38
- py-spy record -f pprof -o profile.pprof --idle -- python script.py
39
-
40
- # Attach to a running process
41
- py-spy record -f pprof -o profile.pprof --idle --pid <pid>
42
- ```
43
-
44
- ## Memory profiling
45
-
46
- Tracks heap allocations. Useful for finding allocation hot spots and memory
47
- leaks.
48
-
49
- ### 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.
50
28
 
51
29
  ```sh
52
- # Record a memory profile (wrap a script)
53
- memray run -o mem.bin script.py
54
-
55
- # Attach to a running process
56
- memray attach -o mem.bin <pid>
57
-
58
- # Convert to pprof format
59
- memray pprof mem.bin
60
- ```
61
-
62
- ### Programmatic API
63
-
64
- ```python
65
- import memray
66
-
67
- with memray.Tracker("mem.bin"):
68
- # Code to profile...
69
- pass
30
+ py-spy record -f raw -o wall.collapsed --idle -- python script.py
70
31
  ```
71
32
 
72
33
  ## Call stack dump
@@ -74,8 +35,6 @@ with memray.Tracker("mem.bin"):
74
35
  Captures the current call stacks of all threads in a running process. Useful for
75
36
  diagnosing hangs, deadlocks, or unexpected blocking.
76
37
 
77
- ### CLI
78
-
79
38
  ```sh
80
39
  # Dump call stacks of a running process (text output)
81
40
  py-spy dump --pid <pid>
@@ -84,35 +43,30 @@ py-spy dump --pid <pid>
84
43
  py-spy dump --pid <pid> --locals
85
44
  ```
86
45
 
87
- ### Programmatic API
46
+ ## CLI flags
88
47
 
89
- ```python
90
- import faulthandler
48
+ | Flag | Default | Description |
49
+ | ------------------- | ------------ | -------------------------------------------------------- |
50
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope` |
51
+ | `-o` / `--output` | — | Output file path |
52
+ | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
53
+ | `-r` / `--rate` | `100` | Sampling rate in Hz |
54
+ | `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
55
+ | `--native` | off | Profile native Cython or C extensions |
56
+ | `--nonblocking` | off | Sample without pausing the process (less accurate) |
57
+ | `--subprocesses` | off | Also profile subprocesses of the target |
58
+
59
+ ## System profiling
60
+
61
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler that
62
+ samples on-CPU stacks and records a stack each time a thread sleeps. With
63
+ `--collect-pystacks` it walks CPython interpreter frames and blends them with
64
+ the native stack, so profiles show Python functions alongside the C and kernel
65
+ frames beneath them. It needs root (BPF) and a kernel with BTF
66
+ (`/sys/kernel/btf/vmlinux`).
91
67
 
92
- faulthandler.dump_traceback() # all threads to stderr
68
+ ```sh
69
+ # Record a Python program with blended Python + native stacks
70
+ sudo systing --duration 30 --collect-pystacks \
71
+ --output profile.systing -- python3 script.py
93
72
  ```
94
-
95
- ## CLI flags
96
-
97
- ### `py-spy`
98
-
99
- | Flag | Default | Description |
100
- | ------------------- | ------------ | ---------------------------------------------------------- |
101
- | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`, `pprof` |
102
- | `-o` / `--output` | — | Output file path |
103
- | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
104
- | `-r` / `--rate` | `100` | Sampling rate in Hz |
105
- | `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
106
- | `--native` | off | Profile native extensions written in Cython or C |
107
- | `--nonblocking` | off | Don't pause the process to collect samples (less accurate) |
108
- | `--subprocesses` | off | Also profile subprocesses of the target |
109
-
110
- ### `memray`
111
-
112
- | Flag | Default | Description |
113
- | --------------------------- | ------- | --------------------------------------------------- |
114
- | `-o` / `--output` | — | Output file path |
115
- | `--native` | off | Also capture native (C extension) stack frames |
116
- | `--follow-fork` | off | Also profile child processes after `fork()` |
117
- | `--aggregate` | off | Aggregate allocations to reduce output file size |
118
- | `--trace-python-allocators` | off | Trace Python allocator calls for finer-grained data |
@@ -1,7 +1,6 @@
1
1
  # Ruby
2
2
 
3
- Ruby profiling uses [rbspy](https://rbspy.github.io), a sampling profiler that
4
- attaches to a running Ruby process.
3
+ Ruby profiling uses [rbspy](https://rbspy.github.io).
5
4
 
6
5
  ## CPU profiling
7
6
 
@@ -11,10 +10,16 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
11
10
 
12
11
  ```sh
13
12
  # Profile a command (speedscope format)
14
- rbspy record --format speedscope -o profile.speedscope -- ruby script.rb
13
+ rbspy record --format speedscope -o cpu.speedscope.json -- ruby script.rb
14
+
15
+ # Collapsed stacks
16
+ rbspy record --format collapsed -o cpu.collapsed -- ruby script.rb
17
+
18
+ # pprof
19
+ rbspy record --format pprof -o cpu.pprof -- ruby script.rb
15
20
 
16
21
  # Attach to a running process
17
- rbspy record --format speedscope -o profile.speedscope --pid <pid>
22
+ rbspy record --format speedscope -o cpu.speedscope.json --pid <pid>
18
23
 
19
24
  # Profile for a fixed duration
20
25
  rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
@@ -23,45 +28,28 @@ rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
23
28
  rbspy record --format speedscope -o profile.speedscope --subprocesses --pid <pid>
24
29
  ```
25
30
 
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
31
  ## Snapshot
42
32
 
43
33
  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.
34
+ checking what a process is executing without a full recording.
46
35
 
47
36
  ### CLI
48
37
 
49
38
  ```sh
50
39
  rbspy snapshot --pid <pid>
51
40
 
52
- # Don't pause the process while reading its stack
41
+ # Read the stack without pausing the process
53
42
  rbspy snapshot --nonblocking --pid <pid>
54
43
  ```
55
44
 
56
45
  ## CLI flags
57
46
 
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) |
47
+ | Flag | Default | Description |
48
+ | ------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
49
+ | `-p` / `--pid` | — | PID of a running process to attach to |
50
+ | `-d` / `--duration` | — | Duration in seconds; records until Ctrl-C if omitted |
51
+ | `-r` / `--rate` | `100` | Samples per second |
52
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `collapsed`, `pprof`, `speedscope`, `callgrind`, `summary`, `summary_by_line` |
53
+ | `-o` / `--file` | — | Output file path |
54
+ | `--subprocesses` | — | Also profile child processes |
55
+ | `--nonblocking` | — | Read the stack without pausing the process (lower overhead, may miss frames) |