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
@@ -1,7 +1,9 @@
1
1
  # C/C++
2
2
 
3
3
  C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools),
4
- or [systing](https://github.com/josefbacik/systing).
4
+ [Valgrind's Callgrind](https://valgrind.org/docs/manual/cl-manual.html),
5
+ [Linux `perf`](https://perfwiki.github.io/main/), or
6
+ [systing](https://github.com/josefbacik/systing).
5
7
 
6
8
  ## CPU profiling
7
9
 
@@ -28,7 +30,7 @@ pprof --proto ./program cpu.prof > cpu.pprof
28
30
 
29
31
  | Variable | Default | Description |
30
32
  | ---------------------- | ------- | -------------------------------------------------------------------------------- |
31
- | `CPUPROFILE` | — | Output filename; profiling is enabled when set |
33
+ | `CPUPROFILE` | — | Output filename that enables profiling when set |
32
34
  | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
33
35
  | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
34
36
  | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
@@ -61,7 +63,7 @@ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
61
63
  ### CLI
62
64
 
63
65
  ```sh
64
- # Generate heap profiles (written as <prefix>.0000.heap, .0001.heap, …)
66
+ # Generate heap profiles (written as <prefix>.0001.heap, .0002.heap, …)
65
67
  HEAPPROFILE=heap.prof ./program
66
68
 
67
69
  # Convert a heap profile to pprof protobuf format
@@ -72,13 +74,13 @@ pprof --proto ./program heap.prof.0001.heap > heap.pprof
72
74
 
73
75
  | Variable | Default | Description |
74
76
  | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
75
- | `HEAPPROFILE` | — | Output filename prefix; heap profiling is enabled when set |
77
+ | `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set |
76
78
  | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
77
79
  | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
78
80
  | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
79
81
  | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
80
82
  | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
81
- | `HEAP_PROFILE_ONLY_MMAP` | `false` | Profile only `mmap`/`mremap`/`sbrk`; skip `malloc`/`new` |
83
+ | `HEAP_PROFILE_ONLY_MMAP` | `false` | Profile only `mmap`/`mremap`/`sbrk`, skipping `malloc`/`new` |
82
84
 
83
85
  ### Programmatic API
84
86
 
@@ -93,11 +95,50 @@ HeapProfilerDump("checkpoint"); // optional mid-run profile dump
93
95
  HeapProfilerStop();
94
96
  ```
95
97
 
98
+ ## Callgrind profiling
99
+
100
+ Counts every executed instruction and records the call graph. Exact instead of
101
+ sampled, but runs the program ~20–100× slower. Requires Linux or another
102
+ Valgrind-supported platform.
103
+
104
+ Build with debug info so functions resolve to source files and lines:
105
+
106
+ ```sh
107
+ gcc -O2 -g -o program program.c # C
108
+ g++ -O2 -g -o program program.cpp # C++
109
+ ```
110
+
111
+ ### CLI
112
+
113
+ ```sh
114
+ # Profile, writing the callgrind format directly
115
+ valgrind --tool=callgrind --callgrind-out-file=program.callgrind ./program
116
+
117
+ # Optional: also simulate CPU caches and branch prediction
118
+ valgrind --tool=callgrind --cache-sim=yes --branch-sim=yes \
119
+ --callgrind-out-file=program.callgrind ./program
120
+ ```
121
+
122
+ #### Flags
123
+
124
+ | Flag | Default | Description |
125
+ | ---------------------- | ------------------ | ----------------------------------------------------------------------- |
126
+ | `--callgrind-out-file` | `callgrind.out.%p` | Output filename (`%p` expands to the PID) |
127
+ | `--cache-sim` | `no` | Also count simulated cache hits/misses |
128
+ | `--branch-sim` | `no` | Also count branch mispredictions |
129
+ | `--dump-instr` | `no` | Record costs per instruction instead of per line |
130
+ | `--separate-threads` | `no` | Write one profile per thread |
131
+ | `--instr-atstart` | `yes` | Set to `no` to skip startup, then toggle with `callgrind_control -i on` |
132
+
96
133
  ## Heap checking
97
134
 
98
135
  Compares the heap state before and after a region of code to detect memory
99
136
  leaks. Useful for confirming a code path frees everything it allocates.
100
137
 
138
+ gperftools 2.17 removed the heap leak checker. On 2.17 and later
139
+ `HeapLeakChecker` is an empty stub and `HEAPCHECK` does nothing, so use
140
+ AddressSanitizer's `LeakSanitizer` (`-fsanitize=address`) instead.
141
+
101
142
  Link with `-ltcmalloc`:
102
143
 
103
144
  ```sh
@@ -122,7 +163,7 @@ HEAPCHECK=draconian ./program
122
163
 
123
164
  | Variable | Default | Description |
124
165
  | ----------- | ------- | ------------------------------------------------------------------------------------ |
125
- | `HEAPCHECK` | — | Leak-checking mode (`minimal`, `normal`, `strict`, or `draconian`); enabled when set |
166
+ | `HEAPCHECK` | — | Leak-checking mode, enabled when set (`minimal`, `normal`, `strict`, or `draconian`) |
126
167
 
127
168
  ### Programmatic API
128
169
 
@@ -138,10 +179,21 @@ if (!checker.NoLeaks()) abort(); // fails if any net allocation leaked
138
179
 
139
180
  ## System profiling
140
181
 
141
- [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler that
142
- samples on-CPU stacks and records a stack each time a thread sleeps, across user
143
- and kernel code. It needs root (BPF) and a kernel with BTF
144
- (`/sys/kernel/btf/vmlinux`).
182
+ Samples on-CPU stacks and records a stack each time a thread sleeps, across user
183
+ and kernel code. Useful for costs outside the process: off-CPU waits, syscall
184
+ time, and contention across the whole node.
185
+
186
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler. It
187
+ needs root (BPF) and a kernel with BTF (`/sys/kernel/btf/vmlinux`).
188
+
189
+ Build what you profile with frame pointers so systing's unwinder can walk the
190
+ stack, and with symbols for readable frames:
191
+
192
+ ```sh
193
+ gcc -O2 -g -fno-omit-frame-pointer -o program program.c
194
+ ```
195
+
196
+ ### CLI
145
197
 
146
198
  ```sh
147
199
  # Record a command (and its children) for 30 seconds
@@ -151,22 +203,57 @@ sudo systing --duration 30 --output profile.systing -- ./program args
151
203
  sudo systing --duration 30 --output profile.systing --pid <pid>
152
204
  ```
153
205
 
154
- Build what you profile with frame pointers so systing's unwinder can walk the
155
- stack, and with symbols for readable frames:
206
+ #### Flags
207
+
208
+ | Flag | Default | Description |
209
+ | --------------------------------- | ---------- | ---------------------------------------------------------------- |
210
+ | `--duration` | — | Recording duration in seconds |
211
+ | `--output` | `trace.pb` | Output path, where `.systing` selects the export this tool reads |
212
+ | `--sample-freq` | `1000` | CPU stack-sampling rate in Hz |
213
+ | `--no-sleep-stack-traces` | off | Skip uninterruptible-sleep stacks |
214
+ | `--no-interruptible-stack-traces` | off | Skip interruptible-sleep stacks |
215
+
216
+ ## Linux perf profiling
217
+
218
+ Samples the call stack through the kernel's own `perf_event` counters, across
219
+ user and kernel code. Useful for finding CPU hot spots, including the ones in
220
+ the kernel.
221
+
222
+ [Linux `perf`](https://perfwiki.github.io/main/) samples any native program and
223
+ writes `perf.data` itself. It needs a Linux kernel and a
224
+ `/proc/sys/kernel/perf_event_paranoid` low enough to permit sampling (`1` or
225
+ below for kernel stacks).
226
+
227
+ Build with frame pointers so perf's unwinder can walk the stack:
156
228
 
157
229
  ```sh
158
- gcc -O2 -g -fno-omit-frame-pointer -o program program.c
230
+ gcc -O2 -g -fno-omit-frame-pointer -o program program.c # C
231
+ g++ -O2 -g -fno-omit-frame-pointer -o program program.cpp # C++
232
+ ```
233
+
234
+ ### CLI
235
+
236
+ ```sh
237
+ # Sample a command at 999 Hz, recording call chains
238
+ perf record -F 999 -g -o perf.data -- ./program args
239
+
240
+ # Or sample a running process for 30 seconds
241
+ perf record -F 999 -g -o perf.data --pid <pid> -- sleep 30
159
242
  ```
160
243
 
161
- ### CLI flags
244
+ #### Flags
245
+
246
+ | Flag | Default | Description |
247
+ | -------------- | ----------- | -------------------------------------------------------------------- |
248
+ | `-F` | `4000` | Samples per second |
249
+ | `-e` | `cycles` | Event to sample (`cpu-clock` where no hardware counter is available) |
250
+ | `-g` | off | Record call chains |
251
+ | `--call-graph` | `fp` | How to unwind: `fp`, `dwarf` (larger files), or `lbr` |
252
+ | `-o` | `perf.data` | Output path |
253
+ | `-a` | off | Sample every CPU on the system rather than one command |
162
254
 
163
- | Flag | Default | Description |
164
- | --------------------------------- | ---------- | ------------------------------------------------------------------ |
165
- | `--duration` | — | Recording duration in seconds |
166
- | `--output` | `trace.pb` | Output path; `.systing` selects the profile export this tool reads |
167
- | `--sample-freq` | `1000` | CPU stack-sampling rate in Hz |
168
- | `--no-sleep-stack-traces` | off | Skip uninterruptible-sleep stacks |
169
- | `--no-interruptible-stack-traces` | off | Skip interruptible-sleep stacks |
255
+ A `perf.data` file holds addresses rather than function names. See
256
+ `profiler-md --help perf` for how frames are named and how to symbolize them.
170
257
 
171
258
  ## Tips
172
259
 
@@ -174,20 +261,20 @@ gcc -O2 -g -fno-omit-frame-pointer -o program program.c
174
261
 
175
262
  gperftools symbolizes addresses from the binary's and its shared libraries'
176
263
  symbol tables, so build and link what you profile with symbols (`-g`, not
177
- stripped). If the hot code lives in a stripped shared library, statically link
178
- an unstripped build instead.
264
+ stripped). If the hot code is in a stripped shared library, statically link an
265
+ unstripped build instead.
179
266
 
180
267
  ### Linking
181
268
 
182
- Modern toolchains link with `--as-needed` by default, which drops
183
- `-lprofiler`/`-ltcmalloc` when your program references no symbol from them,
184
- exactly the case when you enable profiling through the environment variables
185
- instead of the programmatic API. Force the link with `-Wl,--no-as-needed`, or
186
- preload the library at runtime with `LD_PRELOAD`. The programmatic API
187
- (`ProfilerStart`, etc.) references the symbols, so plain
188
- `-lprofiler`/`-ltcmalloc` works there.
269
+ Modern toolchains link with `--as-needed` by default, so the linker drops
270
+ `-lprofiler`/`-ltcmalloc` when the program references no symbol from them. That
271
+ is the case when you enable profiling through environment variables instead of
272
+ the programmatic API. Force the link with `-Wl,--no-as-needed`, or preload the
273
+ library at runtime with `LD_PRELOAD`. The programmatic API (`ProfilerStart`,
274
+ etc.) references the symbols, so plain `-lprofiler`/`-ltcmalloc` works there.
189
275
 
190
276
  ### Converting
191
277
 
192
- `pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
193
- `pprof`/`google-pprof` has no protobuf output.
278
+ `pprof --proto` requires the Go `pprof`. gperftools stopped shipping a `pprof`
279
+ of its own in 2.17, and the Perl `pprof`/`google-pprof` that earlier releases
280
+ and the distro packages built from them install has no protobuf output.
@@ -26,8 +26,8 @@ stacks at roughly 100 Hz.
26
26
  # Attach to a running process, written directly as speedscope
27
27
  dotnet-trace collect --process-id <pid> --format speedscope
28
28
 
29
- # Launch and trace a command from startup (use `dotnet exec` so the dotnet CLI's
30
- # own child processes aren't traced instead of your app)
29
+ # Launch and trace a command from startup (`dotnet exec` traces your app rather
30
+ # than the dotnet CLI's own child processes)
31
31
  dotnet-trace collect --format speedscope -- dotnet exec app.dll
32
32
 
33
33
  # Attach for a fixed duration (dd:hh:mm:ss)
@@ -44,7 +44,9 @@ dotnet-trace convert trace.nettrace --format speedscope
44
44
  | `-p` / `--process-id` | — | PID of the process to trace |
45
45
  | `-n` / `--name` | — | Name of the process to trace |
46
46
  | `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
47
- | `-o` / `--output` | `nettrace` | Output file path |
47
+ | `-o` / `--output` | see below | Output file path |
48
48
  | `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
49
49
  | `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
50
50
  | `--providers` | — | Comma-separated EventPipe providers to enable |
51
+
52
+ Without `-o`, the trace is written to `<appname>_<yyyyMMdd>_<HHmmss>.nettrace`.
@@ -3,17 +3,17 @@
3
3
  Elixir and Erlang profiling uses
4
4
  [eflambe](https://github.com/Stratus3D/eflambe).
5
5
 
6
- ## CPU profiling
6
+ ## Wall-clock profiling
7
7
 
8
8
  Traces function calls and writes them as collapsed stacks. Useful for finding
9
- CPU hot spots.
9
+ hot spots, including time spent sleeping, which eflambe records as its own
10
+ frame.
10
11
 
11
12
  eflambe's default `brendan_gregg` format is collapsed stacks. Add `eflambe` to
12
13
  your dependencies, then profile a specific function.
13
14
 
14
- **Keep the call small.** eflambe traces _every_ function call. It doesn't
15
- sample, so output grows with the number of calls. A single invocation over a
16
- large input can produce hundreds of MB.
15
+ Each line's count is one microsecond of wall time on its stack, not one sample,
16
+ because eflambe derives the counts from the trace's timestamps.
17
17
 
18
18
  ### Elixir
19
19
 
@@ -37,9 +37,17 @@ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_g
37
37
 
38
38
  ### Options
39
39
 
40
- | Option | Default | Description |
41
- | ------------------ | --------------- | --------------------------------------------------- |
42
- | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
43
- | `output_directory` | project root | Directory for the output file |
44
- | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
45
- | `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
40
+ | Option | Default | Description |
41
+ | ------------------ | --------------- | -------------------------------------------------------------------------------------------------------- |
42
+ | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
43
+ | `output_directory` | `./` | Directory for the output file |
44
+ | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
45
+ | `return` | see description | Return value: `value`, `flamegraph`, or `filename`. `capture` returns the filename and `apply` the value |
46
+
47
+ ## Tips
48
+
49
+ ### Overhead
50
+
51
+ Keep the call small. eflambe traces every function call instead of sampling, so
52
+ output grows with the number of calls. A single invocation over a large input
53
+ can produce hundreds of MB.
@@ -0,0 +1,141 @@
1
+ # Fortran
2
+
3
+ Fortran profiling uses [gperftools](https://github.com/gperftools/gperftools),
4
+ whose CPU profiler and tcmalloc heap profiler attach to any dynamically linked
5
+ native program, including one built by `gfortran`, `ifx`, or `flang`.
6
+
7
+ ## CPU profiling
8
+
9
+ Periodically samples the call stack. Useful for finding CPU hot spots.
10
+
11
+ Keep frame pointers so the profiler's unwinder can walk the stack, and debug
12
+ info so its frames contain source locations:
13
+
14
+ ```sh
15
+ gfortran -O2 -g -fno-omit-frame-pointer -o program program.f90
16
+ ```
17
+
18
+ ### CLI
19
+
20
+ ```sh
21
+ # Generate a CPU profile
22
+ CPUPROFILE=cpu.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libprofiler.so ./program
23
+
24
+ # Convert to pprof protobuf format
25
+ pprof --proto ./program cpu.prof > cpu.pprof
26
+ ```
27
+
28
+ #### Environment variables
29
+
30
+ | Variable | Default | Description |
31
+ | ---------------------- | ------- | -------------------------------------------------------------------------------- |
32
+ | `CPUPROFILE` | — | Output filename that enables profiling when set |
33
+ | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
34
+ | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
35
+ | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
36
+
37
+ ### Programmatic API
38
+
39
+ Declare the C entry points through `iso_c_binding` and link `-lprofiler`:
40
+
41
+ ```fortran
42
+ use iso_c_binding, only: c_char, c_int, c_null_char
43
+ interface
44
+ function profiler_start(filename) bind(C, name='ProfilerStart')
45
+ import :: c_char, c_int
46
+ character(kind=c_char), intent(in) :: filename(*)
47
+ integer(c_int) :: profiler_start
48
+ end function
49
+ subroutine profiler_stop() bind(C, name='ProfilerStop')
50
+ end subroutine
51
+ end interface
52
+
53
+ if (profiler_start('cpu.prof'//c_null_char) == 0) error stop 'ProfilerStart failed'
54
+
55
+ ! Code to profile...
56
+
57
+ call profiler_stop()
58
+ ```
59
+
60
+ ```sh
61
+ gfortran -O2 -g -fno-omit-frame-pointer -Wl,--no-as-needed -lprofiler \
62
+ -o program program.f90
63
+ ```
64
+
65
+ ## Memory profiling
66
+
67
+ Periodically dumps the live heap, capturing allocation stack traces. Useful for
68
+ finding memory leaks and allocation hot spots.
69
+
70
+ `allocate` and the temporaries the compiler creates for allocatable and
71
+ automatic arrays go through `malloc`, so tcmalloc records them.
72
+
73
+ ### CLI
74
+
75
+ ```sh
76
+ # Generate heap profiles (written as <prefix>.0001.heap, .0002.heap, …)
77
+ HEAPPROFILE=heap.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libtcmalloc.so ./program
78
+
79
+ # Convert a heap profile to pprof protobuf format
80
+ pprof --proto ./program heap.prof.0001.heap > heap.pprof
81
+ ```
82
+
83
+ #### Environment variables
84
+
85
+ | Variable | Default | Description |
86
+ | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
87
+ | `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set |
88
+ | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
89
+ | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
90
+ | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
91
+ | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
92
+ | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
93
+
94
+ ### Programmatic API
95
+
96
+ Declare the C entry points and link `-ltcmalloc`:
97
+
98
+ ```fortran
99
+ use iso_c_binding, only: c_char, c_null_char
100
+ interface
101
+ subroutine heap_profiler_start(prefix) bind(C, name='HeapProfilerStart')
102
+ import :: c_char
103
+ character(kind=c_char), intent(in) :: prefix(*)
104
+ end subroutine
105
+ subroutine heap_profiler_stop() bind(C, name='HeapProfilerStop')
106
+ end subroutine
107
+ end interface
108
+
109
+ call heap_profiler_start('heap.prof'//c_null_char)
110
+
111
+ ! Code to profile...
112
+
113
+ call heap_profiler_stop()
114
+ ```
115
+
116
+ ## Tips
117
+
118
+ ### Names
119
+
120
+ `gfortran` mangles a module procedure to `__<module>_MOD_<procedure>` and a
121
+ free-standing procedure to `<procedure>_`. The program body appears as `MAIN__`.
122
+ A procedure the compiler specialized or partly inlined gets a suffix such as
123
+ `.part.0` or `.constprop.0`.
124
+
125
+ ### Optimization
126
+
127
+ `-O0` frames are easy to read, but the timings differ from a release build's.
128
+ Profile the `-O2` or `-O3` build you ship, and expect inlining to attribute some
129
+ samples to the caller.
130
+
131
+ ### Threads
132
+
133
+ An OpenMP program runs its worker threads in the same process, so the profile
134
+ covers all of them. Set `OMP_NUM_THREADS=1` to profile the serial path first,
135
+ because a parallel region spreads one hot loop across every worker's stack.
136
+
137
+ ### Converting
138
+
139
+ `pprof --proto` requires the Go `pprof`. gperftools stopped shipping a `pprof`
140
+ of its own in 2.17, and the Perl `pprof`/`google-pprof` that earlier releases
141
+ and the distro packages built from them install has no protobuf output.
@@ -1,6 +1,6 @@
1
1
  # Go
2
2
 
3
- Go supports pprof natively via the
3
+ Go profiling uses pprof, built into the runtime as the
4
4
  [`runtime/pprof`](https://pkg.go.dev/runtime/pprof) package and the
5
5
  [`net/http/pprof`](https://pkg.go.dev/net/http/pprof) HTTP handler.
6
6
 
@@ -38,12 +38,12 @@ defer pprof.StopCPUProfile()
38
38
 
39
39
  ## Memory profiling
40
40
 
41
- Heap profiles come in two variants:
41
+ The heap profile variants are:
42
42
 
43
- - **heap** (`inuse_space` / `inuse_objects`): live allocations at each sample;
43
+ - **heap** (`inuse_space` / `inuse_objects`): live allocations at each sample,
44
44
  useful for finding memory leaks
45
45
  - **allocs** (`alloc_space` / `alloc_objects`): all allocations since program
46
- start; useful for finding allocation hot spots
46
+ start, useful for finding allocation hot spots
47
47
 
48
48
  `runtime.MemProfileRate` controls sampling granularity (default: one sample per
49
49
  512 KB allocated). Set to `1` to capture every allocation (expensive):
@@ -93,7 +93,7 @@ leaks or deadlocks.
93
93
  ### CLI
94
94
 
95
95
  ```sh
96
- # Full stack traces (debug=2 gives text output, debug=0 gives pprof binary)
96
+ # Full stack traces (`debug=2` writes text, and `debug=0` the pprof binary)
97
97
  curl -o goroutine.pprof 'http://localhost:6060/debug/pprof/goroutine'
98
98
 
99
99
  # Human-readable text dump
@@ -107,6 +107,27 @@ f, _ := os.Create("goroutine.pprof")
107
107
  pprof.Lookup("goroutine").WriteTo(f, 0)
108
108
  ```
109
109
 
110
+ ## Goroutine leak profiling
111
+
112
+ Captures stack traces of leaked goroutines: goroutines blocked on a channel,
113
+ mutex, or other concurrency primitive that no runnable goroutine can reach.
114
+ Requires Go 1.27, though Go 1.26 supports it behind
115
+ `GOEXPERIMENT=goroutineleakprofile`. Writing the profile first runs a garbage
116
+ collection cycle that detects the leaks.
117
+
118
+ ### CLI
119
+
120
+ ```sh
121
+ curl -o goroutineleak.pprof 'http://localhost:6060/debug/pprof/goroutineleak'
122
+ ```
123
+
124
+ ### Programmatic API
125
+
126
+ ```go
127
+ f, _ := os.Create("goroutineleak.pprof")
128
+ pprof.Lookup("goroutineleak").WriteTo(f, 0)
129
+ ```
130
+
110
131
  ## Block profiling
111
132
 
112
133
  Captures stack traces that led to blocking on synchronization primitives
@@ -115,7 +136,7 @@ diagnosing synchronization bottlenecks.
115
136
 
116
137
  Disabled by default. Call `runtime.SetBlockProfileRate(rate)` in your program
117
138
  before the code to profile. This applies whether you collect via HTTP or the
118
- programmatic API. Rate is in nanoseconds: `1` captures every blocking event;
139
+ programmatic API. Rate is in nanoseconds. `1` captures every blocking event, and
119
140
  higher values sample less.
120
141
 
121
142
  ```go
@@ -146,8 +167,8 @@ goroutine tries to acquire it. Useful for finding lock contention hot spots.
146
167
 
147
168
  Disabled by default. Call `runtime.SetMutexProfileFraction(rate)` in your
148
169
  program before the code to profile. This applies whether you collect via HTTP or
149
- the programmatic API. `1` captures every contended event; `n` samples roughly
150
- `1/n` events.
170
+ the programmatic API. `1` captures every contended event, and `n` samples
171
+ roughly `1/n` events.
151
172
 
152
173
  ```go
153
174
  runtime.SetMutexProfileFraction(1)
@@ -170,8 +191,8 @@ pprof.Lookup("mutex").WriteTo(f, 0)
170
191
 
171
192
  ## Thread creation profiling
172
193
 
173
- Captures stack traces that create new OS threads. Useful for diagnosing
174
- unexpected thread proliferation.
194
+ Captures the stack traces where the program created new OS threads. Useful for
195
+ finding code that creates too many threads.
175
196
 
176
197
  ### CLI
177
198
 
@@ -188,5 +209,7 @@ pprof.Lookup("threadcreate").WriteTo(f, 0)
188
209
 
189
210
  ## Tips
190
211
 
212
+ ### Locations
213
+
191
214
  Build with `-trimpath` (e.g. `go test -trimpath ...`) so locations are
192
215
  package-relative (`encoding/json/encode.go`) instead of absolute build paths.