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
@@ -1,7 +1,9 @@
1
1
  # Python
2
2
 
3
- Python profiling uses [py-spy](https://github.com/benfred/py-spy), a sampling
4
- profiler that attaches to a running process or wraps a script.
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
6
+ [systing](https://github.com/josefbacik/systing).
5
7
 
6
8
  ## CPU profiling
7
9
 
@@ -17,7 +19,7 @@ py-spy record -f speedscope -o cpu.speedscope.json -- python script.py
17
19
  # Attach to a running process
18
20
  py-spy record -f raw -o cpu.collapsed --pid <pid>
19
21
 
20
- # Include native extensions written in Cython or C
22
+ # Include native Cython or C extensions
21
23
  py-spy record -f raw -o cpu.collapsed --native -- python script.py
22
24
  ```
23
25
 
@@ -43,15 +45,119 @@ py-spy dump --pid <pid>
43
45
  py-spy dump --pid <pid> --locals
44
46
  ```
45
47
 
46
- ## CLI flags
47
-
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 extensions written in Cython or C |
56
- | `--nonblocking` | off | Don't pause the process to collect samples (less accurate) |
57
- | `--subprocesses` | off | Also profile subprocesses of the target |
48
+ ## py-spy CLI flags
49
+
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 |
146
+
147
+ ## System profiling
148
+
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
154
+ `--collect-pystacks` it walks CPython interpreter frames and blends them with
155
+ the native stack, so profiles show Python functions alongside the C and kernel
156
+ frames beneath them. It needs root (BPF) and a kernel with BTF
157
+ (`/sys/kernel/btf/vmlinux`).
158
+
159
+ ```sh
160
+ # Record a Python program with blended Python + native stacks
161
+ sudo systing --duration 30 --collect-pystacks \
162
+ --output profile.systing -- python3 script.py
163
+ ```
@@ -1,57 +1,54 @@
1
1
  # Ruby
2
2
 
3
- Ruby profiling uses [rbspy](https://rbspy.github.io), a sampling profiler that
4
- attaches to a running Ruby process.
3
+ Ruby profiling uses [rbspy](https://rbspy.github.io).
5
4
 
6
5
  ## CPU profiling
7
6
 
8
7
  Periodically samples the call stack. Useful for finding CPU hot spots.
9
8
 
10
- ### CLI
11
-
12
9
  ```sh
13
10
  # Profile a command (speedscope format)
14
- rbspy record --format speedscope -o cpu.speedscope.json -- ruby script.rb
11
+ rbspy record --format speedscope --file cpu.speedscope.json -- ruby script.rb
15
12
 
16
13
  # Collapsed stacks
17
- rbspy record --format collapsed -o cpu.collapsed -- ruby script.rb
14
+ rbspy record --format collapsed --file cpu.collapsed -- ruby script.rb
18
15
 
19
16
  # pprof
20
- rbspy record --format pprof -o cpu.pprof -- ruby script.rb
17
+ rbspy record --format pprof --file cpu.pprof -- ruby script.rb
18
+
19
+ # Callgrind
20
+ rbspy record --format callgrind --file cpu.callgrind -- ruby script.rb
21
21
 
22
22
  # Attach to a running process
23
- rbspy record --format speedscope -o cpu.speedscope.json --pid <pid>
23
+ rbspy record --format speedscope --file cpu.speedscope.json --pid <pid>
24
24
 
25
25
  # Profile for a fixed duration
26
- rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
26
+ rbspy record --format speedscope --file cpu.speedscope.json --duration 30 --pid <pid>
27
27
 
28
28
  # Profile including child processes
29
- rbspy record --format speedscope -o profile.speedscope --subprocesses --pid <pid>
29
+ rbspy record --format speedscope --file cpu.speedscope.json --subprocesses --pid <pid>
30
30
  ```
31
31
 
32
- ## Snapshot
32
+ ## Call stack dump
33
33
 
34
34
  Captures a single stack trace from a running process. Useful for quickly
35
- checking what a process is currently executing without starting a full
36
- recording.
37
-
38
- ### CLI
35
+ checking what a process is executing without a full recording.
39
36
 
40
37
  ```sh
41
38
  rbspy snapshot --pid <pid>
42
39
 
43
- # Don't pause the process while reading its stack
40
+ # Read the stack without pausing the process
44
41
  rbspy snapshot --nonblocking --pid <pid>
45
42
  ```
46
43
 
47
- ## CLI flags
44
+ ## rbspy CLI flags
48
45
 
49
46
  | Flag | Default | Description |
50
47
  | ------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
51
48
  | `-p` / `--pid` | — | PID of a running process to attach to |
52
- | `-d` / `--duration` | — | Duration in seconds; records until Ctrl-C if omitted |
53
- | `-r` / `--rate` | `100` | Samples per second |
54
- | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `collapsed`, `pprof`, `speedscope`, `callgrind`, `summary`, `summary_by_line` |
55
- | `-o` / `--file` | — | Output file path |
49
+ | `-d` / `--duration` | — | Duration in seconds, recording until Ctrl-C if omitted |
50
+ | `-r` / `--rate` | `99` | Samples per second |
51
+ | `-o` / `--format` | `flamegraph` | Output format: `flamegraph`, `collapsed`, `pprof`, `speedscope`, `callgrind`, `summary`, `summary-by-line` |
52
+ | `-f` / `--file` | — | Output file path |
56
53
  | `--subprocesses` | — | Also profile child processes |
57
- | `--nonblocking` | — | Don't pause the process while reading its stack (lower overhead, may miss frames) |
54
+ | `--nonblocking` | — | Read the stack without pausing the process (lower overhead, may miss frames) |
@@ -1,7 +1,7 @@
1
1
  # Rust
2
2
 
3
- Rust CPU profiling uses [pprof-rs](https://github.com/tikv/pprof-rs), a sampling
4
- profiler that integrates directly into your binary.
3
+ Rust CPU profiling uses [pprof-rs](https://github.com/tikv/pprof-rs) or
4
+ [systing](https://github.com/josefbacik/systing).
5
5
 
6
6
  ## CPU profiling
7
7
 
@@ -14,13 +14,8 @@ Add to `Cargo.toml`:
14
14
  pprof = { version = "...", features = ["prost-codec", "frame-pointer"] }
15
15
  ```
16
16
 
17
- The `frame-pointer` feature is required on macOS (the default stack unwinder
18
- crashes with SIGBUS). Also add the following rustflag to make frame-pointer
19
- unwinding reliable:
20
-
21
- ```sh
22
- RUSTFLAGS="-C force-frame-pointers=yes" cargo build ...
23
- ```
17
+ The `frame-pointer` feature is required on macOS, because the default stack
18
+ unwinder crashes with SIGBUS.
24
19
 
25
20
  ```rust
26
21
  use pprof::protos::Message;
@@ -40,5 +35,40 @@ std::fs::write("cpu.pprof", &buf)?;
40
35
 
41
36
  | Method | Default | Description |
42
37
  | -------------------- | ------- | ---------------------------------------- |
43
- | `.frequency(hz)` | `100` | Samples per second |
38
+ | `.frequency(hz)` | `99` | Samples per second |
44
39
  | `.blocklist(frames)` | `[]` | Stack frames to exclude from the profile |
40
+
41
+ ## System profiling
42
+
43
+ Samples on-CPU stacks and records a stack each time a thread sleeps, across user
44
+ and kernel code. Useful for costs outside the process: off-CPU waits, syscall
45
+ time, and contention across the whole node.
46
+
47
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler. It
48
+ needs root (BPF) and a kernel with BTF (`/sys/kernel/btf/vmlinux`).
49
+
50
+ ```sh
51
+ # Record a command (and its children) for 30 seconds
52
+ sudo systing --duration 30 --output profile.systing -- ./target/release/program
53
+ ```
54
+
55
+ ## Tips
56
+
57
+ ### Frame pointers
58
+
59
+ A frame-pointer unwinder needs frame pointers, which Cargo release builds omit
60
+ by default. Force them on:
61
+
62
+ ```sh
63
+ RUSTFLAGS="-C force-frame-pointers=yes" cargo build ...
64
+ ```
65
+
66
+ ### Symbols
67
+
68
+ Keep debug info for release builds so frames resolve to readable names:
69
+
70
+ ```toml
71
+ # Cargo.toml
72
+ [profile.release]
73
+ debug = true
74
+ ```
@@ -0,0 +1,135 @@
1
+ # Swift
2
+
3
+ Swift profiling on Linux uses
4
+ [gperftools](https://github.com/gperftools/gperftools), whose CPU profiler and
5
+ tcmalloc heap profiler attach to any dynamically linked native program. Swift
6
+ allocates class instances and buffers through `malloc`, so tcmalloc records
7
+ them.
8
+
9
+ ## CPU profiling
10
+
11
+ Periodically samples the call stack. Useful for finding CPU hot spots.
12
+
13
+ Build with debug info so frames resolve to source files and lines, and link
14
+ `-lprofiler` with `--as-needed` disabled, because the linker would otherwise
15
+ drop a library the program references no symbol from:
16
+
17
+ ```sh
18
+ # A single file
19
+ swiftc -O -g program.swift -o program -Xlinker --no-as-needed -Xlinker -lprofiler
20
+
21
+ # A SwiftPM package
22
+ swift build -c release -Xswiftc -g -Xlinker --no-as-needed -Xlinker -lprofiler
23
+ ```
24
+
25
+ ### CLI
26
+
27
+ ```sh
28
+ # Generate a CPU profile
29
+ CPUPROFILE=cpu.prof ./program
30
+
31
+ # Convert to pprof protobuf format
32
+ pprof --proto ./program cpu.prof > cpu.pprof
33
+ ```
34
+
35
+ #### Environment variables
36
+
37
+ | Variable | Default | Description |
38
+ | ---------------------- | ------- | -------------------------------------------------------------------------------- |
39
+ | `CPUPROFILE` | — | Output filename that enables profiling when set |
40
+ | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
41
+ | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
42
+ | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
43
+
44
+ ### Programmatic API
45
+
46
+ Declare gperftools' C entry points with `@_silgen_name` and link `-lprofiler`:
47
+
48
+ ```swift
49
+ @_silgen_name("ProfilerStart")
50
+ func ProfilerStart(_ path: UnsafePointer<CChar>) -> Int32
51
+ @_silgen_name("ProfilerStop")
52
+ func ProfilerStop()
53
+
54
+ _ = "cpu.prof".withCString { ProfilerStart($0) }
55
+
56
+ // Code to profile...
57
+
58
+ ProfilerStop()
59
+ ```
60
+
61
+ ## Memory profiling
62
+
63
+ Periodically dumps the live heap, capturing allocation stack traces. Useful for
64
+ finding memory leaks and allocation hot spots.
65
+
66
+ Link `-ltcmalloc` the same way:
67
+
68
+ ```sh
69
+ swiftc -O -g program.swift -o program -Xlinker --no-as-needed -Xlinker -ltcmalloc
70
+ ```
71
+
72
+ ### CLI
73
+
74
+ ```sh
75
+ # Generate heap profiles (written as <prefix>.0001.heap, .0002.heap, …)
76
+ HEAPPROFILE=heap.prof ./program
77
+
78
+ # Convert a heap profile to pprof protobuf format
79
+ pprof --proto ./program heap.prof.0001.heap > heap.pprof
80
+ ```
81
+
82
+ #### Environment variables
83
+
84
+ | Variable | Default | Description |
85
+ | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
86
+ | `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set |
87
+ | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
88
+ | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
89
+ | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
90
+ | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
91
+ | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
92
+
93
+ ## Tips
94
+
95
+ ### Demangling
96
+
97
+ gperftools reads names from the binary's symbol table, where Swift names are
98
+ mangled (`$s11SwiftParser5LexerO6CursorV7advance2ifS2bs7UnicodeO6ScalarVXE_tF`).
99
+ `swift demangle` rewrites the mangled names in any text it reads, so pipe the
100
+ Markdown through it:
101
+
102
+ ```sh
103
+ profiler-md cpu.pprof | swift demangle
104
+ ```
105
+
106
+ `--simplified` drops module names and implicit `self` types, turning the name
107
+ above into `Lexer.Cursor.advance(if:)`.
108
+
109
+ ### Preloading
110
+
111
+ `LD_PRELOAD` activates the profiler in a program that was linked without it:
112
+
113
+ ```sh
114
+ CPUPROFILE=cpu.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libprofiler.so ./program
115
+ HEAPPROFILE=heap.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libtcmalloc.so ./program
116
+ ```
117
+
118
+ ### Symbols
119
+
120
+ SwiftPM statically links a package and its dependencies into the executable, so
121
+ one binary contains their symbols. The Swift runtime (`libswiftCore.so` and the
122
+ rest of `/usr/lib/swift/linux`) stays dynamic. `pprof` needs those libraries
123
+ present to symbolize frames inside them.
124
+
125
+ ### Optimization
126
+
127
+ `-Onone` frames are easy to read, but the timings differ from a release build's.
128
+ Profile `-O`, and expect inlining and generic specialization to attribute some
129
+ samples to the caller or to a specialized copy of the callee.
130
+
131
+ ### Converting
132
+
133
+ `pprof --proto` requires the Go `pprof`. gperftools stopped shipping a `pprof`
134
+ of its own in 2.17, and the Perl `pprof`/`google-pprof` that earlier releases
135
+ and the distro packages built from them install has no protobuf output.
@@ -0,0 +1,155 @@
1
+ # Zig
2
+
3
+ Zig profiling uses [gperftools](https://github.com/gperftools/gperftools), whose
4
+ CPU profiler and tcmalloc heap profiler attach to any dynamically linked native
5
+ program, or [Linux `perf`](https://perfwiki.github.io/main/), which samples the
6
+ program from the kernel.
7
+
8
+ ## CPU profiling
9
+
10
+ Periodically samples the call stack. Useful for finding CPU hot spots.
11
+
12
+ Link libc dynamically so the profiler can be preloaded, and keep frame pointers
13
+ so its unwinder can walk the stack:
14
+
15
+ ```sh
16
+ zig build-exe -O ReleaseSafe -fno-omit-frame-pointer -lc program.zig
17
+ ```
18
+
19
+ ### CLI
20
+
21
+ ```sh
22
+ # Generate a CPU profile
23
+ CPUPROFILE=cpu.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libprofiler.so ./program
24
+
25
+ # Convert to pprof protobuf format
26
+ pprof --proto ./program cpu.prof > cpu.pprof
27
+ ```
28
+
29
+ #### Environment variables
30
+
31
+ | Variable | Default | Description |
32
+ | ---------------------- | ------- | -------------------------------------------------------------------------------- |
33
+ | `CPUPROFILE` | — | Output filename that enables profiling when set |
34
+ | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
35
+ | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
36
+ | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
37
+
38
+ ### Programmatic API
39
+
40
+ Declare the C entry points and link `-lprofiler`:
41
+
42
+ ```zig
43
+ extern fn ProfilerStart(fname: [*:0]const u8) c_int;
44
+ extern fn ProfilerStop() void;
45
+
46
+ _ = ProfilerStart("cpu.prof");
47
+
48
+ // Code to profile...
49
+
50
+ ProfilerStop();
51
+ ```
52
+
53
+ ```sh
54
+ zig build-exe -O ReleaseSafe -fno-omit-frame-pointer -lc -lprofiler program.zig
55
+ ```
56
+
57
+ ## Memory profiling
58
+
59
+ Periodically dumps the live heap, capturing allocation stack traces. Useful for
60
+ finding memory leaks and allocation hot spots.
61
+
62
+ Allocate through `std.heap.c_allocator`, which routes every allocation to
63
+ `malloc` and so to tcmalloc:
64
+
65
+ ```zig
66
+ const gpa = std.heap.c_allocator;
67
+ ```
68
+
69
+ ### CLI
70
+
71
+ ```sh
72
+ # Generate heap profiles (written as <prefix>.0001.heap, .0002.heap, …)
73
+ HEAPPROFILE=heap.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libtcmalloc.so ./program
74
+
75
+ # Convert a heap profile to pprof protobuf format
76
+ pprof --proto ./program heap.prof.0001.heap > heap.pprof
77
+ ```
78
+
79
+ #### Environment variables
80
+
81
+ | Variable | Default | Description |
82
+ | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
83
+ | `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set |
84
+ | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
85
+ | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
86
+ | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
87
+ | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
88
+ | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
89
+
90
+ ## Linux perf profiling
91
+
92
+ Samples the call stack through the kernel's own `perf_event` counters, across
93
+ user and kernel code. Useful for finding CPU hot spots, including the ones in
94
+ the kernel.
95
+
96
+ [Linux `perf`](https://perfwiki.github.io/main/) samples any native program and
97
+ writes `perf.data` itself. It needs a Linux kernel and a
98
+ `/proc/sys/kernel/perf_event_paranoid` low enough to permit sampling (`1` or
99
+ below for kernel stacks).
100
+
101
+ Build with frame pointers so perf's unwinder can walk the stack:
102
+
103
+ ```sh
104
+ zig build-exe -O ReleaseSafe -fno-omit-frame-pointer program.zig
105
+ ```
106
+
107
+ ### CLI
108
+
109
+ ```sh
110
+ # Sample a command at 999 Hz, recording call chains
111
+ perf record -F 999 -g -o perf.data -- ./program args
112
+
113
+ # Or sample a running process for 30 seconds
114
+ perf record -F 999 -g -o perf.data --pid <pid> -- sleep 30
115
+ ```
116
+
117
+ #### Flags
118
+
119
+ | Flag | Default | Description |
120
+ | -------------- | ----------- | -------------------------------------------------------------------- |
121
+ | `-F` | `4000` | Samples per second |
122
+ | `-e` | `cycles` | Event to sample (`cpu-clock` where no hardware counter is available) |
123
+ | `-g` | off | Record call chains |
124
+ | `--call-graph` | `fp` | How to unwind: `fp`, `dwarf` (larger files), or `lbr` |
125
+ | `-o` | `perf.data` | Output path |
126
+ | `-a` | off | Sample every CPU on the system rather than one command |
127
+
128
+ A `perf.data` file holds addresses rather than function names. See
129
+ `profiler-md --help perf` for how frames are named and how to symbolize them.
130
+
131
+ ## Tips
132
+
133
+ ### Linking
134
+
135
+ `LD_PRELOAD` requires a dynamic loader, and a Zig program without libc is
136
+ statically linked. Pass `-lc` to link glibc dynamically, or link
137
+ `-lprofiler`/`-ltcmalloc` and call the profiler's C API instead.
138
+
139
+ ### Symbols
140
+
141
+ gperftools symbolizes addresses from the binary's symbol table, so profile a
142
+ build that keeps its symbols. `-O ReleaseSafe` and `-O ReleaseFast` keep them,
143
+ and `-fstrip` removes them.
144
+
145
+ ### Optimization
146
+
147
+ `-O Debug` frames are easy to read, but the timings differ from a release
148
+ build's. Profile `-O ReleaseSafe` or `-O ReleaseFast`, and expect inlining to
149
+ attribute some samples to the caller.
150
+
151
+ ### Converting
152
+
153
+ `pprof --proto` requires the Go `pprof`. gperftools stopped shipping a `pprof`
154
+ of its own in 2.17, and the Perl `pprof`/`google-pprof` that earlier releases
155
+ and the distro packages built from them install has no protobuf output.