profiler-md 0.6.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 (239) hide show
  1. package/dist/cli/index.mjs +12685 -4219
  2. package/dist/index.d.mts +1140 -432
  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 +33 -27
  29. package/docs/languages/julia.md +21 -18
  30. package/docs/languages/php.md +7 -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 +301 -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
 
@@ -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 for the profile |
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 for the snapshot |
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
 
@@ -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();
@@ -1,6 +1,8 @@
1
1
  # Python
2
2
 
3
- Python profiling uses [py-spy](https://github.com/benfred/py-spy) or
3
+ Python profiling uses [py-spy](https://github.com/benfred/py-spy),
4
+ [pyinstrument](https://github.com/joerick/pyinstrument),
5
+ [memray](https://github.com/bloomberg/memray), or
4
6
  [systing](https://github.com/josefbacik/systing).
5
7
 
6
8
  ## CPU profiling
@@ -43,23 +45,112 @@ py-spy dump --pid <pid>
43
45
  py-spy dump --pid <pid> --locals
44
46
  ```
45
47
 
46
- ## CLI flags
48
+ ## py-spy CLI flags
47
49
 
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 |
50
+ | Flag | Default | Description |
51
+ | ------------------- | ------------ | --------------------------------------------------------------- |
52
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`, `chrometrace` |
53
+ | `-o` / `--output` | — | Output file path |
54
+ | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
55
+ | `-r` / `--rate` | `100` | Sampling rate in Hz |
56
+ | `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
57
+ | `--native` | off | Profile native Cython or C extensions |
58
+ | `--nonblocking` | off | Sample without pausing the process (less accurate) |
59
+ | `--subprocesses` | off | Also profile subprocesses of the target |
60
+
61
+ ## In-process wall-clock profiling
62
+
63
+ Samples wall-clock time rather than CPU time, from inside the interpreter rather
64
+ than through ptrace. Useful for I/O-bound or latency-sensitive code.
65
+
66
+ [pyinstrument](https://github.com/joerick/pyinstrument) samples the call stack
67
+ from inside the interpreter, so it needs no ptrace access. Its speedscope
68
+ renderer writes a format this tool reads.
69
+
70
+ ### CLI
71
+
72
+ ```sh
73
+ # Profile a script
74
+ pyinstrument -r speedscope -o profile.speedscope.json script.py
75
+
76
+ # Profile a console script, such as the one an installed package provides
77
+ pyinstrument -r speedscope -o profile.speedscope.json "$(which black)" file.py
78
+
79
+ # Keep every frame instead of those above the 1% threshold
80
+ pyinstrument --show-all -r speedscope -o profile.speedscope.json script.py
81
+ ```
82
+
83
+ Run a console script by its path rather than as `python -m package`. Under `-m`,
84
+ pyinstrument trims the leading `runpy` frames by descending into the first child
85
+ of each. That child is the import subtree rather than the module body, so the
86
+ export covers only the imports. `--show-all` can trim the run the same way.
87
+
88
+ By default the export keeps the frames above 1% of the total and folds the rest
89
+ into the self time of the frame that called them.
90
+
91
+ #### Flags
92
+
93
+ | Flag | Default | Description |
94
+ | --------------------- | --------- | ------------------------------------------------------------- |
95
+ | `-r` / `--renderer` | see below | Output format. `speedscope` writes the format this tool reads |
96
+ | `-o` / `--outfile` | — | Output file path |
97
+ | `-m` | — | Run a library module as a script |
98
+ | `-i` / `--interval` | `0.001` | Minimum seconds between stack samples |
99
+ | `--show-all` | off | Keep every frame, including the standard library's |
100
+ | `--hide` | — | Glob matching the file paths whose frames to hide |
101
+ | `-t` / `--timeline` | off | Keep call ordering instead of condensing repeated calls |
102
+ | `--use-timing-thread` | off | Time the sampling interval on a separate thread |
103
+
104
+ Without `-r`, pyinstrument picks the renderer from the `-o` filename's
105
+ extension, and writes text when there is no `-o`.
106
+
107
+ ## Memory profiling
108
+
109
+ Traces every allocation with the Python call stack it came from. Useful for
110
+ finding where memory was held when the program's memory use was highest, and
111
+ what it never freed.
112
+
113
+ [memray](https://github.com/bloomberg/memray) traces the allocations the
114
+ interpreter makes, from inside the process.
115
+
116
+ ### CLI
117
+
118
+ ```sh
119
+ # Trace a script's allocations
120
+ memray run -o memory.bin script.py
121
+
122
+ # Trace a module, as `python -m` would run it
123
+ memray run -o memory.bin -m black file.py
124
+
125
+ # Keep per-stack totals only, for a smaller capture of a long run
126
+ memray run --aggregate -o memory.bin script.py
127
+
128
+ # Attach to a running process
129
+ memray attach --duration 60 -o memory.bin <pid>
130
+ ```
131
+
132
+ Tracing from inside the process makes the program run several times slower, so
133
+ profile a workload small enough to finish with tracing on.
134
+
135
+ #### Flags
136
+
137
+ | Flag | Default | Description |
138
+ | --------------------------- | -------------------------- | ------------------------------------------------------------------- |
139
+ | `-o` / `--output` | `<process_name>.<pid>.bin` | Output file path |
140
+ | `-f` / `--force` | off | Overwrite the output file if it exists |
141
+ | `--aggregate` | off | Record each stack's totals instead of every allocation |
142
+ | `--native` | off | Also record C/C++ frames, which this tool skips |
143
+ | `--trace-python-allocators` | off | Record pymalloc's own allocations as well as the ones underneath it |
144
+ | `--follow-fork` | off | Also trace child processes, each into its own capture |
145
+ | `--no-compress` | off | Write the capture uncompressed rather than LZ4 compressed |
58
146
 
59
147
  ## System profiling
60
148
 
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
149
+ Samples on-CPU stacks and records a stack each time a thread sleeps. Useful for
150
+ costs outside the process: off-CPU waits, syscall time, and contention across
151
+ the whole node.
152
+
153
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler. With
63
154
  `--collect-pystacks` it walks CPython interpreter frames and blends them with
64
155
  the native stack, so profiles show Python functions alongside the C and kernel
65
156
  frames beneath them. It needs root (BPF) and a kernel with BTF