profiler-md 0.3.0 → 0.5.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 (225) hide show
  1. package/dist/cli/index.mjs +5331 -2044
  2. package/dist/index.d.mts +738 -229
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/formats/jfr.md +16 -0
  6. package/docs/formats/jsc-heap-snapshot.md +2 -2
  7. package/docs/languages/c.md +31 -7
  8. package/docs/languages/cpp.md +160 -0
  9. package/docs/languages/csharp.md +52 -0
  10. package/docs/languages/elixir.md +46 -0
  11. package/docs/languages/erlang.md +46 -0
  12. package/docs/languages/fsharp.md +52 -0
  13. package/docs/languages/go.md +11 -6
  14. package/docs/languages/java.md +110 -57
  15. package/docs/languages/javascript.md +69 -12
  16. package/docs/languages/julia.md +54 -0
  17. package/docs/languages/kotlin.md +170 -0
  18. package/docs/languages/php.md +64 -20
  19. package/docs/languages/python.md +13 -68
  20. package/docs/languages/ruby.md +17 -27
  21. package/docs/languages/typescript.md +276 -0
  22. package/examples/output/c.gperftools.cpu.base.pprof.md +324 -0
  23. package/examples/output/c.gperftools.cpu.current.pprof.md +271 -0
  24. package/examples/output/c.gperftools.cpu.diff.pprof.md +98 -0
  25. package/examples/output/c.gperftools.heap.base.pprof.md +362 -0
  26. package/examples/output/c.gperftools.heap.current.pprof.md +362 -0
  27. package/examples/output/c.gperftools.heap.diff.pprof.md +28 -0
  28. package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
  29. package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
  30. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
  31. package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
  32. package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
  33. package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
  34. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
  35. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
  36. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
  37. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
  38. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
  39. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
  40. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
  41. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
  42. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
  43. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
  44. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
  45. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
  46. package/examples/output/go.pprof.block.base.pprof.md +86 -0
  47. package/examples/output/go.pprof.block.current.pprof.md +83 -0
  48. package/examples/output/go.pprof.block.diff.pprof.md +42 -0
  49. package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
  50. package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
  51. package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
  52. package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
  53. package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
  54. package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
  55. package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
  56. package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
  57. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
  58. package/examples/output/go.pprof.heap.base.pprof.md +154 -0
  59. package/examples/output/go.pprof.heap.current.pprof.md +146 -0
  60. package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
  61. package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
  62. package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
  63. package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
  64. package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
  65. package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
  66. package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
  67. package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
  68. package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
  69. package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
  70. package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
  71. package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
  72. package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
  73. package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
  74. package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
  75. package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
  76. package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
  77. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
  78. package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
  79. package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
  80. package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
  81. package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
  82. package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
  83. package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
  84. package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
  85. package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
  86. package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
  87. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
  88. package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
  89. package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
  90. package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
  91. package/examples/output/java.jdk.all.base.jfr.md +1024 -0
  92. package/examples/output/java.jdk.all.current.jfr.md +1010 -0
  93. package/examples/output/java.jdk.all.diff.jfr.md +311 -0
  94. package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
  95. package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
  96. package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
  97. package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
  98. package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
  99. package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
  100. package/examples/output/java.jdk.live.base.jfr.md +1029 -0
  101. package/examples/output/java.jdk.live.current.jfr.md +1035 -0
  102. package/examples/output/java.jdk.live.diff.jfr.md +289 -0
  103. package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
  104. package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
  105. package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
  106. package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
  107. package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
  108. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
  109. package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
  110. package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
  111. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
  112. package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
  113. package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
  114. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
  115. package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
  116. package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
  117. package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
  118. package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
  119. package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
  120. package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
  121. package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
  122. package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
  123. package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
  124. package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
  125. package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
  126. package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
  127. package/examples/output/javascript.node.base.cpuprofile.md +136 -0
  128. package/examples/output/javascript.node.base.heapprofile.md +56 -0
  129. package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
  130. package/examples/output/javascript.node.current.cpuprofile.md +119 -0
  131. package/examples/output/javascript.node.current.heapprofile.md +52 -0
  132. package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
  133. package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
  134. package/examples/output/javascript.node.diff.heapprofile.md +34 -0
  135. package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
  136. package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
  137. package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
  138. package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
  139. package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
  140. package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
  141. package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
  142. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
  143. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
  144. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
  145. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
  146. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
  147. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
  148. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
  149. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
  150. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
  151. package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
  152. package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
  153. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
  154. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
  155. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
  156. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
  157. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
  158. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
  159. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
  160. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
  161. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
  162. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
  163. package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
  164. package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
  165. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
  166. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
  167. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
  168. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
  169. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
  170. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
  171. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
  172. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
  173. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
  174. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
  175. package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
  176. package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
  177. package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
  178. package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
  179. package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
  180. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
  181. package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
  182. package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
  183. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
  184. package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
  185. package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
  186. package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
  187. package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
  188. package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
  189. package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
  190. package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
  191. package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
  192. package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
  193. package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
  194. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
  195. package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
  196. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
  197. package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
  198. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
  199. package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
  200. package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
  201. package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
  202. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
  203. package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
  204. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
  205. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
  206. package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
  207. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
  208. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
  209. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
  210. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
  211. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
  212. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
  213. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
  214. package/package.json +27 -20
  215. package/readme.md +201 -87
  216. package/examples/bun.cpuprofile.md +0 -475
  217. package/examples/deno.cpuprofile.md +0 -481
  218. package/examples/jsc-heap-snapshot.json.md +0 -509
  219. package/examples/node.cpuprofile.md +0 -485
  220. package/examples/node.heapprofile.md +0 -281
  221. package/examples/node.heapsnapshot.md +0 -694
  222. package/examples/node.pprof.md +0 -441
  223. package/examples/node.speedscope.json.md +0 -408
  224. package/examples/rust.pprof.md +0 -477
  225. package/examples/webkit-timeline-recording.json.md +0 -434
@@ -0,0 +1,12 @@
1
+ # Collapsed stacks
2
+
3
+ Collapsed stacks is the plain-text interchange format from Brendan Gregg's
4
+ [FlameGraph](https://github.com/brendangregg/FlameGraph) tooling. It is emitted
5
+ by many profilers.
6
+
7
+ Each line is one call stack, written root-to-leaf and joined by `;`, followed by
8
+ a space and an integer sample count. Frames are opaque strings and carry no
9
+ units.
10
+
11
+ Files have no standard extension; `.collapsed`, `.folded`, and `.txt` are all
12
+ common.
@@ -0,0 +1,16 @@
1
+ # JFR
2
+
3
+ [JFR](https://openjdk.org/jeps/328) (Java Flight Recorder) is the JVM's native
4
+ binary profiling format, written by the JDK's built-in
5
+ [Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) and
6
+ [async-profiler](https://github.com/async-profiler/async-profiler).
7
+
8
+ A recording splits into self-contained chunks of LEB128 varint-encoded events.
9
+ One recording can mix event kinds, so it converts to one profile per kind:
10
+ CPU/wall sampling measured by sample count, heap and native memory allocation
11
+ sampling measured by allocated bytes, and lock contention measured by blocked
12
+ time.
13
+
14
+ It supports one metric per profile and multiple profiles per file.
15
+
16
+ Files use the `.jfr` extension.
@@ -9,5 +9,5 @@ Unlike heap profiles, which sample allocations, snapshots show what objects
9
9
  currently exist in memory. This is useful for diagnosing memory leaks rather
10
10
  than allocation hotspots.
11
11
 
12
- Files use the `.json` extension and contain `"type": "Inspector"` and
13
- `"version": 2` fields.
12
+ Files use the `.json` extension and contain `"type": "Inspector"` and a
13
+ `"version"` of `2` (Safari/JSC) or `3` (Bun's `generateHeapSnapshot("jsc")`).
@@ -9,8 +9,8 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
9
9
  Link with `-lprofiler`:
10
10
 
11
11
  ```sh
12
- gcc -O2 -lprofiler -o program program.c # C
13
- g++ -O2 -lprofiler -o program program.cpp # C++
12
+ gcc -O2 -Wl,--no-as-needed -lprofiler -o program program.c # C
13
+ g++ -O2 -Wl,--no-as-needed -lprofiler -o program program.cpp # C++
14
14
  ```
15
15
 
16
16
  ### CLI
@@ -53,8 +53,8 @@ finding memory leaks and allocation hot spots.
53
53
  Link with `-ltcmalloc`:
54
54
 
55
55
  ```sh
56
- gcc -O2 -ltcmalloc -o program program.c # C
57
- g++ -O2 -ltcmalloc -o program program.cpp # C++
56
+ gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
57
+ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
58
58
  ```
59
59
 
60
60
  ### CLI
@@ -95,13 +95,13 @@ HeapProfilerStop();
95
95
  ## Heap checking
96
96
 
97
97
  Compares the heap state before and after a region of code to detect memory
98
- leaks. Useful for confirming that a code path frees everything it allocates.
98
+ leaks. Useful for confirming a code path frees everything it allocates.
99
99
 
100
100
  Link with `-ltcmalloc`:
101
101
 
102
102
  ```sh
103
- gcc -O2 -ltcmalloc -o program program.c # C
104
- g++ -O2 -ltcmalloc -o program program.cpp # C++
103
+ gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
104
+ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
105
105
  ```
106
106
 
107
107
  ### CLI
@@ -134,3 +134,27 @@ HeapLeakChecker checker("my_check");
134
134
 
135
135
  if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
136
136
  ```
137
+
138
+ ## Tips
139
+
140
+ ### Symbols
141
+
142
+ gperftools symbolizes addresses from the binary's and its shared libraries'
143
+ 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.
146
+
147
+ ### Linking
148
+
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.
156
+
157
+ ### Converting
158
+
159
+ `pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
160
+ `pprof`/`google-pprof` has no protobuf output.
@@ -0,0 +1,160 @@
1
+ # C/C++
2
+
3
+ C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools).
4
+
5
+ ## CPU profiling
6
+
7
+ Periodically samples the call stack. Useful for finding CPU hot spots.
8
+
9
+ Link with `-lprofiler`:
10
+
11
+ ```sh
12
+ gcc -O2 -Wl,--no-as-needed -lprofiler -o program program.c # C
13
+ g++ -O2 -Wl,--no-as-needed -lprofiler -o program program.cpp # C++
14
+ ```
15
+
16
+ ### CLI
17
+
18
+ ```sh
19
+ # Generate a CPU profile
20
+ CPUPROFILE=cpu.prof ./program
21
+
22
+ # Convert to pprof protobuf format
23
+ pprof --proto ./program cpu.prof > cpu.pprof
24
+ ```
25
+
26
+ #### Environment variables
27
+
28
+ | Variable | Default | Description |
29
+ | ---------------------- | ------- | -------------------------------------------------------------------------------- |
30
+ | `CPUPROFILE` | — | Output filename; profiling is enabled when set |
31
+ | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
32
+ | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
33
+ | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
34
+
35
+ ### Programmatic API
36
+
37
+ ```c
38
+ #include <gperftools/profiler.h>
39
+
40
+ ProfilerStart("cpu.prof");
41
+
42
+ // Code to profile...
43
+
44
+ ProfilerFlush(); // optional: flush buffered samples mid-run
45
+ ProfilerStop();
46
+ ```
47
+
48
+ ## Memory profiling
49
+
50
+ Periodically dumps the live heap, capturing allocation stack traces. Useful for
51
+ finding memory leaks and allocation hot spots.
52
+
53
+ Link with `-ltcmalloc`:
54
+
55
+ ```sh
56
+ gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
57
+ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
58
+ ```
59
+
60
+ ### CLI
61
+
62
+ ```sh
63
+ # Generate heap profiles (written as <prefix>.0000.heap, .0001.heap, …)
64
+ HEAPPROFILE=heap.prof ./program
65
+
66
+ # Convert a heap profile to pprof protobuf format
67
+ pprof --proto ./program heap.prof.0001.heap > heap.pprof
68
+ ```
69
+
70
+ #### Environment variables
71
+
72
+ | Variable | Default | Description |
73
+ | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
74
+ | `HEAPPROFILE` | — | Output filename prefix; heap profiling is enabled when set |
75
+ | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
76
+ | `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
+ | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
78
+ | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
79
+ | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
80
+ | `HEAP_PROFILE_ONLY_MMAP` | `false` | Profile only `mmap`/`mremap`/`sbrk`; skip `malloc`/`new` |
81
+
82
+ ### Programmatic API
83
+
84
+ ```c
85
+ #include <gperftools/heap-profiler.h>
86
+
87
+ HeapProfilerStart("heap.prof");
88
+
89
+ // Code to profile...
90
+
91
+ HeapProfilerDump("checkpoint"); // optional mid-run profile dump
92
+ HeapProfilerStop();
93
+ ```
94
+
95
+ ## Heap checking
96
+
97
+ Compares the heap state before and after a region of code to detect memory
98
+ leaks. Useful for confirming a code path frees everything it allocates.
99
+
100
+ Link with `-ltcmalloc`:
101
+
102
+ ```sh
103
+ gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
104
+ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
105
+ ```
106
+
107
+ ### CLI
108
+
109
+ ```sh
110
+ # Report leaks at program exit
111
+ HEAPCHECK=normal ./program
112
+
113
+ # Also report still-reachable allocations at exit
114
+ HEAPCHECK=strict ./program
115
+
116
+ # Most aggressive: report all live allocations at exit
117
+ HEAPCHECK=draconian ./program
118
+ ```
119
+
120
+ #### Environment variables
121
+
122
+ | Variable | Default | Description |
123
+ | ----------- | ------- | ------------------------------------------------------------------------------------ |
124
+ | `HEAPCHECK` | — | Leak-checking mode (`minimal`, `normal`, `strict`, or `draconian`); enabled when set |
125
+
126
+ ### Programmatic API
127
+
128
+ ```c
129
+ #include <gperftools/heap-checker.h>
130
+
131
+ HeapLeakChecker checker("my_check");
132
+
133
+ // Code to check...
134
+
135
+ if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
136
+ ```
137
+
138
+ ## Tips
139
+
140
+ ### Symbols
141
+
142
+ gperftools symbolizes addresses from the binary's and its shared libraries'
143
+ 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.
146
+
147
+ ### Linking
148
+
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.
156
+
157
+ ### Converting
158
+
159
+ `pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
160
+ `pprof`/`google-pprof` has no protobuf output.
@@ -0,0 +1,52 @@
1
+ # C#/F#
2
+
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.
7
+
8
+ Install it as a global tool:
9
+
10
+ ```sh
11
+ dotnet tool install --global dotnet-trace
12
+ ```
13
+
14
+ The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
15
+ install a compatible version with `--version`.
16
+
17
+ ## CPU profiling
18
+
19
+ Periodically samples the call stack. Useful for finding CPU hot spots.
20
+
21
+ With no `--profile` or `--providers`, `dotnet-trace collect` enables the
22
+ `dotnet-common` and `dotnet-sampled-thread-time` profiles, sampling thread
23
+ stacks at roughly 100 Hz.
24
+
25
+ ### CLI
26
+
27
+ ```sh
28
+ # Attach to a running process, written directly as speedscope
29
+ dotnet-trace collect --process-id <pid> --format speedscope
30
+
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)
33
+ dotnet-trace collect --format speedscope -- dotnet exec app.dll
34
+
35
+ # Attach for a fixed duration (dd:hh:mm:ss)
36
+ dotnet-trace collect --process-id <pid> --duration 00:00:00:30 --format speedscope
37
+
38
+ # Convert an existing .nettrace to speedscope
39
+ dotnet-trace convert trace.nettrace --format speedscope
40
+ ```
41
+
42
+ #### Flags
43
+
44
+ | Flag | Default | Description |
45
+ | --------------------- | ---------- | --------------------------------------------------- |
46
+ | `-p` / `--process-id` | — | PID of the process to trace |
47
+ | `-n` / `--name` | — | Name of the process to trace |
48
+ | `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
49
+ | `-o` / `--output` | `nettrace` | Output file path |
50
+ | `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
51
+ | `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
52
+ | `--providers` | — | Comma-separated EventPipe providers to enable |
@@ -0,0 +1,46 @@
1
+ # Elixir/Erlang
2
+
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.
6
+
7
+ ## CPU profiling
8
+
9
+ Traces function calls and writes them as collapsed stacks. Useful for finding
10
+ CPU hot spots.
11
+
12
+ eflambe's default `brendan_gregg` format is collapsed stacks. Add `eflambe` to
13
+ your dependencies, then profile a specific function.
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.
18
+
19
+ ### Elixir
20
+
21
+ ```elixir
22
+ # Profile a function as it runs during normal execution (capture 1 call)
23
+ :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
24
+
25
+ # Directly invoke and profile a function
26
+ :eflambe.apply({MyModule, :my_function, [arg1, arg2]}, output_format: :brendan_gregg)
27
+ ```
28
+
29
+ ### Erlang
30
+
31
+ ```erlang
32
+ %% Profile a function as it runs during normal execution (capture 1 call)
33
+ eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
34
+
35
+ %% Directly invoke and profile a function
36
+ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_gregg}]).
37
+ ```
38
+
39
+ ### Options
40
+
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` |
@@ -0,0 +1,46 @@
1
+ # Elixir/Erlang
2
+
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.
6
+
7
+ ## CPU profiling
8
+
9
+ Traces function calls and writes them as collapsed stacks. Useful for finding
10
+ CPU hot spots.
11
+
12
+ eflambe's default `brendan_gregg` format is collapsed stacks. Add `eflambe` to
13
+ your dependencies, then profile a specific function.
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.
18
+
19
+ ### Elixir
20
+
21
+ ```elixir
22
+ # Profile a function as it runs during normal execution (capture 1 call)
23
+ :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
24
+
25
+ # Directly invoke and profile a function
26
+ :eflambe.apply({MyModule, :my_function, [arg1, arg2]}, output_format: :brendan_gregg)
27
+ ```
28
+
29
+ ### Erlang
30
+
31
+ ```erlang
32
+ %% Profile a function as it runs during normal execution (capture 1 call)
33
+ eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
34
+
35
+ %% Directly invoke and profile a function
36
+ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_gregg}]).
37
+ ```
38
+
39
+ ### Options
40
+
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` |
@@ -0,0 +1,52 @@
1
+ # C#/F#
2
+
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.
7
+
8
+ Install it as a global tool:
9
+
10
+ ```sh
11
+ dotnet tool install --global dotnet-trace
12
+ ```
13
+
14
+ The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
15
+ install a compatible version with `--version`.
16
+
17
+ ## CPU profiling
18
+
19
+ Periodically samples the call stack. Useful for finding CPU hot spots.
20
+
21
+ With no `--profile` or `--providers`, `dotnet-trace collect` enables the
22
+ `dotnet-common` and `dotnet-sampled-thread-time` profiles, sampling thread
23
+ stacks at roughly 100 Hz.
24
+
25
+ ### CLI
26
+
27
+ ```sh
28
+ # Attach to a running process, written directly as speedscope
29
+ dotnet-trace collect --process-id <pid> --format speedscope
30
+
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)
33
+ dotnet-trace collect --format speedscope -- dotnet exec app.dll
34
+
35
+ # Attach for a fixed duration (dd:hh:mm:ss)
36
+ dotnet-trace collect --process-id <pid> --duration 00:00:00:30 --format speedscope
37
+
38
+ # Convert an existing .nettrace to speedscope
39
+ dotnet-trace convert trace.nettrace --format speedscope
40
+ ```
41
+
42
+ #### Flags
43
+
44
+ | Flag | Default | Description |
45
+ | --------------------- | ---------- | --------------------------------------------------- |
46
+ | `-p` / `--process-id` | — | PID of the process to trace |
47
+ | `-n` / `--name` | — | Name of the process to trace |
48
+ | `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
49
+ | `-o` / `--output` | `nettrace` | Output file path |
50
+ | `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
51
+ | `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
52
+ | `--providers` | — | Comma-separated EventPipe providers to enable |
@@ -40,8 +40,8 @@ defer pprof.StopCPUProfile()
40
40
 
41
41
  Heap profiles come in two variants:
42
42
 
43
- - **heap** (`inuse_space` / `inuse_objects`): live allocations at the time of
44
- the time of each sample; useful for finding memory leaks
43
+ - **heap** (`inuse_space` / `inuse_objects`): live allocations at each sample;
44
+ useful for finding memory leaks
45
45
  - **allocs** (`alloc_space` / `alloc_objects`): all allocations since program
46
46
  start; useful for finding allocation hot spots
47
47
 
@@ -87,8 +87,8 @@ pprof.Lookup("allocs").WriteTo(f, 0)
87
87
 
88
88
  ## Goroutine profiling
89
89
 
90
- Captures the stack traces of all current goroutines. Useful for diagnosing
91
- goroutine leaks or deadlocks.
90
+ Captures stack traces of all current goroutines. Useful for diagnosing goroutine
91
+ leaks or deadlocks.
92
92
 
93
93
  ### CLI
94
94
 
@@ -170,8 +170,8 @@ pprof.Lookup("mutex").WriteTo(f, 0)
170
170
 
171
171
  ## Thread creation profiling
172
172
 
173
- Captures stack traces that led to the creation of new OS threads. Useful for
174
- diagnosing unexpected thread proliferation.
173
+ Captures stack traces that create new OS threads. Useful for diagnosing
174
+ unexpected thread proliferation.
175
175
 
176
176
  ### CLI
177
177
 
@@ -185,3 +185,8 @@ curl -o threadcreate.pprof 'http://localhost:6060/debug/pprof/threadcreate'
185
185
  f, _ := os.Create("threadcreate.pprof")
186
186
  pprof.Lookup("threadcreate").WriteTo(f, 0)
187
187
  ```
188
+
189
+ ## Tips
190
+
191
+ Build with `-trimpath` (e.g. `go test -trimpath ...`) so locations are
192
+ package-relative (`encoding/json/encode.go`) instead of absolute build paths.