profiler-md 0.4.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 (232) hide show
  1. package/dist/cli/index.mjs +3327 -720
  2. package/dist/index.d.mts +596 -25
  3. package/dist/index.js +2 -2
  4. package/docs/formats/jfr.md +16 -0
  5. package/docs/formats/jsc-heap-snapshot.md +2 -2
  6. package/docs/languages/c.md +31 -7
  7. package/docs/languages/cpp.md +31 -7
  8. package/docs/languages/csharp.md +3 -0
  9. package/docs/languages/elixir.md +8 -4
  10. package/docs/languages/erlang.md +8 -4
  11. package/docs/languages/fsharp.md +3 -0
  12. package/docs/languages/go.md +11 -6
  13. package/docs/languages/java.md +109 -59
  14. package/docs/languages/javascript.md +34 -12
  15. package/docs/languages/julia.md +14 -2
  16. package/docs/languages/kotlin.md +109 -59
  17. package/docs/languages/php.md +64 -20
  18. package/docs/languages/python.md +11 -72
  19. package/docs/languages/ruby.md +17 -27
  20. package/docs/languages/typescript.md +34 -12
  21. package/examples/output/c.gperftools.cpu.base.pprof.md +324 -0
  22. package/examples/output/c.gperftools.cpu.current.pprof.md +271 -0
  23. package/examples/output/c.gperftools.cpu.diff.pprof.md +98 -0
  24. package/examples/output/c.gperftools.heap.base.pprof.md +362 -0
  25. package/examples/output/c.gperftools.heap.current.pprof.md +362 -0
  26. package/examples/output/c.gperftools.heap.diff.pprof.md +28 -0
  27. package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
  28. package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
  29. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
  30. package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
  31. package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
  32. package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
  33. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
  34. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
  35. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
  36. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
  37. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
  38. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
  39. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
  40. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
  41. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
  42. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
  43. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
  44. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
  45. package/examples/output/go.pprof.block.base.pprof.md +86 -0
  46. package/examples/output/go.pprof.block.current.pprof.md +83 -0
  47. package/examples/output/go.pprof.block.diff.pprof.md +42 -0
  48. package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
  49. package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
  50. package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
  51. package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
  52. package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
  53. package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
  54. package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
  55. package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
  56. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
  57. package/examples/output/go.pprof.heap.base.pprof.md +154 -0
  58. package/examples/output/go.pprof.heap.current.pprof.md +146 -0
  59. package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
  60. package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
  61. package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
  62. package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
  63. package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
  64. package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
  65. package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
  66. package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
  67. package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
  68. package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
  69. package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
  70. package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
  71. package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
  72. package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
  73. package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
  74. package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
  75. package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
  76. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
  77. package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
  78. package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
  79. package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
  80. package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
  81. package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
  82. package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
  83. package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
  84. package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
  85. package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
  86. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
  87. package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
  88. package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
  89. package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
  90. package/examples/output/java.jdk.all.base.jfr.md +1024 -0
  91. package/examples/output/java.jdk.all.current.jfr.md +1010 -0
  92. package/examples/output/java.jdk.all.diff.jfr.md +311 -0
  93. package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
  94. package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
  95. package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
  96. package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
  97. package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
  98. package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
  99. package/examples/output/java.jdk.live.base.jfr.md +1029 -0
  100. package/examples/output/java.jdk.live.current.jfr.md +1035 -0
  101. package/examples/output/java.jdk.live.diff.jfr.md +289 -0
  102. package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
  103. package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
  104. package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
  105. package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
  106. package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
  107. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
  108. package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
  109. package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
  110. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
  111. package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
  112. package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
  113. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
  114. package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
  115. package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
  116. package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
  117. package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
  118. package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
  119. package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
  120. package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
  121. package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
  122. package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
  123. package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
  124. package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
  125. package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
  126. package/examples/output/javascript.node.base.cpuprofile.md +136 -0
  127. package/examples/output/javascript.node.base.heapprofile.md +56 -0
  128. package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
  129. package/examples/output/javascript.node.current.cpuprofile.md +119 -0
  130. package/examples/output/javascript.node.current.heapprofile.md +52 -0
  131. package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
  132. package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
  133. package/examples/output/javascript.node.diff.heapprofile.md +34 -0
  134. package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
  135. package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
  136. package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
  137. package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
  138. package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
  139. package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
  140. package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
  141. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
  142. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
  143. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
  144. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
  145. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
  146. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
  147. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
  148. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
  149. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
  150. package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
  151. package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
  152. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
  153. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
  154. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
  155. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
  156. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
  157. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
  158. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
  159. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
  160. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
  161. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
  162. package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
  163. package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
  164. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
  165. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
  166. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
  167. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
  168. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
  169. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
  170. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
  171. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
  172. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
  173. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
  174. package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
  175. package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
  176. package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
  177. package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
  178. package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
  179. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
  180. package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
  181. package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
  182. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
  183. package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
  184. package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
  185. package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
  186. package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
  187. package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
  188. package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
  189. package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
  190. package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
  191. package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
  192. package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
  193. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
  194. package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
  195. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
  196. package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
  197. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
  198. package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
  199. package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
  200. package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
  201. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
  202. package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
  203. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
  204. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
  205. package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
  206. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
  207. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
  208. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
  209. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
  210. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
  211. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
  212. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
  213. package/package.json +7 -3
  214. package/readme.md +115 -27
  215. package/examples/bun.cpuprofile.md +0 -475
  216. package/examples/deno.cpuprofile.md +0 -481
  217. package/examples/jsc-heap-snapshot.base.json.md +0 -507
  218. package/examples/jsc-heap-snapshot.current.json.md +0 -504
  219. package/examples/jsc-heap-snapshot.diff.json.md +0 -119
  220. package/examples/node.base.cpuprofile.md +0 -451
  221. package/examples/node.current.cpuprofile.md +0 -449
  222. package/examples/node.diff.cpuprofile.md +0 -82
  223. package/examples/node.heapprofile.md +0 -281
  224. package/examples/node.heapsnapshot.md +0 -694
  225. package/examples/node.pprof.md +0 -441
  226. package/examples/python.base.collapsed.md +0 -116
  227. package/examples/python.current.collapsed.md +0 -125
  228. package/examples/python.diff.collapsed.md +0 -51
  229. package/examples/rust.base.pprof.md +0 -477
  230. package/examples/rust.current.pprof.md +0 -480
  231. package/examples/rust.diff.pprof.md +0 -117
  232. package/examples/webkit-timeline-recording.json.md +0 -434
@@ -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.
@@ -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.
@@ -11,6 +11,9 @@ Install it as a global tool:
11
11
  dotnet tool install --global dotnet-trace
12
12
  ```
13
13
 
14
+ The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
15
+ install a compatible version with `--version`.
16
+
14
17
  ## CPU profiling
15
18
 
16
19
  Periodically samples the call stack. Useful for finding CPU hot spots.
@@ -1,16 +1,20 @@
1
1
  # Elixir/Erlang
2
2
 
3
3
  Elixir and Erlang profiling uses
4
- [eflambe](https://github.com/Stratus3D/eflambe), a profiler for the BEAM that
5
- wraps the runtime's built-in tracing and writes flame graph output.
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
6
 
7
7
  ## CPU profiling
8
8
 
9
9
  Traces function calls and writes them as collapsed stacks. Useful for finding
10
10
  CPU hot spots.
11
11
 
12
- eflambe's default `brendan_gregg` output format is collapsed stacks. Add
13
- `eflambe` to your dependencies, then profile a specific function.
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.
14
18
 
15
19
  ### Elixir
16
20
 
@@ -1,16 +1,20 @@
1
1
  # Elixir/Erlang
2
2
 
3
3
  Elixir and Erlang profiling uses
4
- [eflambe](https://github.com/Stratus3D/eflambe), a profiler for the BEAM that
5
- wraps the runtime's built-in tracing and writes flame graph output.
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
6
 
7
7
  ## CPU profiling
8
8
 
9
9
  Traces function calls and writes them as collapsed stacks. Useful for finding
10
10
  CPU hot spots.
11
11
 
12
- eflambe's default `brendan_gregg` output format is collapsed stacks. Add
13
- `eflambe` to your dependencies, then profile a specific function.
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.
14
18
 
15
19
  ### Elixir
16
20
 
@@ -11,6 +11,9 @@ Install it as a global tool:
11
11
  dotnet tool install --global dotnet-trace
12
12
  ```
13
13
 
14
+ The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
15
+ install a compatible version with `--version`.
16
+
14
17
  ## CPU profiling
15
18
 
16
19
  Periodically samples the call stack. Useful for finding CPU hot spots.
@@ -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.
@@ -1,32 +1,41 @@
1
1
  # Java/Kotlin
2
2
 
3
- Java and Kotlin profiling uses
3
+ Java and Kotlin profiling works with any JVM language, using either
4
+ [Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) (JFR),
5
+ built into the JDK since JDK 11, or
4
6
  [async-profiler](https://github.com/async-profiler/async-profiler), a low
5
- overhead sampling profiler that works with any JVM language.
7
+ overhead sampling profiler that additionally resolves native frames and works on
8
+ older JDKs.
6
9
 
7
10
  ## CPU profiling
8
11
 
9
- Periodically samples the call stack. Useful for finding CPU hot spots.
12
+ Periodically samples the call stack while on CPU. Useful for finding CPU hot
13
+ spots. Recorded as `jdk.ExecutionSample` events.
10
14
 
11
- ### CLI
15
+ ### Java Flight Recorder
12
16
 
13
17
  ```sh
14
- # Attach to a running process (collapsed format)
15
- asprof -d 30 -f cpu.collapsed -o collapsed <pid>
18
+ java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms -jar app.jar
19
+ jfr summary cpu.jfr
20
+ ```
21
+
22
+ ### async-profiler
16
23
 
17
- # Attach to a running process (pprof format)
18
- asprof -d 30 -f cpu.pprof <pid>
24
+ #### CLI
19
25
 
20
- # Attach to a running process (speedscope format)
21
- asprof -d 30 -f profile.speedscope -o speedscope <pid>
26
+ ```sh
27
+ # Attach to a running JVM (JFR is the default output format)
28
+ asprof -e cpu -d 30 -f cpu.jfr <pid>
22
29
 
23
- # Profile a command directly
24
- asprof -d 30 -f cpu.pprof -- java -jar app.jar
30
+ # Or write collapsed stacks
31
+ asprof -e cpu -d 30 -o collapsed -f cpu.collapsed <pid>
25
32
  ```
26
33
 
27
- ### Programmatic API
34
+ #### Programmatic API
28
35
 
29
- Add `async-profiler` to your dependencies, then:
36
+ Add `async-profiler` to your dependencies, then control it in-process. The
37
+ output format follows the file extension (`.jfr` or `.collapsed`), and `event`
38
+ selects the metric:
30
39
 
31
40
  ```java
32
41
  import one.profiler.AsyncProfiler;
@@ -41,80 +50,121 @@ profiler.execute("stop");
41
50
 
42
51
  ## Wall-clock profiling
43
52
 
44
- Samples wall-clock time rather than CPU time. Useful for I/O-bound or
45
- latency-sensitive code where threads spend time waiting.
46
-
47
- ### CLI
48
-
49
- ```sh
50
- asprof -d 30 -e wall -f profile.pprof <pid>
51
- ```
53
+ Samples wall-clock time rather than CPU time, including time threads spend
54
+ waiting. Useful for I/O-bound or latency-sensitive code.
52
55
 
53
- ### Programmatic API
56
+ ### Java Flight Recorder
54
57
 
55
- ```java
56
- AsyncProfiler profiler = AsyncProfiler.getInstance();
57
- profiler.execute("start,event=wall,file=profile.jfr");
58
+ JFR has no wall-clock sampler, so this metric is async-profiler only. (JFR does
59
+ record specific waiting events, such as `jdk.ThreadPark` and
60
+ `jdk.JavaMonitorWait`, via the lock recipe below.)
58
61
 
59
- // Code to profile...
62
+ ### async-profiler
60
63
 
61
- profiler.execute("stop");
64
+ ```sh
65
+ asprof -e wall -d 30 -f wall.jfr <pid>
62
66
  ```
63
67
 
68
+ Recorded as `profiler.WallClockSample` events. `cpu` and `wall` share the same
69
+ sampling timer, so async-profiler records one or the other within a single
70
+ recording, not both.
71
+
64
72
  ## Memory profiling
65
73
 
66
- Samples heap allocations. Useful for finding allocation hot spots and reducing
67
- GC pressure.
74
+ Samples memory allocations, in allocated bytes. async-profiler offers three
75
+ variants; JFR offers two:
68
76
 
69
- ### CLI
77
+ - **heap allocations**: every heap allocation sampled since profiling started;
78
+ useful for finding allocation hot spots and reducing GC pressure
79
+ - **live heap**: only allocations whose objects are still live at the end;
80
+ useful for finding leaks
81
+ - **native memory**: off-heap `malloc`/`free`; useful for finding native leaks
82
+ (async-profiler only)
83
+
84
+ ### Java Flight Recorder
70
85
 
71
86
  ```sh
72
- # Attach to a running process (pprof format)
73
- asprof -d 30 -e alloc -f mem.pprof <pid>
87
+ # Heap allocation hot spots (jdk.ObjectAllocationSample, JDK 16+)
88
+ java -XX:StartFlightRecording=filename=alloc.jfr,settings=none,+jdk.ObjectAllocationSample#enabled=true,+jdk.ObjectAllocationSample#throttle=150/s -jar app.jar
74
89
 
75
- # Profile a command directly
76
- asprof -d 30 -e alloc -f mem.pprof -- java -jar app.jar
90
+ # Live objects, for leak finding (jdk.OldObjectSample)
91
+ java -XX:StartFlightRecording=filename=live.jfr,settings=none,+jdk.OldObjectSample#enabled=true,+jdk.OldObjectSample#stackTrace=true -jar app.jar
77
92
  ```
78
93
 
79
- ### Programmatic API
94
+ JFR's native memory tracking (`-XX:NativeMemoryTracking`) reports usage by
95
+ category rather than call-stack-attributed allocations, so native allocation
96
+ profiling is async-profiler only.
80
97
 
81
- ```java
82
- AsyncProfiler profiler = AsyncProfiler.getInstance();
83
- profiler.execute("start,event=alloc,file=mem.jfr");
98
+ ### async-profiler
84
99
 
85
- // Code to profile...
100
+ ```sh
101
+ # Heap allocation hot spots (jdk.ObjectAllocationInNewTLAB/OutsideTLAB)
102
+ asprof -e alloc -d 30 -f alloc.jfr <pid>
86
103
 
87
- profiler.execute("stop");
104
+ # Live objects only, for leak finding (profiler.LiveObject)
105
+ asprof -e alloc --live -d 30 -f live.jfr <pid>
106
+
107
+ # Off-heap native memory (profiler.Malloc/Free); --nofree skips free events
108
+ asprof -e nativemem -d 30 -f native.jfr <pid>
88
109
  ```
89
110
 
111
+ `--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
112
+ heap and native variants.
113
+
90
114
  ## Lock profiling
91
115
 
92
- Samples contended monitor locks (`synchronized`, `ReentrantLock`, and other
93
- `java.util.concurrent` locks). Useful for finding lock contention hot spots.
116
+ Samples contended monitor and `java.util.concurrent` locks. Useful for finding
117
+ lock contention hot spots. The sampled values are nanoseconds spent blocked.
118
+ Recorded as `jdk.JavaMonitorEnter` and `jdk.ThreadPark` events.
94
119
 
95
- ### CLI
120
+ ### Java Flight Recorder
96
121
 
97
122
  ```sh
98
- asprof -d 30 -e lock -f lock.pprof <pid>
123
+ java -XX:StartFlightRecording=filename=lock.jfr,settings=none,+jdk.JavaMonitorEnter#enabled=true,+jdk.JavaMonitorEnter#threshold=10ms,+jdk.ThreadPark#enabled=true,+jdk.ThreadPark#threshold=10ms -jar app.jar
99
124
  ```
100
125
 
101
- ### Programmatic API
126
+ ### async-profiler
102
127
 
103
- ```java
104
- AsyncProfiler profiler = AsyncProfiler.getInstance();
105
- profiler.execute("start,event=lock,file=lock.jfr");
128
+ ```sh
129
+ asprof -e lock -d 30 -f lock.jfr <pid>
130
+ ```
106
131
 
107
- // Code to profile...
132
+ Recorded as `profiler.NativeLock` events.
108
133
 
109
- profiler.execute("stop");
134
+ ## Profiling all events
135
+
136
+ ### Java Flight Recorder
137
+
138
+ The `profile` template records execution samples, allocations, locks, GC, and
139
+ many other JVM events at once. JFR rotates the recording into multiple chunks as
140
+ it grows (`-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold).
141
+
142
+ ```sh
143
+ java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
144
+ jfr summary all.jfr
110
145
  ```
111
146
 
112
- ## CLI flags
147
+ ### async-profiler
148
+
149
+ `--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock`
150
+ simultaneously. Add `--nofree` to suppress the high-volume native `free` events,
151
+ which otherwise dominate the recording.
152
+
153
+ ```sh
154
+ asprof --all --nofree -d 30 -f all.jfr <pid>
155
+ ```
156
+
157
+ ## async-profiler flags
158
+
159
+ | Flag | Default | Description |
160
+ | ------------------- | ------- | ------------------------------------------------------------ |
161
+ | `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock`, and others |
162
+ | `-d` / `--duration` | — | Duration in seconds |
163
+ | `-o` / `--output` | `jfr` | Output format (`jfr` or `collapsed`) |
164
+ | `-f` / `--file` | — | Output file path |
165
+ | `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
166
+ | `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
167
+ | `<pid>` | — | Target JVM PID, `jps`, or the application name |
113
168
 
114
- | Flag | Default | Description |
115
- | ------------------- | ------- | -------------------------------------------------------- |
116
- | `-d` / `--duration` | — | Duration in seconds |
117
- | `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock` |
118
- | `-f` / `--file` | — | Output file path |
119
- | `-o` / `--output` | `jfr` | Output format: `collapsed`, `jfr`, `pprof`, `speedscope` |
120
- | `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
169
+ On macOS the default `cpu` event works (it samples CPU time via a timer), but
170
+ hardware events like `cache-misses` require Linux `perf_events`.
@@ -1,7 +1,7 @@
1
1
  # JavaScript
2
2
 
3
- Profiling JavaScript works across Node.js, Deno, Bun, and Chrome via V8 CPU
4
- profiles, V8 heap profiles, and V8 heap snapshots.
3
+ Profile JavaScript across Node.js, Deno, Bun, Chrome, and Safari, capturing CPU
4
+ profiles, heap profiles, and heap snapshots in V8 and JavaScriptCore formats.
5
5
 
6
6
  ## CPU profiling
7
7
 
@@ -54,7 +54,7 @@ writeFileSync(`cpu.cpuprofile`, JSON.stringify(profile))
54
54
  Samples heap allocations by stack trace. Useful for finding allocation hot spots
55
55
  and reducing GC pressure.
56
56
 
57
- `bun --heap-prof` generates a heap _snapshot_ on exit, not a heap _profile_.
57
+ `bun --heap-prof` generates a V8 heap _snapshot_ on exit, not a heap _profile_.
58
58
  Deno has no equivalent.
59
59
 
60
60
  ### CLI
@@ -127,6 +127,9 @@ bun --heap-prof script.ts
127
127
 
128
128
  ### Programmatic API
129
129
 
130
+ `node:v8`'s `writeHeapSnapshot` writes a V8-format snapshot and works in
131
+ Node.js, Deno, and Bun:
132
+
130
133
  ```js
131
134
  import { writeHeapSnapshot } from 'node:v8'
132
135
 
@@ -134,6 +137,20 @@ import { writeHeapSnapshot } from 'node:v8'
134
137
  writeHeapSnapshot(`heap.heapsnapshot`)
135
138
  ```
136
139
 
140
+ Bun also offers
141
+ [`Bun.generateHeapSnapshot()`](https://bun.com/reference/bun/generateHeapSnapshot),
142
+ which emits _both_ heap snapshot formats, selectable by argument:
143
+
144
+ ```js
145
+ import { generateHeapSnapshot } from 'bun'
146
+
147
+ const jsc = generateHeapSnapshot() // Or generateHeapSnapshot(`jsc`)
148
+ await Bun.write(`heap.json`, JSON.stringify(jsc))
149
+
150
+ const v8 = generateHeapSnapshot(`v8`)
151
+ await Bun.write(`heap.heapsnapshot`, v8)
152
+ ```
153
+
137
154
  ## pprof
138
155
 
139
156
  Node.js can also emit [pprof](https://github.com/google/pprof) profiles via the
@@ -172,19 +189,16 @@ await writeFile(`heap.pb.gz`, await encode(await heap.profile()))
172
189
  ## Chrome DevTools
173
190
 
174
191
  Chrome DevTools can profile JavaScript running in the browser or connected to
175
- Node.js, Deno, or Bun via `--inspect`. The panels and workflow are the same in
176
- both cases.
192
+ Node.js or Deno via `--inspect`. The panels and workflow are identical.
177
193
 
178
194
  ### Connecting
179
195
 
180
196
  **In the browser:** open DevTools with ⌥⌘I (macOS) or Ctrl+Shift+I
181
197
  (Windows/Linux).
182
198
 
183
- **Via `--inspect` (Node.js, Deno, Bun):** start the process with the inspector
199
+ **Via `--inspect` (Node.js, Deno):** start the process with the inspector
184
200
  enabled, then open `chrome://inspect` in Chrome and click **Open dedicated
185
- DevTools for Node**. For Bun, open the URL printed to stderr in
186
- [debug.bun.sh](https://debug.bun.sh) — Bun uses the WebKit Inspector Protocol
187
- rather than V8's.
201
+ DevTools for Node**.
188
202
 
189
203
  ```sh
190
204
  # Node.js (default port 9229)
@@ -192,9 +206,6 @@ node --inspect script.js
192
206
 
193
207
  # Deno (default port 9229)
194
208
  deno run --inspect script.ts
195
-
196
- # Bun (auto-assigned port)
197
- bun --inspect script.ts
198
209
  ```
199
210
 
200
211
  #### Flags (all runtimes)
@@ -219,6 +230,17 @@ Stop when done to see allocation hot spots by call stack.
219
230
  Open the **Memory** panel, select **Heap snapshot**, and click **Take
220
231
  snapshot**.
221
232
 
233
+ ## debug.bun.sh
234
+
235
+ Bun's inspector speaks the WebKit Inspector Protocol rather than V8's, so it
236
+ connects through [debug.bun.sh](https://debug.bun.sh) instead of Chrome
237
+ DevTools. Start the process with `--inspect` and open the URL printed to stderr.
238
+
239
+ ```sh
240
+ # Bun (auto-assigned port)
241
+ bun --inspect script.ts
242
+ ```
243
+
222
244
  ## Safari Web Inspector
223
245
 
224
246
  Safari's Web Inspector records a timeline that combines CPU sampling, browser
@@ -12,11 +12,15 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
12
12
  ```julia
13
13
  using Profile, PProf
14
14
 
15
+ # Warm up the JIT so compilation isn't captured as part of the profile.
16
+ my_function()
17
+
15
18
  Profile.clear()
16
19
  @profile my_function()
17
20
 
18
- # Write profile.pb.gz without launching the web UI
19
- pprof(out = "cpu.pb.gz", web = false)
21
+ # `web = false` skips the UI. `from_c = false` drops C/runtime frames, leaving
22
+ # just your Julia code.
23
+ pprof(out = "cpu.pb.gz", web = false, from_c = false)
20
24
  ```
21
25
 
22
26
  ## Memory profiling
@@ -27,6 +31,9 @@ GC pressure.
27
31
  ```julia
28
32
  using Profile, PProf
29
33
 
34
+ # Warm up the JIT so compilation isn't captured as part of the profile.
35
+ my_function()
36
+
30
37
  Profile.Allocs.clear()
31
38
  Profile.Allocs.@profile my_function()
32
39
 
@@ -40,3 +47,8 @@ PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
40
47
  | `out` | `"profile.pb.gz"` | Output file path |
41
48
  | `web` | `true` | Launch the interactive web UI after exporting |
42
49
  | `from_c` | `true` | Include C and Julia runtime frames |
50
+
51
+ ## Tips
52
+
53
+ Run single-threaded (`julia -t 1 --gcthreads=1`). Otherwise idle GC and
54
+ scheduler threads fill the profile with wait frames (`__psynch_cvwait`).