profiler-md 0.6.0 → 0.8.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 (239) hide show
  1. package/dist/cli/index.mjs +12953 -4258
  2. package/dist/index.d.mts +1182 -435
  3. package/dist/index.js +2 -2
  4. package/docs/api.md +138 -0
  5. package/docs/formats/callgrind.md +25 -0
  6. package/docs/formats/collapsed.md +5 -3
  7. package/docs/formats/ghc-eventlog.md +20 -0
  8. package/docs/formats/ghc-json-profile.md +23 -0
  9. package/docs/formats/hprof.md +21 -0
  10. package/docs/formats/jfr.md +2 -2
  11. package/docs/formats/jsc-heap-snapshot.md +10 -4
  12. package/docs/formats/memray.md +30 -0
  13. package/docs/formats/perf.md +74 -0
  14. package/docs/formats/pprof.md +4 -2
  15. package/docs/formats/speedscope.md +3 -2
  16. package/docs/formats/systing.md +17 -15
  17. package/docs/formats/v8-cpu-profile.md +4 -3
  18. package/docs/formats/v8-heap-profile.md +8 -5
  19. package/docs/formats/v8-heap-snapshot.md +8 -3
  20. package/docs/formats/webkit-timeline-recording.md +6 -0
  21. package/docs/languages/c.md +119 -32
  22. package/docs/languages/csharp.md +5 -3
  23. package/docs/languages/elixir.md +19 -11
  24. package/docs/languages/fortran.md +141 -0
  25. package/docs/languages/go.md +33 -10
  26. package/docs/languages/haskell.md +134 -0
  27. package/docs/languages/java.md +81 -26
  28. package/docs/languages/javascript.md +43 -25
  29. package/docs/languages/julia.md +21 -18
  30. package/docs/languages/php.md +19 -0
  31. package/docs/languages/python.md +105 -14
  32. package/docs/languages/ruby.md +15 -16
  33. package/docs/languages/rust.md +11 -10
  34. package/docs/languages/swift.md +135 -0
  35. package/docs/languages/zig.md +155 -0
  36. package/package.json +42 -42
  37. package/readme.md +302 -259
  38. package/skills/profile-optimize/SKILL.md +4 -2
  39. package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
  40. package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
  41. package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
  42. package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
  43. package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
  44. package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
  45. package/examples/output/c.systing.cpu.base.systing.md +0 -824
  46. package/examples/output/c.systing.cpu.current.systing.md +0 -825
  47. package/examples/output/c.systing.cpu.diff.systing.md +0 -238
  48. package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
  49. package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
  50. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
  51. package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
  52. package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
  53. package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
  54. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
  55. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
  56. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
  57. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
  58. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
  59. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
  60. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
  61. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
  62. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
  63. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
  64. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
  65. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
  66. package/examples/output/go.pprof.block.base.pprof.md +0 -86
  67. package/examples/output/go.pprof.block.current.pprof.md +0 -83
  68. package/examples/output/go.pprof.block.diff.pprof.md +0 -42
  69. package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
  70. package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
  71. package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
  72. package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
  73. package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
  74. package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
  75. package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
  76. package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
  77. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
  78. package/examples/output/go.pprof.heap.base.pprof.md +0 -154
  79. package/examples/output/go.pprof.heap.current.pprof.md +0 -146
  80. package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
  81. package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
  82. package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
  83. package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
  84. package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
  85. package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
  86. package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
  87. package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
  88. package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
  89. package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
  90. package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
  91. package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
  92. package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
  93. package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
  94. package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
  95. package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
  96. package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
  97. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
  98. package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
  99. package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
  100. package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
  101. package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
  102. package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
  103. package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
  104. package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
  105. package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
  106. package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
  107. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
  108. package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
  109. package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
  110. package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
  111. package/examples/output/java.jdk.all.base.jfr.md +0 -1024
  112. package/examples/output/java.jdk.all.current.jfr.md +0 -1010
  113. package/examples/output/java.jdk.all.diff.jfr.md +0 -311
  114. package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
  115. package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
  116. package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
  117. package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
  118. package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
  119. package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
  120. package/examples/output/java.jdk.live.base.jfr.md +0 -1029
  121. package/examples/output/java.jdk.live.current.jfr.md +0 -1035
  122. package/examples/output/java.jdk.live.diff.jfr.md +0 -289
  123. package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
  124. package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
  125. package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
  126. package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
  127. package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
  128. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
  129. package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
  130. package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
  131. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
  132. package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
  133. package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
  134. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
  135. package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
  136. package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
  137. package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
  138. package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
  139. package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
  140. package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
  141. package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
  142. package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
  143. package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
  144. package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
  145. package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
  146. package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
  147. package/examples/output/javascript.node.base.cpuprofile.md +0 -136
  148. package/examples/output/javascript.node.base.heapprofile.md +0 -56
  149. package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
  150. package/examples/output/javascript.node.current.cpuprofile.md +0 -119
  151. package/examples/output/javascript.node.current.heapprofile.md +0 -52
  152. package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
  153. package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
  154. package/examples/output/javascript.node.diff.heapprofile.md +0 -34
  155. package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
  156. package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
  157. package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
  158. package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
  159. package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
  160. package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
  161. package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
  162. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
  163. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
  164. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
  165. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
  166. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
  167. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
  168. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
  169. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
  170. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
  171. package/examples/output/julia.pprof-jl.wall.base.pprof.md +0 -181
  172. package/examples/output/julia.pprof-jl.wall.current.pprof.md +0 -193
  173. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +0 -64
  174. package/examples/output/julia.profile.base.heapsnapshot.md +0 -590
  175. package/examples/output/julia.profile.current.heapsnapshot.md +0 -590
  176. package/examples/output/julia.profile.diff.heapsnapshot.md +0 -288
  177. package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
  178. package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
  179. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
  180. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
  181. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
  182. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
  183. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
  184. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
  185. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
  186. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
  187. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
  188. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
  189. package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
  190. package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
  191. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
  192. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
  193. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
  194. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
  195. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
  196. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
  197. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
  198. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
  199. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
  200. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
  201. package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
  202. package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
  203. package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
  204. package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
  205. package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
  206. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
  207. package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
  208. package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
  209. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
  210. package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
  211. package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
  212. package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
  213. package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
  214. package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
  215. package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
  216. package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
  217. package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
  218. package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
  219. package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
  220. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
  221. package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
  222. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
  223. package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
  224. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
  225. package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
  226. package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
  227. package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
  228. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
  229. package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
  230. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
  231. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
  232. package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
  233. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
  234. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
  235. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
  236. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
  237. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
  238. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
  239. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +0 -24
@@ -0,0 +1,134 @@
1
+ # Haskell
2
+
3
+ Haskell profiling uses GHC's built-in
4
+ [cost-centre profiler](https://downloads.haskell.org/ghc/latest/docs/users_guide/profiling.html),
5
+ which writes a JSON report (`+RTS -pj`) and an eventlog (`+RTS -l`). A cost
6
+ centre is an annotation on a binding that the runtime attributes time and
7
+ allocation to.
8
+
9
+ ## Wall-clock profiling
10
+
11
+ Periodically samples the cost-centre stack. Useful for finding hot spots,
12
+ including the time the program spends blocked, which the runtime attributes to
13
+ the built-in `IDLE` cost centre.
14
+
15
+ The timer runs on real time and samples every capability whether or not it is
16
+ running Haskell. The runtime also counts every byte the program allocates per
17
+ cost-centre stack and every time it enters one, and the JSON report includes
18
+ both counts. The eventlog omits them.
19
+
20
+ GHC inserts cost centres only into modules compiled with `-prof`, so compile
21
+ every library the program links with `-prof` too:
22
+
23
+ ```sh
24
+ # cabal, which rebuilds the dependencies with profiling as well
25
+ cabal build --enable-profiling
26
+
27
+ # stack
28
+ stack build --profile
29
+
30
+ # ghc directly
31
+ ghc -O2 -prof -fprof-auto-top -rtsopts Main.hs
32
+ ```
33
+
34
+ ### Cost centres
35
+
36
+ Annotating every binding costs time and prevents optimizations, so GHC inserts
37
+ only the cost centres one of these flags specifies. Add `{-# SCC "name" #-}` in
38
+ the source to annotate an expression by hand.
39
+
40
+ #### Flags
41
+
42
+ | Flag | Description |
43
+ | ------------------------ | ----------------------------------------------------------------------------------- |
44
+ | `-fprof-auto` | A cost centre for every binding, including local ones |
45
+ | `-fprof-auto-top` | A cost centre for every top-level binding |
46
+ | `-fprof-auto-exported` | A cost centre for every exported binding |
47
+ | `-fprof-auto-calls` | A cost centre at every call site, required for `-xc` stack traces |
48
+ | `-fprof-late` | A cost centre for every top-level binding, inserted after optimization (GHC ≥ 9.4) |
49
+ | `-fprof-late-overloaded` | A cost centre for every overloaded top-level binding, inserted after optimization |
50
+ | `-fno-prof-auto` | No automatic cost centres, keeping only the `{-# SCC #-}` annotations in the source |
51
+
52
+ Cabal picks the flag from `--profiling-detail`, which defaults to
53
+ `exported-functions` for a library and `toplevel-functions` for an executable.
54
+ Pass a GHC flag directly with `--ghc-options=-fprof-late`.
55
+
56
+ `-fprof-auto` and its variants insert their cost centres before optimization, so
57
+ the optimizer cannot inline or fuse the annotated code. The profiled program
58
+ then runs code a release build never runs. `-fprof-late` annotates the optimized
59
+ program instead, at the cost of names the compiler generated (`$wgo1`, `main2`)
60
+ in place of the source's.
61
+
62
+ ### CLI
63
+
64
+ ```sh
65
+ # The JSON report, written to Main.prof
66
+ cabal run --enable-profiling my-program -- +RTS -pj -RTS
67
+
68
+ # The JSON report and the eventlog, from one run
69
+ ./Main +RTS -pj -l-au -RTS
70
+ ```
71
+
72
+ Prefer the JSON report, which contains the allocation totals as well as the
73
+ ticks. Use the eventlog when the program already records one, or when marking
74
+ phases with `Debug.Trace.traceEventIO` to profile a run in parts.
75
+
76
+ An eventlog contains cost-centre samples only when the time profiler runs, which
77
+ `-pj` turns on alongside the JSON report. `-p` turns it on too, but writes the
78
+ text report, which is for reading by hand, so profiler-md rejects it.
79
+
80
+ #### RTS options
81
+
82
+ | Option | Default | Description |
83
+ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
84
+ | `-p` | — | Write a time and allocation report to `<program>.prof` |
85
+ | `-P` | — | As `-p`, plus per-cost-centre tick and byte counts |
86
+ | `-pj` | — | Write the report as JSON |
87
+ | `-l` | — | Write an eventlog to `<program>.eventlog` |
88
+ | `-ol` | — | The eventlog's path |
89
+ | `-V` | `0.001` | Seconds between samples, and the resolution of every other RTS timer. A build without `-prof` ticks every `0.01` seconds |
90
+ | `-xc` | — | Print the cost-centre stack on every exception |
91
+
92
+ `-l` takes the event classes to log. `-l-au` turns them all off and turns user
93
+ events back on, so the scheduler and heap events stay out of a log recorded for
94
+ its cost-centre samples.
95
+
96
+ ## Tips
97
+
98
+ ### Garbage collection
99
+
100
+ The runtime's collector reports as the `GC` cost centre. Read its share of the
101
+ ticks first, because a Haskell program that allocates heavily spends much of its
102
+ time collecting. Cutting the allocation the profile attributes to the program's
103
+ own cost centres also cuts the collector's share.
104
+
105
+ ### Runtime cost centres
106
+
107
+ The runtime's own cost centres (`MAIN`, `CAF`, `GC`) have no source location.
108
+
109
+ ### Boot libraries
110
+
111
+ A library compiled without `-prof` gets no cost centres, so the profile
112
+ attributes its time to the nearest annotated caller. A default GHC install ships
113
+ `base` and the other boot libraries that way, while
114
+ `cabal build --enable-profiling` and `stack build --profile` rebuild every
115
+ dependency with cost centres.
116
+
117
+ ### Packages
118
+
119
+ A cost centre's source span is relative to the package GHC compiled the module
120
+ from, and the report names no package, so profiler-md counts a dependency's cost
121
+ centres as the program's own code rather than as `third-party`.
122
+
123
+ ### Overhead
124
+
125
+ Time the profiled build against a plain one before treating the profile's
126
+ numbers as a release build's. Profiling adds a word to every closure and
127
+ prevents some optimizations, so a program that allocates heavily can run several
128
+ times slower.
129
+
130
+ ### Benchmarks
131
+
132
+ GHC floats a benchmark loop's body out of the loop when it doesn't depend on the
133
+ iteration, so the run measures a single iteration. Vary the input per iteration,
134
+ or force the result with `Control.DeepSeq.deepseq`.
@@ -1,6 +1,6 @@
1
- # Java/Kotlin
1
+ # Java/Kotlin/Groovy
2
2
 
3
- Java and Kotlin profiling works with any JVM language, using
3
+ Java, Kotlin, and Groovy profiling works with any JVM language, using
4
4
  [Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) (JFR),
5
5
  built into the JDK since JDK 11, or
6
6
  [async-profiler](https://github.com/async-profiler/async-profiler), which also
@@ -24,7 +24,7 @@ jfr summary cpu.jfr
24
24
  #### CLI
25
25
 
26
26
  ```sh
27
- # Attach to a running JVM (JFR is the default output format)
27
+ # Attach to a running JVM (the .jfr extension selects the JFR format)
28
28
  asprof -e cpu -d 30 -f cpu.jfr <pid>
29
29
 
30
30
  # Or write collapsed stacks
@@ -55,9 +55,9 @@ waiting. Useful for I/O-bound or latency-sensitive code.
55
55
 
56
56
  ### Java Flight Recorder
57
57
 
58
- JFR has no wall-clock sampler, so this metric is async-profiler only. (JFR does
59
- record specific waiting events, such as `jdk.ThreadPark`, via the lock recipe
60
- below.)
58
+ JFR has no wall-clock sampler, so this metric is async-profiler only. JFR does
59
+ record specific waiting events, such as `jdk.ThreadPark`, through the lock
60
+ recipe below.
61
61
 
62
62
  ### async-profiler
63
63
 
@@ -65,20 +65,24 @@ below.)
65
65
  asprof -e wall -d 30 -f wall.jfr <pid>
66
66
  ```
67
67
 
68
- Recorded as `profiler.WallClockSample` events. `cpu` and `wall` share the same
69
- sampling timer, so async-profiler records one or the other within a single
70
- recording, not both.
68
+ Recorded as `profiler.WallClockSample` events. To record wall-clock samples
69
+ alongside another event, pass the interval through `--wall` rather than
70
+ `-e wall`, which async-profiler rejects in combination with a second event:
71
+
72
+ ```sh
73
+ asprof -e cpu --wall 100ms -d 30 -f combined.jfr <pid>
74
+ ```
71
75
 
72
76
  ## Memory profiling
73
77
 
74
78
  Samples memory allocations, in allocated bytes. async-profiler offers three
75
79
  variants; JFR offers two:
76
80
 
77
- - **heap allocations**: every heap allocation sampled since profiling started;
81
+ - **heap allocations**: every heap allocation sampled since profiling started,
78
82
  useful for finding allocation hot spots and reducing GC pressure
79
- - **live heap**: only allocations whose objects are still live at the end;
83
+ - **live heap**: only allocations whose objects are still live at the end,
80
84
  useful for finding leaks
81
- - **native memory**: off-heap `malloc`/`free`; useful for finding native leaks
85
+ - **native memory**: off-heap `malloc`/`free`, useful for finding native leaks
82
86
  (async-profiler only)
83
87
 
84
88
  ### Java Flight Recorder
@@ -111,6 +115,50 @@ asprof -e nativemem -d 30 -f native.jfr <pid>
111
115
  `--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
112
116
  heap and native variants.
113
117
 
118
+ ## Heap dumps
119
+
120
+ Captures every live object on the heap, with the references between them. Useful
121
+ for finding what a leak retains, which the allocation profiles above don't
122
+ record. The JVM writes the dump in the HPROF format.
123
+
124
+ ### CLI
125
+
126
+ ```sh
127
+ # Attach to a running JVM (live objects only, after a full GC)
128
+ jcmd <pid> GC.heap_dump -all=false heap.hprof
129
+
130
+ # Or with jmap
131
+ jmap -dump:live,format=b,file=heap.hprof <pid>
132
+ ```
133
+
134
+ ### On out of memory
135
+
136
+ ```sh
137
+ java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=heap.hprof -jar app.jar
138
+ ```
139
+
140
+ #### Flags
141
+
142
+ | Flag | Default | Description |
143
+ | --------------------------------- | ----------------- | ---------------------------------------------------- |
144
+ | `-XX:+HeapDumpOnOutOfMemoryError` | off | Dump the heap when the JVM throws `OutOfMemoryError` |
145
+ | `-XX:HeapDumpPath=<path>` | working directory | File or directory the dump is written to |
146
+
147
+ ### Programmatic API
148
+
149
+ `HotSpotDiagnosticMXBean` dumps the heap from inside the process:
150
+
151
+ ```java
152
+ import com.sun.management.HotSpotDiagnosticMXBean;
153
+ import java.lang.management.ManagementFactory;
154
+
155
+ HotSpotDiagnosticMXBean diagnostics = ManagementFactory.getPlatformMXBean(
156
+ HotSpotDiagnosticMXBean.class);
157
+
158
+ // Code to capture...
159
+ diagnostics.dumpHeap("heap.hprof", /* live= */ true);
160
+ ```
161
+
114
162
  ## Lock profiling
115
163
 
116
164
  Samples contended monitor and `java.util.concurrent` locks. Useful for finding
@@ -136,8 +184,8 @@ Recorded as `profiler.NativeLock` events.
136
184
  ### Java Flight Recorder
137
185
 
138
186
  The `profile` template records execution samples, allocations, locks, GC, and
139
- many other JVM events at once. JFR rotates the recording into chunks as it grows
140
- (`-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold).
187
+ many other JVM events at once. JFR rotates the recording into chunks as it
188
+ grows. `-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold.
141
189
 
142
190
  ```sh
143
191
  java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
@@ -154,17 +202,24 @@ dominate the recording.
154
202
  asprof --all --nofree -d 30 -f all.jfr <pid>
155
203
  ```
156
204
 
157
- ## async-profiler flags
205
+ ## async-profiler CLI flags
206
+
207
+ | Flag | Default | Description |
208
+ | ------- | ------------------ | ------------------------------------------------------------ |
209
+ | `-e` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock`, and others |
210
+ | `-d` | — | Duration in seconds |
211
+ | `-o` | the `-f` extension | Output format (`jfr`, `collapsed`, `flamegraph`, and others) |
212
+ | `-f` | — | Output file path |
213
+ | `-i` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
214
+ | `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
215
+ | `<pid>` | — | Target JVM PID, `jps`, or the application name |
216
+
217
+ `-o` overrides the format the `-f` filename's extension selects. A run with
218
+ neither writes a text summary.
219
+
220
+ ## Tips
158
221
 
159
- | Flag | Default | Description |
160
- | ------------------- | ------- | ------------------------------------------------------------ |
161
- | `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock`, and others |
162
- | `-d` / `--duration` | — | Duration in seconds |
163
- | `-o` / `--output` | `jfr` | Output format (`jfr` or `collapsed`) |
164
- | `-f` / `--file` | — | Output file path |
165
- | `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
166
- | `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
167
- | `<pid>` | — | Target JVM PID, `jps`, or the application name |
222
+ ### Platforms
168
223
 
169
- On macOS the default `cpu` event works (it samples CPU time via a timer), but
170
- hardware events like `cache-misses` require Linux `perf_events`.
224
+ The default `cpu` event works on macOS, where it samples CPU time through a
225
+ timer. Hardware events such as `cache-misses` require Linux `perf_events`.
@@ -1,7 +1,8 @@
1
1
  # JavaScript
2
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.
3
+ JavaScript profiling uses the profilers built into Node.js, Deno, Bun, Chrome
4
+ DevTools, and Safari's Web Inspector, which capture CPU profiles, heap profiles,
5
+ and heap snapshots in the V8 and JavaScriptCore formats.
5
6
 
6
7
  ## CPU profiling
7
8
 
@@ -22,12 +23,16 @@ bun --cpu-prof script.ts
22
23
 
23
24
  #### Flags
24
25
 
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 for the profile |
30
- | `--cpu-prof-name=<name>` | `CPU.<timestamp>.<pid>.cpuprofile` | Filename for the profile |
26
+ | Flag | Default | Description |
27
+ | -------------------------- | --------- | ------------------------------------ |
28
+ | `--cpu-prof` | — | Write a CPU profile on exit when set |
29
+ | `--cpu-prof-interval=<µs>` | `1000` | Sampling interval in microseconds |
30
+ | `--cpu-prof-dir=<dir>` | `.` | Directory for the profile |
31
+ | `--cpu-prof-name=<name>` | see below | Filename for the profile |
32
+
33
+ Node.js names the profile
34
+ `CPU.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.cpuprofile`, and Deno and Bun name it
35
+ `CPU.<timestamp>.<pid>.cpuprofile`.
31
36
 
32
37
  ### Programmatic API
33
38
 
@@ -57,6 +62,14 @@ and reducing GC pressure.
57
62
  `bun --heap-prof` generates a V8 heap _snapshot_ on exit, not a heap _profile_.
58
63
  Deno has no equivalent.
59
64
 
65
+ The profiler reports only the sampled objects still alive when the profile is
66
+ written, so a workload that frees most of what it allocates leaves few samples.
67
+ `HeapProfiler.startSampling` takes `includeObjectsCollectedByMajorGC` and
68
+ `includeObjectsCollectedByMinorGC`, which keep the objects a major or a minor
69
+ garbage collection freed. Set both to profile allocation hot spots, and leave
70
+ them off to profile what stays in memory. `--heap-prof` sets neither and has no
71
+ flag for them, so use the programmatic API to set them.
72
+
60
73
  ### CLI
61
74
 
62
75
  ```sh
@@ -66,12 +79,15 @@ node --heap-prof script.js
66
79
 
67
80
  #### Flags
68
81
 
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 for the profile |
74
- | `--heap-prof-name=<name>` | — | Filename for the profile |
82
+ | Flag | Default | Description |
83
+ | ------------------------------ | --------- | ------------------------------------------- |
84
+ | `--heap-prof` | — | Write a heap profile on exit when set |
85
+ | `--heap-prof-interval=<bytes>` | `524288` | Sampling interval in bytes (default 512 KB) |
86
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the profile |
87
+ | `--heap-prof-name=<name>` | see below | Filename for the profile |
88
+
89
+ Node.js names the profile
90
+ `Heap.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.heapprofile`.
75
91
 
76
92
  ### Programmatic API
77
93
 
@@ -82,13 +98,15 @@ import { Session } from 'node:inspector/promises'
82
98
  const session = new Session()
83
99
  session.connect()
84
100
  await session.post(`HeapProfiler.enable`)
85
- await session.post(`HeapProfiler.startSamplingHeapProfiler`, {
101
+ await session.post(`HeapProfiler.startSampling`, {
86
102
  samplingInterval: 524_288,
103
+ includeObjectsCollectedByMajorGC: true,
104
+ includeObjectsCollectedByMinorGC: true,
87
105
  })
88
106
 
89
107
  // Code to profile...
90
108
 
91
- const { profile } = await session.post(`HeapProfiler.stopSamplingHeapProfiler`)
109
+ const { profile } = await session.post(`HeapProfiler.stopSampling`)
92
110
  writeFileSync(`heap.heapprofile`, JSON.stringify(profile))
93
111
  ```
94
112
 
@@ -104,7 +122,7 @@ memory leaks.
104
122
  node --heapsnapshot-near-heap-limit=1 script.js
105
123
 
106
124
  # Trigger on signal
107
- node --heapsnapshot-signal=USR2 script.js # then: kill -USR2 <pid>
125
+ node --heapsnapshot-signal=SIGUSR2 script.js # then: kill -USR2 <pid>
108
126
 
109
127
  # Bun (on exit)
110
128
  bun --heap-prof script.ts
@@ -115,15 +133,15 @@ bun --heap-prof script.ts
115
133
  | Flag | Default | Description |
116
134
  | ------------------------------------ | ------- | ---------------------------------------------------------- |
117
135
  | `--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`) |
136
+ | `--heapsnapshot-signal=<signal>` | — | Signal that triggers a snapshot on demand (e.g. `SIGUSR2`) |
119
137
 
120
138
  #### Bun flags
121
139
 
122
- | Flag | Default | Description |
123
- | ------------------------- | ------- | ----------------------------------------------- |
124
- | `--heap-prof` | — | Write a heap snapshot on exit; enabled when set |
125
- | `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot |
126
- | `--heap-prof-name=<name>` | — | Filename for the snapshot |
140
+ | Flag | Default | Description |
141
+ | ------------------------- | ------- | -------------------------------------- |
142
+ | `--heap-prof` | — | Write a heap snapshot on exit when set |
143
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot |
144
+ | `--heap-prof-name=<name>` | — | Filename for the snapshot |
127
145
 
128
146
  ### Programmatic API
129
147
 
@@ -139,7 +157,7 @@ writeHeapSnapshot(`heap.heapsnapshot`)
139
157
 
140
158
  Bun also offers
141
159
  [`Bun.generateHeapSnapshot()`](https://bun.com/reference/bun/generateHeapSnapshot),
142
- which emits _both_ heap snapshot formats, selectable by argument:
160
+ which emits both heap snapshot formats, selectable by argument:
143
161
 
144
162
  ```js
145
163
  import { generateHeapSnapshot } from 'bun'
@@ -212,7 +230,7 @@ deno run --inspect script.ts
212
230
 
213
231
  | Flag | Description |
214
232
  | ------------------------------ | ----------------------------------------------------------- |
215
- | `--inspect[=<host:port>]` | Start the inspector; code runs immediately |
233
+ | `--inspect[=<host:port>]` | Start the inspector and run the code immediately |
216
234
  | `--inspect-wait[=<host:port>]` | Wait for a debugger to attach before running |
217
235
  | `--inspect-brk[=<host:port>]` | Wait for a debugger to attach, then break on the first line |
218
236
 
@@ -20,14 +20,15 @@ Profile.clear()
20
20
  @profile my_function()
21
21
 
22
22
  # `web = false` skips the UI. `from_c = false` drops C/runtime frames, leaving
23
- # just your Julia code.
23
+ # your Julia code.
24
24
  pprof(out = "cpu.pb.gz", web = false, from_c = false)
25
25
  ```
26
26
 
27
- ### Sampling settings
27
+ ### `Profile.init` options
28
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.
29
+ Samples every 1 ms by default (10 ms on 32-bit Windows). Configure with
30
+ `Profile.init` before profiling. Calling it with no arguments returns the
31
+ current settings.
31
32
 
32
33
  ```julia
33
34
  Profile.init(n = 10^7, delay = 0.0005)
@@ -35,7 +36,7 @@ Profile.init(n = 10^7, delay = 0.0005)
35
36
 
36
37
  | Option | Default | Description |
37
38
  | ------- | ------- | --------------------------------------------------- |
38
- | `n` | `10^6` | Buffer capacity in instruction pointers, per thread |
39
+ | `n` | `10^7` | Buffer capacity in instruction pointers, per thread |
39
40
  | `delay` | `0.001` | Seconds between samples |
40
41
 
41
42
  If profiling warns that the buffer filled up, increase `n` or `delay` and
@@ -101,7 +102,7 @@ using Profile
101
102
  Profile.take_heap_snapshot("heap.heapsnapshot")
102
103
  ```
103
104
 
104
- ### Options
105
+ ### `take_heap_snapshot` options
105
106
 
106
107
  | Option | Default | Description |
107
108
  | ------------- | ------- | ------------------------------------------------------------------------ |
@@ -110,24 +111,26 @@ Profile.take_heap_snapshot("heap.heapsnapshot")
110
111
 
111
112
  A snapshot spans the entire runtime heap: `Base`, method tables, and every
112
113
  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
+ They compress well, and profiler-md accepts them gzipped as-is. For
114
115
  memory-constrained processes, pass `streaming = true` and reassemble afterwards
115
116
  with `Profile.HeapSnapshot.assemble_snapshot(prefix, "heap.heapsnapshot")`.
116
117
 
117
118
  ## `pprof` options
118
119
 
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 |
120
+ | Option | Default | Description |
121
+ | ----------------- | ----------------- | ------------------------------------------------------------------- |
122
+ | `out` | `"profile.pb.gz"` | Output file path (`"alloc-profile.pb.gz"` for `PProf.Allocs.pprof`) |
123
+ | `web` | `true` | Launch the interactive web UI after exporting |
124
+ | `from_c` | `true` | Include C and Julia runtime frames |
125
+ | `drop_frames` | `nothing` | Regex of function names to drop from stacks |
126
+ | `keep_frames` | `nothing` | Regex of function names to keep despite dropping |
127
+ | `full_signatures` | `true` | Use full method signatures as function names |
127
128
 
128
129
  ## Tips
129
130
 
131
+ ### Threads
132
+
130
133
  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.
134
+ scheduler threads fill the profile with wait frames (`__psynch_cvwait`). The
135
+ wall-time profiler records more of those idle tasks, because it samples tasks
136
+ that are blocked as well as running ones.
@@ -4,10 +4,17 @@ PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
4
4
  extension. Excimer samples from a PHP-controlled timer, so you start and stop it
5
5
  within the program or a prepended bootstrap script.
6
6
 
7
+ A new `ExcimerProfiler` samples wall-clock time every 0.1 seconds, so the
8
+ recipes below set the event type and the period.
9
+
7
10
  ## CPU profiling
8
11
 
9
12
  Periodically samples the call stack. Useful for finding CPU hot spots.
10
13
 
14
+ Excimer defines `EXCIMER_CPU` only where POSIX timers provide a CPU clock, so
15
+ the constant is undefined on macOS, where Excimer uses kqueue instead. Check
16
+ with `defined('EXCIMER_CPU')` and fall back to wall-clock profiling.
17
+
11
18
  ```php
12
19
  <?php
13
20
  $prof = new ExcimerProfiler();
@@ -63,6 +70,17 @@ register_shutdown_function(function () use ($prof) {
63
70
  php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optimize
64
71
  ```
65
72
 
73
+ ## Output formats
74
+
75
+ `getSpeedscopeData()` writes the sampled time alongside each frame's file, and
76
+ `formatCollapsed()` writes sample counts with each frame's file packed into its
77
+ name. Prefer speedscope, because a collapsed frame names a method by its
78
+ declaring class rather than its file.
79
+
80
+ ```php
81
+ file_put_contents('wall.collapsed', $prof->getLog()->formatCollapsed());
82
+ ```
83
+
66
84
  ## API
67
85
 
68
86
  | Method | Description |
@@ -72,3 +90,4 @@ php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optim
72
90
  | `setMaxDepth($depth)` | Maximum stack frames per sample |
73
91
  | `start()` / `stop()` | Begin and end profiling |
74
92
  | `getLog()->getSpeedscopeData()` | The collected profile as Speedscope-format data |
93
+ | `getLog()->formatCollapsed()` | The collected profile as collapsed stacks |