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,6 +1,9 @@
1
1
  # C/C++
2
2
 
3
- C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools).
3
+ C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools),
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).
4
7
 
5
8
  ## CPU profiling
6
9
 
@@ -27,7 +30,7 @@ pprof --proto ./program cpu.prof > cpu.pprof
27
30
 
28
31
  | Variable | Default | Description |
29
32
  | ---------------------- | ------- | -------------------------------------------------------------------------------- |
30
- | `CPUPROFILE` | — | Output filename; profiling is enabled when set |
33
+ | `CPUPROFILE` | — | Output filename that enables profiling when set |
31
34
  | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
32
35
  | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
33
36
  | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
@@ -60,7 +63,7 @@ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
60
63
  ### CLI
61
64
 
62
65
  ```sh
63
- # Generate heap profiles (written as <prefix>.0000.heap, .0001.heap, …)
66
+ # Generate heap profiles (written as <prefix>.0001.heap, .0002.heap, …)
64
67
  HEAPPROFILE=heap.prof ./program
65
68
 
66
69
  # Convert a heap profile to pprof protobuf format
@@ -71,13 +74,13 @@ pprof --proto ./program heap.prof.0001.heap > heap.pprof
71
74
 
72
75
  | Variable | Default | Description |
73
76
  | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
74
- | `HEAPPROFILE` | — | Output filename prefix; heap profiling is enabled when set |
77
+ | `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set |
75
78
  | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
76
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) |
77
80
  | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
78
81
  | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
79
82
  | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
80
- | `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` |
81
84
 
82
85
  ### Programmatic API
83
86
 
@@ -92,11 +95,50 @@ HeapProfilerDump("checkpoint"); // optional mid-run profile dump
92
95
  HeapProfilerStop();
93
96
  ```
94
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
+
95
133
  ## Heap checking
96
134
 
97
135
  Compares the heap state before and after a region of code to detect memory
98
136
  leaks. Useful for confirming a code path frees everything it allocates.
99
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
+
100
142
  Link with `-ltcmalloc`:
101
143
 
102
144
  ```sh
@@ -121,7 +163,7 @@ HEAPCHECK=draconian ./program
121
163
 
122
164
  | Variable | Default | Description |
123
165
  | ----------- | ------- | ------------------------------------------------------------------------------------ |
124
- | `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`) |
125
167
 
126
168
  ### Programmatic API
127
169
 
@@ -132,29 +174,107 @@ HeapLeakChecker checker("my_check");
132
174
 
133
175
  // Code to check...
134
176
 
135
- if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
177
+ if (!checker.NoLeaks()) abort(); // fails if any net allocation leaked
178
+ ```
179
+
180
+ ## System profiling
181
+
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
197
+
198
+ ```sh
199
+ # Record a command (and its children) for 30 seconds
200
+ sudo systing --duration 30 --output profile.systing -- ./program args
201
+
202
+ # Or attach to a running process
203
+ sudo systing --duration 30 --output profile.systing --pid <pid>
136
204
  ```
137
205
 
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:
228
+
229
+ ```sh
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
242
+ ```
243
+
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 |
254
+
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.
257
+
138
258
  ## Tips
139
259
 
140
260
  ### Symbols
141
261
 
142
262
  gperftools symbolizes addresses from the binary's and its shared libraries'
143
263
  symbol tables, so build and link what you profile with symbols (`-g`, not
144
- stripped). If the hot code lives in a stripped shared library, statically link
145
- an unstripped build instead.
264
+ stripped). If the hot code is in a stripped shared library, statically link an
265
+ unstripped build instead.
146
266
 
147
267
  ### Linking
148
268
 
149
- Modern toolchains link with `--as-needed` by default, which drops
150
- `-lprofiler`/`-ltcmalloc` when your program references no symbol from them,
151
- exactly the case when you enable profiling through the environment variables
152
- instead of the programmatic API. Force the link with `-Wl,--no-as-needed`, or
153
- preload the library at runtime with `LD_PRELOAD`. The programmatic API
154
- (`ProfilerStart`, etc.) references the symbols, so plain
155
- `-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.
156
275
 
157
276
  ### Converting
158
277
 
159
- `pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
160
- `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.
@@ -1,9 +1,7 @@
1
1
  # C#/F#
2
2
 
3
3
  .NET profiling (C#, F#, and other CLR languages) uses
4
- [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace),
5
- a cross-platform diagnostics tool that collects traces through the runtime's
6
- EventPipe without a native profiler.
4
+ [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace).
7
5
 
8
6
  Install it as a global tool:
9
7
 
@@ -11,7 +9,7 @@ Install it as a global tool:
11
9
  dotnet tool install --global dotnet-trace
12
10
  ```
13
11
 
14
- The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
12
+ The latest `dotnet-trace` needs a matching .NET runtime. If yours is older,
15
13
  install a compatible version with `--version`.
16
14
 
17
15
  ## CPU profiling
@@ -28,8 +26,8 @@ stacks at roughly 100 Hz.
28
26
  # Attach to a running process, written directly as speedscope
29
27
  dotnet-trace collect --process-id <pid> --format speedscope
30
28
 
31
- # Launch and trace a command from startup (use `dotnet exec` so the dotnet CLI's
32
- # 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)
33
31
  dotnet-trace collect --format speedscope -- dotnet exec app.dll
34
32
 
35
33
  # Attach for a fixed duration (dd:hh:mm:ss)
@@ -46,7 +44,9 @@ dotnet-trace convert trace.nettrace --format speedscope
46
44
  | `-p` / `--process-id` | — | PID of the process to trace |
47
45
  | `-n` / `--name` | — | Name of the process to trace |
48
46
  | `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
49
- | `-o` / `--output` | `nettrace` | Output file path |
47
+ | `-o` / `--output` | see below | Output file path |
50
48
  | `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
51
49
  | `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
52
50
  | `--providers` | — | Comma-separated EventPipe providers to enable |
51
+
52
+ Without `-o`, the trace is written to `<appname>_<yyyyMMdd>_<HHmmss>.nettrace`.
@@ -1,25 +1,24 @@
1
1
  # Elixir/Erlang
2
2
 
3
3
  Elixir and Erlang profiling uses
4
- [eflambe](https://github.com/Stratus3D/eflambe), a BEAM profiler that wraps the
5
- runtime's built-in tracing and writes flame graph output.
4
+ [eflambe](https://github.com/Stratus3D/eflambe).
6
5
 
7
- ## CPU profiling
6
+ ## Wall-clock profiling
8
7
 
9
8
  Traces function calls and writes them as collapsed stacks. Useful for finding
10
- CPU hot spots.
9
+ hot spots, including time spent sleeping, which eflambe records as its own
10
+ frame.
11
11
 
12
12
  eflambe's default `brendan_gregg` format is collapsed stacks. Add `eflambe` to
13
13
  your dependencies, then profile a specific function.
14
14
 
15
- **Keep the call small.** eflambe traces _every_ function call. It doesn't
16
- sample, so output grows with the number of calls. A single invocation over a
17
- 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.
18
17
 
19
18
  ### Elixir
20
19
 
21
20
  ```elixir
22
- # Profile a function as it runs during normal execution (capture 1 call)
21
+ # Profile a function during normal execution (capture 1 call)
23
22
  :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
24
23
 
25
24
  # Directly invoke and profile a function
@@ -29,7 +28,7 @@ large input can produce hundreds of MB.
29
28
  ### Erlang
30
29
 
31
30
  ```erlang
32
- %% Profile a function as it runs during normal execution (capture 1 call)
31
+ %% Profile a function during normal execution (capture 1 call)
33
32
  eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
34
33
 
35
34
  %% Directly invoke and profile a function
@@ -38,9 +37,17 @@ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_g
38
37
 
39
38
  ### Options
40
39
 
41
- | Option | Default | Description |
42
- | ------------------ | --------------- | --------------------------------------------------- |
43
- | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
44
- | `output_directory` | project root | Directory to write the output file to |
45
- | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
46
- | `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
@@ -114,9 +135,9 @@ Captures stack traces that led to blocking on synchronization primitives
114
135
  diagnosing synchronization bottlenecks.
115
136
 
116
137
  Disabled by default. Call `runtime.SetBlockProfileRate(rate)` in your program
117
- before the code you want to profile. This applies whether you collect via HTTP
118
- or the programmatic API. Rate is in nanoseconds: `1` captures every blocking
119
- event; higher values sample less.
138
+ before the code to profile. This applies whether you collect via HTTP or the
139
+ programmatic API. Rate is in nanoseconds. `1` captures every blocking event, and
140
+ higher values sample less.
120
141
 
121
142
  ```go
122
143
  runtime.SetBlockProfileRate(1)
@@ -145,9 +166,9 @@ Captures stack traces of goroutines holding a contended mutex when another
145
166
  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
- program before the code you want to profile. This applies whether you collect
149
- via HTTP or the programmatic API. `1` captures every contended event; `n`
150
- samples roughly `1/n` events.
169
+ program before the code to profile. This applies whether you collect via HTTP or
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.