profiler-md 0.5.0 → 0.7.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 (235) hide show
  1. package/dist/cli/index.mjs +14155 -5081
  2. package/dist/index.d.mts +1312 -263
  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 +3 -3
  11. package/docs/formats/jsc-heap-snapshot.md +11 -5
  12. package/docs/formats/memray.md +30 -0
  13. package/docs/formats/perf.md +74 -0
  14. package/docs/formats/pprof.md +10 -6
  15. package/docs/formats/speedscope.md +7 -5
  16. package/docs/formats/systing.md +27 -0
  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 +10 -5
  20. package/docs/formats/webkit-timeline-recording.md +6 -0
  21. package/docs/languages/c.md +138 -18
  22. package/docs/languages/csharp.md +7 -7
  23. package/docs/languages/elixir.md +22 -15
  24. package/docs/languages/fortran.md +141 -0
  25. package/docs/languages/go.md +36 -13
  26. package/docs/languages/haskell.md +134 -0
  27. package/docs/languages/java.md +89 -34
  28. package/docs/languages/javascript.md +37 -31
  29. package/docs/languages/julia.md +96 -14
  30. package/docs/languages/php.md +10 -4
  31. package/docs/languages/python.md +121 -15
  32. package/docs/languages/ruby.md +19 -22
  33. package/docs/languages/rust.md +40 -10
  34. package/docs/languages/swift.md +135 -0
  35. package/docs/languages/zig.md +155 -0
  36. package/package.json +47 -46
  37. package/readme.md +306 -242
  38. package/skills/profile-optimize/SKILL.md +162 -0
  39. package/docs/languages/cpp.md +0 -160
  40. package/docs/languages/erlang.md +0 -46
  41. package/docs/languages/fsharp.md +0 -52
  42. package/docs/languages/kotlin.md +0 -170
  43. package/docs/languages/typescript.md +0 -276
  44. package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
  45. package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
  46. package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
  47. package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
  48. package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
  49. package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
  50. package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
  51. package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
  52. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
  53. package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
  54. package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
  55. package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
  56. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
  57. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
  58. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
  59. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
  60. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
  61. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
  62. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
  63. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
  64. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
  65. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
  66. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
  67. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
  68. package/examples/output/go.pprof.block.base.pprof.md +0 -86
  69. package/examples/output/go.pprof.block.current.pprof.md +0 -83
  70. package/examples/output/go.pprof.block.diff.pprof.md +0 -42
  71. package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
  72. package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
  73. package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
  74. package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
  75. package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
  76. package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
  77. package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
  78. package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
  79. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
  80. package/examples/output/go.pprof.heap.base.pprof.md +0 -154
  81. package/examples/output/go.pprof.heap.current.pprof.md +0 -146
  82. package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
  83. package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
  84. package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
  85. package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
  86. package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
  87. package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
  88. package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
  89. package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
  90. package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
  91. package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
  92. package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
  93. package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
  94. package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
  95. package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
  96. package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
  97. package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
  98. package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
  99. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
  100. package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
  101. package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
  102. package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
  103. package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
  104. package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
  105. package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
  106. package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
  107. package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
  108. package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
  109. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
  110. package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
  111. package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
  112. package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
  113. package/examples/output/java.jdk.all.base.jfr.md +0 -1024
  114. package/examples/output/java.jdk.all.current.jfr.md +0 -1010
  115. package/examples/output/java.jdk.all.diff.jfr.md +0 -311
  116. package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
  117. package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
  118. package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
  119. package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
  120. package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
  121. package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
  122. package/examples/output/java.jdk.live.base.jfr.md +0 -1029
  123. package/examples/output/java.jdk.live.current.jfr.md +0 -1035
  124. package/examples/output/java.jdk.live.diff.jfr.md +0 -289
  125. package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
  126. package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
  127. package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
  128. package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
  129. package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
  130. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
  131. package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
  132. package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
  133. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
  134. package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
  135. package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
  136. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
  137. package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
  138. package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
  139. package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
  140. package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
  141. package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
  142. package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
  143. package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
  144. package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
  145. package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
  146. package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
  147. package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
  148. package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
  149. package/examples/output/javascript.node.base.cpuprofile.md +0 -136
  150. package/examples/output/javascript.node.base.heapprofile.md +0 -56
  151. package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
  152. package/examples/output/javascript.node.current.cpuprofile.md +0 -119
  153. package/examples/output/javascript.node.current.heapprofile.md +0 -52
  154. package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
  155. package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
  156. package/examples/output/javascript.node.diff.heapprofile.md +0 -34
  157. package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
  158. package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
  159. package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
  160. package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
  161. package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
  162. package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
  163. package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
  164. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
  165. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
  166. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
  167. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
  168. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
  169. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
  170. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
  171. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
  172. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
  173. package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
  174. package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
  175. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
  176. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
  177. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
  178. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
  179. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
  180. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
  181. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
  182. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
  183. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
  184. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
  185. package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
  186. package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
  187. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
  188. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
  189. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
  190. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
  191. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
  192. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
  193. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
  194. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
  195. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
  196. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
  197. package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
  198. package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
  199. package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
  200. package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
  201. package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
  202. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
  203. package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
  204. package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
  205. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
  206. package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
  207. package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
  208. package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
  209. package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
  210. package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
  211. package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
  212. package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
  213. package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
  214. package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
  215. package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
  216. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
  217. package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
  218. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
  219. package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
  220. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
  221. package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
  222. package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
  223. package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
  224. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
  225. package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
  226. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
  227. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
  228. package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
  229. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
  230. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
  231. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
  232. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
  233. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
  234. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
  235. 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,21 +1,21 @@
1
- # Java/Kotlin
1
+ # Java/Kotlin/Groovy
2
2
 
3
- Java and Kotlin profiling works with any JVM language, using either
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
- [async-profiler](https://github.com/async-profiler/async-profiler), a low
7
- overhead sampling profiler that additionally resolves native frames and works on
8
- older JDKs.
6
+ [async-profiler](https://github.com/async-profiler/async-profiler), which also
7
+ resolves native frames and works on older JDKs.
9
8
 
10
9
  ## CPU profiling
11
10
 
12
11
  Periodically samples the call stack while on CPU. Useful for finding CPU hot
13
- spots. Recorded as `jdk.ExecutionSample` events.
12
+ spots. Recorded as `jdk.ExecutionSample` events, plus `jdk.NativeMethodSample`
13
+ events for threads running native methods.
14
14
 
15
15
  ### Java Flight Recorder
16
16
 
17
17
  ```sh
18
- java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms -jar app.jar
18
+ java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms,+jdk.NativeMethodSample#enabled=true,+jdk.NativeMethodSample#period=10ms -jar app.jar
19
19
  jfr summary cpu.jfr
20
20
  ```
21
21
 
@@ -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` and
60
- `jdk.JavaMonitorWait`, via the lock recipe 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 @@ record specific waiting events, such as `jdk.ThreadPark` and
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 multiple chunks as
140
- it grows (`-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
@@ -146,25 +194,32 @@ jfr summary all.jfr
146
194
 
147
195
  ### async-profiler
148
196
 
149
- `--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock`
150
- simultaneously. Add `--nofree` to suppress the high-volume native `free` events,
151
- which otherwise dominate the recording.
197
+ `--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock` at once.
198
+ Add `--nofree` to suppress the high-volume native `free` events, which otherwise
199
+ dominate the recording.
152
200
 
153
201
  ```sh
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,16 +23,20 @@ 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 to write the profile to |
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
 
34
- Profile a specific section of code rather than the whole process:
39
+ Profile a section of code rather than the whole process:
35
40
 
36
41
  ```js
37
42
  import { writeFileSync } from 'node:fs'
@@ -66,12 +71,15 @@ node --heap-prof script.js
66
71
 
67
72
  #### Flags
68
73
 
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 |
74
+ | Flag | Default | Description |
75
+ | ------------------------------ | --------- | ------------------------------------------- |
76
+ | `--heap-prof` | — | Write a heap profile on exit when set |
77
+ | `--heap-prof-interval=<bytes>` | `524288` | Sampling interval in bytes (default 512 KB) |
78
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the profile |
79
+ | `--heap-prof-name=<name>` | see below | Filename for the profile |
80
+
81
+ Node.js names the profile
82
+ `Heap.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.heapprofile`.
75
83
 
76
84
  ### Programmatic API
77
85
 
@@ -82,13 +90,11 @@ import { Session } from 'node:inspector/promises'
82
90
  const session = new Session()
83
91
  session.connect()
84
92
  await session.post(`HeapProfiler.enable`)
85
- await session.post(`HeapProfiler.startSamplingHeapProfiler`, {
86
- samplingInterval: 524_288,
87
- })
93
+ await session.post(`HeapProfiler.startSampling`, { samplingInterval: 524_288 })
88
94
 
89
95
  // Code to profile...
90
96
 
91
- const { profile } = await session.post(`HeapProfiler.stopSamplingHeapProfiler`)
97
+ const { profile } = await session.post(`HeapProfiler.stopSampling`)
92
98
  writeFileSync(`heap.heapprofile`, JSON.stringify(profile))
93
99
  ```
94
100
 
@@ -104,7 +110,7 @@ memory leaks.
104
110
  node --heapsnapshot-near-heap-limit=1 script.js
105
111
 
106
112
  # Trigger on signal
107
- node --heapsnapshot-signal=USR2 script.js # then: kill -USR2 <pid>
113
+ node --heapsnapshot-signal=SIGUSR2 script.js # then: kill -USR2 <pid>
108
114
 
109
115
  # Bun (on exit)
110
116
  bun --heap-prof script.ts
@@ -115,15 +121,15 @@ bun --heap-prof script.ts
115
121
  | Flag | Default | Description |
116
122
  | ------------------------------------ | ------- | ---------------------------------------------------------- |
117
123
  | `--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`) |
124
+ | `--heapsnapshot-signal=<signal>` | — | Signal that triggers a snapshot on demand (e.g. `SIGUSR2`) |
119
125
 
120
126
  #### Bun flags
121
127
 
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 |
128
+ | Flag | Default | Description |
129
+ | ------------------------- | ------- | -------------------------------------- |
130
+ | `--heap-prof` | — | Write a heap snapshot on exit when set |
131
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot |
132
+ | `--heap-prof-name=<name>` | — | Filename for the snapshot |
127
133
 
128
134
  ### Programmatic API
129
135
 
@@ -139,7 +145,7 @@ writeHeapSnapshot(`heap.heapsnapshot`)
139
145
 
140
146
  Bun also offers
141
147
  [`Bun.generateHeapSnapshot()`](https://bun.com/reference/bun/generateHeapSnapshot),
142
- which emits _both_ heap snapshot formats, selectable by argument:
148
+ which emits both heap snapshot formats, selectable by argument:
143
149
 
144
150
  ```js
145
151
  import { generateHeapSnapshot } from 'bun'
@@ -212,7 +218,7 @@ deno run --inspect script.ts
212
218
 
213
219
  | Flag | Description |
214
220
  | ------------------------------ | ----------------------------------------------------------- |
215
- | `--inspect[=<host:port>]` | Start the inspector; code runs immediately |
221
+ | `--inspect[=<host:port>]` | Start the inspector and run the code immediately |
216
222
  | `--inspect-wait[=<host:port>]` | Wait for a debugger to attach before running |
217
223
  | `--inspect-brk[=<host:port>]` | Wait for a debugger to attach, then break on the first line |
218
224
 
@@ -254,10 +260,10 @@ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
254
260
  ### Recording
255
261
 
256
262
  1. Click the **Timelines** tab.
257
- 2. Enable the instruments you want: **JavaScript & Events** (always), and
258
- optionally **Memory** and **JavaScript Allocations**.
263
+ 2. Enable the instruments: **JavaScript & Events** (always), and optionally
264
+ **Memory** and **JavaScript Allocations**.
259
265
  3. Click **Start Recording** (or ⌘R).
260
- 4. Reproduce the scenario you want to profile.
266
+ 4. Reproduce the scenario to profile.
261
267
  5. Click **Stop Recording**.
262
268
  6. Click the **Export** button (arrow icon) and save as a `.json` file.
263
269
 
@@ -3,52 +3,134 @@
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
 
15
- # Warm up the JIT so compilation isn't captured as part of the profile.
16
+ # Warm up the JIT so the profile excludes compilation.
16
17
  my_function()
17
18
 
18
19
  Profile.clear()
19
20
  @profile my_function()
20
21
 
21
22
  # `web = false` skips the UI. `from_c = false` drops C/runtime frames, leaving
22
- # just your Julia code.
23
+ # your Julia code.
23
24
  pprof(out = "cpu.pb.gz", web = false, from_c = false)
24
25
  ```
25
26
 
27
+ ### `Profile.init` options
28
+
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.
32
+
33
+ ```julia
34
+ Profile.init(n = 10^7, delay = 0.0005)
35
+ ```
36
+
37
+ | Option | Default | Description |
38
+ | ------- | ------- | --------------------------------------------------- |
39
+ | `n` | `10^7` | Buffer capacity in instruction pointers, per thread |
40
+ | `delay` | `0.001` | Seconds between samples |
41
+
42
+ If profiling warns that the buffer filled up, increase `n` or `delay` and
43
+ re-run.
44
+
45
+ ## Wall-time profiling
46
+
47
+ Periodically samples all live tasks regardless of scheduling state (Julia ≥
48
+ 1.12). Unlike CPU profiling, it samples blocked tasks too, counting time spent
49
+ waiting on IO, locks, channels, and the scheduler. Useful for I/O-bound or
50
+ latency-sensitive code.
51
+
52
+ ```julia
53
+ using Profile, PProf
54
+
55
+ # Warm up the JIT so the profile excludes compilation.
56
+ my_function()
57
+
58
+ Profile.clear()
59
+ Profile.@profile_walltime my_function()
60
+
61
+ # Wall-time samples land in the same buffer as `@profile`, so the same call
62
+ # exports them. Always `Profile.clear()` between runs so CPU and wall-time
63
+ # samples don't mix.
64
+ pprof(out = "wall.pb.gz", web = false, from_c = false)
65
+ ```
66
+
67
+ Samples containing `failed_to_sample_task_fun` or `failed_to_stop_thread_fun`
68
+ indicate many short-lived tasks that completed before their backtraces could be
69
+ collected.
70
+
26
71
  ## Memory profiling
27
72
 
28
- Samples heap allocations. Useful for finding allocation hot spots and reducing
29
- GC pressure.
73
+ Samples heap allocations (Julia ≥ 1.8). Useful for finding allocation hot spots
74
+ and reducing GC pressure.
30
75
 
31
76
  ```julia
32
77
  using Profile, PProf
33
78
 
34
- # Warm up the JIT so compilation isn't captured as part of the profile.
79
+ # Warm up the JIT so the profile excludes compilation.
35
80
  my_function()
36
81
 
37
82
  Profile.Allocs.clear()
38
- Profile.Allocs.@profile my_function()
83
+ Profile.Allocs.@profile sample_rate = 0.01 my_function()
39
84
 
40
85
  PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
41
86
  ```
42
87
 
88
+ `sample_rate` is the fraction of allocations recorded: `1.0` records every
89
+ allocation, the default `0.1` records ~10%. Allocation-heavy workloads allocate
90
+ millions of times, so lower the rate until the run's overhead and the profile's
91
+ size are reasonable.
92
+
93
+ ## Heap snapshots
94
+
95
+ Captures a snapshot of all live objects on the heap (Julia ≥ 1.9), written
96
+ directly in the V8 heap snapshot format. Useful for diagnosing memory leaks.
97
+
98
+ ```julia
99
+ using Profile
100
+
101
+ # Code to capture...
102
+ Profile.take_heap_snapshot("heap.heapsnapshot")
103
+ ```
104
+
105
+ ### `take_heap_snapshot` options
106
+
107
+ | Option | Default | Description |
108
+ | ------------- | ------- | ------------------------------------------------------------------------ |
109
+ | `redact_data` | `true` | Omit the contents of Julia strings |
110
+ | `streaming` | `false` | Stream four intermediate files instead of holding the snapshot in memory |
111
+
112
+ A snapshot spans the entire runtime heap: `Base`, method tables, and every
113
+ loaded package. Expect files of hundreds of megabytes even for small programs.
114
+ They compress well, and profiler-md accepts them gzipped as-is. For
115
+ memory-constrained processes, pass `streaming = true` and reassemble afterwards
116
+ with `Profile.HeapSnapshot.assemble_snapshot(prefix, "heap.heapsnapshot")`.
117
+
43
118
  ## `pprof` options
44
119
 
45
- | Option | Default | Description |
46
- | -------- | ----------------- | --------------------------------------------- |
47
- | `out` | `"profile.pb.gz"` | Output file path |
48
- | `web` | `true` | Launch the interactive web UI after exporting |
49
- | `from_c` | `true` | Include C and Julia runtime frames |
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 |
50
128
 
51
129
  ## Tips
52
130
 
131
+ ### Threads
132
+
53
133
  Run single-threaded (`julia -t 1 --gcthreads=1`). Otherwise idle GC and
54
- scheduler threads fill the profile with wait frames (`__psynch_cvwait`).
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.
@@ -1,14 +1,20 @@
1
1
  # PHP
2
2
 
3
3
  PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
4
- extension, a low-overhead sampling profiler. Excimer samples from a
5
- PHP-controlled timer, so you start and stop it from within the program or a
6
- prepended bootstrap script.
4
+ extension. Excimer samples from a PHP-controlled timer, so you start and stop it
5
+ within the program or a prepended bootstrap script.
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.
7
9
 
8
10
  ## CPU profiling
9
11
 
10
12
  Periodically samples the call stack. Useful for finding CPU hot spots.
11
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
+
12
18
  ```php
13
19
  <?php
14
20
  $prof = new ExcimerProfiler();
@@ -44,7 +50,7 @@ file_put_contents('wall.speedscope.json',
44
50
 
45
51
  ## Profiling an existing program
46
52
 
47
- To profile a program you don't want to edit, point `auto_prepend_file` at a
53
+ To profile a program without editing it, point `auto_prepend_file` at a
48
54
  bootstrap script that starts the profiler and writes the result on shutdown:
49
55
 
50
56
  ```php