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
@@ -1,29 +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 (pprof format)
15
- asprof -d 30 -f cpu.pprof <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 (speedscope format)
18
- asprof -d 30 -f profile.speedscope -o speedscope <pid>
24
+ #### CLI
19
25
 
20
- # Profile a command directly
21
- asprof -d 30 -f cpu.pprof -- java -jar app.jar
26
+ ```sh
27
+ # Attach to a running JVM (JFR is the default output format)
28
+ asprof -e cpu -d 30 -f cpu.jfr <pid>
29
+
30
+ # Or write collapsed stacks
31
+ asprof -e cpu -d 30 -o collapsed -f cpu.collapsed <pid>
22
32
  ```
23
33
 
24
- ### Programmatic API
34
+ #### Programmatic API
25
35
 
26
- 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:
27
39
 
28
40
  ```java
29
41
  import one.profiler.AsyncProfiler;
@@ -38,80 +50,121 @@ profiler.execute("stop");
38
50
 
39
51
  ## Wall-clock profiling
40
52
 
41
- Samples wall-clock time rather than CPU time. Useful for I/O-bound or
42
- latency-sensitive code where threads spend time waiting.
43
-
44
- ### CLI
53
+ Samples wall-clock time rather than CPU time, including time threads spend
54
+ waiting. Useful for I/O-bound or latency-sensitive code.
45
55
 
46
- ```sh
47
- asprof -d 30 -e wall -f profile.pprof <pid>
48
- ```
56
+ ### Java Flight Recorder
49
57
 
50
- ### Programmatic API
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.)
51
61
 
52
- ```java
53
- AsyncProfiler profiler = AsyncProfiler.getInstance();
54
- profiler.execute("start,event=wall,file=profile.jfr");
62
+ ### async-profiler
55
63
 
56
- // Code to profile...
57
-
58
- profiler.execute("stop");
64
+ ```sh
65
+ asprof -e wall -d 30 -f wall.jfr <pid>
59
66
  ```
60
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
+
61
72
  ## Memory profiling
62
73
 
63
- Samples heap allocations. Useful for finding allocation hot spots and reducing
64
- GC pressure.
74
+ Samples memory allocations, in allocated bytes. async-profiler offers three
75
+ variants; JFR offers two:
76
+
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)
65
83
 
66
- ### CLI
84
+ ### Java Flight Recorder
67
85
 
68
86
  ```sh
69
- # Attach to a running process (pprof format)
70
- 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
71
89
 
72
- # Profile a command directly
73
- 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
74
92
  ```
75
93
 
76
- ### 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.
77
97
 
78
- ```java
79
- AsyncProfiler profiler = AsyncProfiler.getInstance();
80
- profiler.execute("start,event=alloc,file=mem.jfr");
98
+ ### async-profiler
81
99
 
82
- // Code to profile...
100
+ ```sh
101
+ # Heap allocation hot spots (jdk.ObjectAllocationInNewTLAB/OutsideTLAB)
102
+ asprof -e alloc -d 30 -f alloc.jfr <pid>
83
103
 
84
- 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>
85
109
  ```
86
110
 
111
+ `--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
112
+ heap and native variants.
113
+
87
114
  ## Lock profiling
88
115
 
89
- Samples contended monitor locks (`synchronized`, `ReentrantLock`, and other
90
- `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.
91
119
 
92
- ### CLI
120
+ ### Java Flight Recorder
93
121
 
94
122
  ```sh
95
- 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
96
124
  ```
97
125
 
98
- ### Programmatic API
126
+ ### async-profiler
99
127
 
100
- ```java
101
- AsyncProfiler profiler = AsyncProfiler.getInstance();
102
- profiler.execute("start,event=lock,file=lock.jfr");
128
+ ```sh
129
+ asprof -e lock -d 30 -f lock.jfr <pid>
130
+ ```
103
131
 
104
- // Code to profile...
132
+ Recorded as `profiler.NativeLock` events.
105
133
 
106
- 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
107
145
  ```
108
146
 
109
- ## 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 |
110
168
 
111
- | Flag | Default | Description |
112
- | ------------------- | ------- | ------------------------------------------------ |
113
- | `-d` / `--duration` | — | Duration in seconds |
114
- | `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock` |
115
- | `-f` / `--file` | — | Output file path |
116
- | `-o` / `--output` | `jfr` | Output format: `jfr`, `pprof`, `speedscope` |
117
- | `-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,22 +137,68 @@ 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
+
154
+ ## pprof
155
+
156
+ Node.js can also emit [pprof](https://github.com/google/pprof) profiles via the
157
+ [`@datadog/pprof`](https://www.npmjs.com/package/@datadog/pprof) package, which
158
+ profiles a section of code rather than the whole process.
159
+
160
+ ### CPU profiling
161
+
162
+ Samples wall-clock time across all threads. Useful for finding CPU hot spots and
163
+ time spent waiting.
164
+
165
+ ```js
166
+ import { writeFile } from 'node:fs/promises'
167
+ import { encode, time } from '@datadog/pprof'
168
+
169
+ const profile = await time.profile({ durationMillis: 10_000 })
170
+ await writeFile(`cpu.pb.gz`, await encode(profile))
171
+ ```
172
+
173
+ ### Memory profiling
174
+
175
+ Samples heap allocations by stack trace. Useful for finding allocation hot spots
176
+ and reducing GC pressure.
177
+
178
+ ```js
179
+ import { writeFile } from 'node:fs/promises'
180
+ import { encode, heap } from '@datadog/pprof'
181
+
182
+ heap.start(512 * 1024, 64) // Sampling interval in bytes, max stack depth
183
+
184
+ // Code to profile...
185
+
186
+ await writeFile(`heap.pb.gz`, await encode(await heap.profile()))
187
+ ```
188
+
137
189
  ## Chrome DevTools
138
190
 
139
191
  Chrome DevTools can profile JavaScript running in the browser or connected to
140
- Node.js, Deno, or Bun via `--inspect`. The panels and workflow are the same in
141
- both cases.
192
+ Node.js or Deno via `--inspect`. The panels and workflow are identical.
142
193
 
143
194
  ### Connecting
144
195
 
145
196
  **In the browser:** open DevTools with ⌥⌘I (macOS) or Ctrl+Shift+I
146
197
  (Windows/Linux).
147
198
 
148
- **Via `--inspect` (Node.js, Deno, Bun):** start the process with the inspector
199
+ **Via `--inspect` (Node.js, Deno):** start the process with the inspector
149
200
  enabled, then open `chrome://inspect` in Chrome and click **Open dedicated
150
- DevTools for Node**. For Bun, open the URL printed to stderr in
151
- [debug.bun.sh](https://debug.bun.sh) — Bun uses the WebKit Inspector Protocol
152
- rather than V8's.
201
+ DevTools for Node**.
153
202
 
154
203
  ```sh
155
204
  # Node.js (default port 9229)
@@ -157,9 +206,6 @@ node --inspect script.js
157
206
 
158
207
  # Deno (default port 9229)
159
208
  deno run --inspect script.ts
160
-
161
- # Bun (auto-assigned port)
162
- bun --inspect script.ts
163
209
  ```
164
210
 
165
211
  #### Flags (all runtimes)
@@ -184,6 +230,17 @@ Stop when done to see allocation hot spots by call stack.
184
230
  Open the **Memory** panel, select **Heap snapshot**, and click **Take
185
231
  snapshot**.
186
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
+
187
244
  ## Safari Web Inspector
188
245
 
189
246
  Safari's Web Inspector records a timeline that combines CPU sampling, browser
@@ -0,0 +1,54 @@
1
+ # Julia
2
+
3
+ Julia profiling uses [PProf.jl](https://github.com/JuliaPerf/PProf.jl), which
4
+ exports profiles collected by Julia's built-in
5
+ [`Profile`](https://docs.julialang.org/en/v1/manual/profile/) standard library
6
+ to the pprof format.
7
+
8
+ ## CPU profiling
9
+
10
+ Periodically samples the call stack. Useful for finding CPU hot spots.
11
+
12
+ ```julia
13
+ using Profile, PProf
14
+
15
+ # Warm up the JIT so compilation isn't captured as part of the profile.
16
+ my_function()
17
+
18
+ Profile.clear()
19
+ @profile my_function()
20
+
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)
24
+ ```
25
+
26
+ ## Memory profiling
27
+
28
+ Samples heap allocations. Useful for finding allocation hot spots and reducing
29
+ GC pressure.
30
+
31
+ ```julia
32
+ using Profile, PProf
33
+
34
+ # Warm up the JIT so compilation isn't captured as part of the profile.
35
+ my_function()
36
+
37
+ Profile.Allocs.clear()
38
+ Profile.Allocs.@profile my_function()
39
+
40
+ PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
41
+ ```
42
+
43
+ ## `pprof` options
44
+
45
+ | Option | Default | Description |
46
+ | -------- | ----------------- | --------------------------------------------- |
47
+ | `out` | `"profile.pb.gz"` | Output file path |
48
+ | `web` | `true` | Launch the interactive web UI after exporting |
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`).
@@ -0,0 +1,170 @@
1
+ # Java/Kotlin
2
+
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
6
+ [async-profiler](https://github.com/async-profiler/async-profiler), a low
7
+ overhead sampling profiler that additionally resolves native frames and works on
8
+ older JDKs.
9
+
10
+ ## CPU profiling
11
+
12
+ Periodically samples the call stack while on CPU. Useful for finding CPU hot
13
+ spots. Recorded as `jdk.ExecutionSample` events.
14
+
15
+ ### Java Flight Recorder
16
+
17
+ ```sh
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
23
+
24
+ #### CLI
25
+
26
+ ```sh
27
+ # Attach to a running JVM (JFR is the default output format)
28
+ asprof -e cpu -d 30 -f cpu.jfr <pid>
29
+
30
+ # Or write collapsed stacks
31
+ asprof -e cpu -d 30 -o collapsed -f cpu.collapsed <pid>
32
+ ```
33
+
34
+ #### Programmatic API
35
+
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:
39
+
40
+ ```java
41
+ import one.profiler.AsyncProfiler;
42
+
43
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
44
+ profiler.execute("start,event=cpu,file=cpu.jfr");
45
+
46
+ // Code to profile...
47
+
48
+ profiler.execute("stop");
49
+ ```
50
+
51
+ ## Wall-clock profiling
52
+
53
+ Samples wall-clock time rather than CPU time, including time threads spend
54
+ waiting. Useful for I/O-bound or latency-sensitive code.
55
+
56
+ ### Java Flight Recorder
57
+
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.)
61
+
62
+ ### async-profiler
63
+
64
+ ```sh
65
+ asprof -e wall -d 30 -f wall.jfr <pid>
66
+ ```
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
+
72
+ ## Memory profiling
73
+
74
+ Samples memory allocations, in allocated bytes. async-profiler offers three
75
+ variants; JFR offers two:
76
+
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
85
+
86
+ ```sh
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
89
+
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
92
+ ```
93
+
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.
97
+
98
+ ### async-profiler
99
+
100
+ ```sh
101
+ # Heap allocation hot spots (jdk.ObjectAllocationInNewTLAB/OutsideTLAB)
102
+ asprof -e alloc -d 30 -f alloc.jfr <pid>
103
+
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>
109
+ ```
110
+
111
+ `--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
112
+ heap and native variants.
113
+
114
+ ## Lock profiling
115
+
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.
119
+
120
+ ### Java Flight Recorder
121
+
122
+ ```sh
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
124
+ ```
125
+
126
+ ### async-profiler
127
+
128
+ ```sh
129
+ asprof -e lock -d 30 -f lock.jfr <pid>
130
+ ```
131
+
132
+ Recorded as `profiler.NativeLock` events.
133
+
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
145
+ ```
146
+
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 |
168
+
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 |