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
@@ -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,31 +1,75 @@
1
1
  # PHP
2
2
 
3
- PHP profiling uses [phpspy](https://github.com/adsr/phpspy), a low overhead
4
- sampling profiler for PHP processes.
3
+ PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
4
+ extension, a low-overhead sampling profiler. Excimer samples from a
5
+ PHP-controlled timer, so you start and stop it from within the program or a
6
+ prepended bootstrap script.
5
7
 
6
8
  ## CPU profiling
7
9
 
8
10
  Periodically samples the call stack. Useful for finding CPU hot spots.
9
11
 
10
- ```sh
11
- # Profile a command (speedscope format)
12
- phpspy -d 30 --output-format=speedscope -f cpu.speedscope -- php script.php
12
+ ```php
13
+ <?php
14
+ $prof = new ExcimerProfiler();
15
+ $prof->setEventType(EXCIMER_CPU);
16
+ $prof->setPeriod(0.001); // seconds
17
+ $prof->start();
18
+
19
+ // Code to profile...
20
+
21
+ $prof->stop();
22
+ file_put_contents('cpu.speedscope.json',
23
+ json_encode($prof->getLog()->getSpeedscopeData()));
24
+ ```
13
25
 
14
- # Attach to a running process (speedscope format)
15
- phpspy -d 30 --output-format=speedscope --pid <pid> -f cpu.speedscope
26
+ ## Wall-clock profiling
16
27
 
17
- # Attach to a running process (callgrind format, for KCachegrind)
18
- phpspy -d 30 --output-format=callgrind --pid <pid> > cpu.callgrind
28
+ Samples wall-clock time rather than CPU time, including time threads spend
29
+ waiting. Useful for I/O-bound or latency-sensitive code.
30
+
31
+ ```php
32
+ <?php
33
+ $prof = new ExcimerProfiler();
34
+ $prof->setEventType(EXCIMER_REAL);
35
+ $prof->setPeriod(0.001);
36
+ $prof->start();
37
+
38
+ // Code to profile...
39
+
40
+ $prof->stop();
41
+ file_put_contents('wall.speedscope.json',
42
+ json_encode($prof->getLog()->getSpeedscopeData()));
19
43
  ```
20
44
 
21
- ### Flags
22
-
23
- | Flag | Default | Description |
24
- | -------------------- | ------- | ------------------------------------------------------------------ |
25
- | `--pid` / `-p` | — | PID of the PHP process to profile |
26
- | `--duration` / `-d` | — | Duration in seconds; profiles indefinitely when not set |
27
- | `--sleep-us` / `-s` | `10000` | Sampling interval in microseconds |
28
- | `--num-samples` | — | Maximum number of samples to collect |
29
- | `--max-depth` / `-l` | `64` | Maximum stack frames per sample |
30
- | `--output-format` | `raw` | Output format: `raw`, `callgrind`, `speedscope`, `valgrind`, `rep` |
31
- | `--output-file` | stdout | Write output to this file instead of stdout |
45
+ ## Profiling an existing program
46
+
47
+ To profile a program you don't want to edit, point `auto_prepend_file` at a
48
+ bootstrap script that starts the profiler and writes the result on shutdown:
49
+
50
+ ```php
51
+ <?php // prepend.php
52
+ $prof = new ExcimerProfiler();
53
+ $prof->setEventType(EXCIMER_REAL);
54
+ $prof->setPeriod(0.001);
55
+ $prof->start();
56
+ register_shutdown_function(function () use ($prof) {
57
+ $prof->stop();
58
+ file_put_contents('profile.speedscope.json',
59
+ json_encode($prof->getLog()->getSpeedscopeData()));
60
+ });
61
+ ```
62
+
63
+ ```sh
64
+ php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optimize
65
+ ```
66
+
67
+ ## API
68
+
69
+ | Method | Description |
70
+ | ------------------------------- | ----------------------------------------------------- |
71
+ | `setEventType($type)` | `EXCIMER_REAL` (wall clock) or `EXCIMER_CPU` |
72
+ | `setPeriod($seconds)` | Sampling interval in seconds (e.g. `0.001` = 1000 Hz) |
73
+ | `setMaxDepth($depth)` | Maximum stack frames per sample |
74
+ | `start()` / `stop()` | Begin and end profiling |
75
+ | `getLog()->getSpeedscopeData()` | The collected profile as Speedscope-format data |
@@ -1,72 +1,33 @@
1
1
  # Python
2
2
 
3
- Python profiling uses [py-spy](https://github.com/benford/py-spy), a sampling
4
- profiler that attaches to a running process or wraps a script, and
5
- [memray](https://github.com/bloomberg/memray) for memory profiling.
3
+ Python profiling uses [py-spy](https://github.com/benfred/py-spy), a sampling
4
+ profiler that attaches to a running process or wraps a script.
6
5
 
7
6
  ## CPU profiling
8
7
 
9
8
  Periodically samples the call stack. Useful for finding CPU hot spots.
10
9
 
11
10
  ```sh
12
- # Collapsed format (python 3.15+)
13
- python -m profiling.sampling run --collapsed -o cpu.collapsed script.py
14
-
15
11
  # Collapsed format (wrap a script)
16
12
  py-spy record -f raw -o cpu.collapsed -- python script.py
17
13
 
18
- # Collapsed format (attach to a running process)
19
- py-spy record -f raw -o cpu.collapsed --pid <pid>
20
-
21
- # pprof format
22
- py-spy record -f pprof -o cpu.pprof -- python script.py
14
+ # Speedscope format (wrap a script)
15
+ py-spy record -f speedscope -o cpu.speedscope.json -- python script.py
23
16
 
24
- # Speedscope format
25
- py-spy record -f speedscope -o profile.speedscope -- python script.py
17
+ # Attach to a running process
18
+ py-spy record -f raw -o cpu.collapsed --pid <pid>
26
19
 
27
20
  # Include native extensions written in Cython or C
28
- py-spy record -f pprof -o cpu.pprof --native -- python script.py
21
+ py-spy record -f raw -o cpu.collapsed --native -- python script.py
29
22
  ```
30
23
 
31
24
  ## Wall-clock profiling
32
25
 
33
- Samples wall-clock time rather than CPU time. Useful for I/O-bound code where
34
- threads spend time sleeping or waiting.
35
-
36
- ```sh
37
- # Wrap a script
38
- py-spy record -f pprof -o profile.pprof --idle -- python script.py
39
-
40
- # Attach to a running process
41
- py-spy record -f pprof -o profile.pprof --idle --pid <pid>
42
- ```
43
-
44
- ## Memory profiling
45
-
46
- Tracks heap allocations. Useful for finding allocation hot spots and memory
47
- leaks.
48
-
49
- ### CLI
26
+ Samples wall-clock time rather than CPU time, including time threads spend
27
+ waiting. Useful for I/O-bound or latency-sensitive code.
50
28
 
51
29
  ```sh
52
- # Record a memory profile (wrap a script)
53
- memray run -o mem.bin script.py
54
-
55
- # Attach to a running process
56
- memray attach -o mem.bin <pid>
57
-
58
- # Convert to pprof format
59
- memray pprof mem.bin
60
- ```
61
-
62
- ### Programmatic API
63
-
64
- ```python
65
- import memray
66
-
67
- with memray.Tracker("mem.bin"):
68
- # Code to profile...
69
- pass
30
+ py-spy record -f raw -o wall.collapsed --idle -- python script.py
70
31
  ```
71
32
 
72
33
  ## Call stack dump
@@ -74,8 +35,6 @@ with memray.Tracker("mem.bin"):
74
35
  Captures the current call stacks of all threads in a running process. Useful for
75
36
  diagnosing hangs, deadlocks, or unexpected blocking.
76
37
 
77
- ### CLI
78
-
79
38
  ```sh
80
39
  # Dump call stacks of a running process (text output)
81
40
  py-spy dump --pid <pid>
@@ -84,21 +43,11 @@ py-spy dump --pid <pid>
84
43
  py-spy dump --pid <pid> --locals
85
44
  ```
86
45
 
87
- ### Programmatic API
88
-
89
- ```python
90
- import faulthandler
91
-
92
- faulthandler.dump_traceback() # all threads to stderr
93
- ```
94
-
95
46
  ## CLI flags
96
47
 
97
- ### `py-spy`
98
-
99
48
  | Flag | Default | Description |
100
49
  | ------------------- | ------------ | ---------------------------------------------------------- |
101
- | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`, `pprof` |
50
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope` |
102
51
  | `-o` / `--output` | — | Output file path |
103
52
  | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
104
53
  | `-r` / `--rate` | `100` | Sampling rate in Hz |
@@ -106,13 +55,3 @@ faulthandler.dump_traceback() # all threads to stderr
106
55
  | `--native` | off | Profile native extensions written in Cython or C |
107
56
  | `--nonblocking` | off | Don't pause the process to collect samples (less accurate) |
108
57
  | `--subprocesses` | off | Also profile subprocesses of the target |
109
-
110
- ### `memray`
111
-
112
- | Flag | Default | Description |
113
- | --------------------------- | ------- | --------------------------------------------------- |
114
- | `-o` / `--output` | — | Output file path |
115
- | `--native` | off | Also capture native (C extension) stack frames |
116
- | `--follow-fork` | off | Also profile child processes after `fork()` |
117
- | `--aggregate` | off | Aggregate allocations to reduce output file size |
118
- | `--trace-python-allocators` | off | Trace Python allocator calls for finer-grained data |
@@ -11,10 +11,16 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
11
11
 
12
12
  ```sh
13
13
  # Profile a command (speedscope format)
14
- rbspy record --format speedscope -o profile.speedscope -- ruby script.rb
14
+ rbspy record --format speedscope -o cpu.speedscope.json -- ruby script.rb
15
+
16
+ # Collapsed stacks
17
+ rbspy record --format collapsed -o cpu.collapsed -- ruby script.rb
18
+
19
+ # pprof
20
+ rbspy record --format pprof -o cpu.pprof -- ruby script.rb
15
21
 
16
22
  # Attach to a running process
17
- rbspy record --format speedscope -o profile.speedscope --pid <pid>
23
+ rbspy record --format speedscope -o cpu.speedscope.json --pid <pid>
18
24
 
19
25
  # Profile for a fixed duration
20
26
  rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
@@ -23,21 +29,6 @@ rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
23
29
  rbspy record --format speedscope -o profile.speedscope --subprocesses --pid <pid>
24
30
  ```
25
31
 
26
- ## Memory profiling
27
-
28
- Records RSS memory alongside call stack samples. Useful for correlating memory
29
- growth with specific code paths.
30
-
31
- ### CLI
32
-
33
- ```sh
34
- # Record CPU and memory together
35
- rbspy record --memory --format speedscope -o profile.speedscope --pid <pid>
36
-
37
- # Profile a command with memory tracking
38
- rbspy record --memory --format speedscope -o profile.speedscope -- ruby script.rb
39
- ```
40
-
41
32
  ## Snapshot
42
33
 
43
34
  Captures a single stack trace from a running process. Useful for quickly
@@ -55,13 +46,12 @@ rbspy snapshot --nonblocking --pid <pid>
55
46
 
56
47
  ## CLI flags
57
48
 
58
- | Flag | Default | Description |
59
- | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
60
- | `-p` / `--pid` | — | PID of a running process to attach to |
61
- | `-d` / `--duration` | — | Duration in seconds; records until Ctrl-C if omitted |
62
- | `-r` / `--rate` | `100` | Samples per second |
63
- | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `speedscope`, `callgrind`, `summary`, `summary_by_line`, `raw_call_stack` |
64
- | `-o` / `--file` | — | Output file path |
65
- | `-m` / `--memory` | — | Also record RSS memory usage alongside stack samples |
66
- | `--subprocesses` | — | Also profile child processes |
67
- | `--nonblocking` | — | Don't pause the process while reading its stack (lower overhead, may miss frames) |
49
+ | Flag | Default | Description |
50
+ | ------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
51
+ | `-p` / `--pid` | — | PID of a running process to attach to |
52
+ | `-d` / `--duration` | — | Duration in seconds; records until Ctrl-C if omitted |
53
+ | `-r` / `--rate` | `100` | Samples per second |
54
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `collapsed`, `pprof`, `speedscope`, `callgrind`, `summary`, `summary_by_line` |
55
+ | `-o` / `--file` | — | Output file path |
56
+ | `--subprocesses` | — | Also profile child processes |
57
+ | `--nonblocking` | — | Don't pause the process while reading its stack (lower overhead, may miss frames) |
@@ -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