profiler-md 0.4.0 → 0.6.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 (247) hide show
  1. package/dist/cli/index.mjs +5512 -2297
  2. package/dist/index.d.mts +974 -62
  3. package/dist/index.js +2 -2
  4. package/docs/formats/jfr.md +16 -0
  5. package/docs/formats/jsc-heap-snapshot.md +3 -3
  6. package/docs/formats/pprof.md +8 -6
  7. package/docs/formats/speedscope.md +5 -4
  8. package/docs/formats/systing.md +25 -0
  9. package/docs/formats/v8-heap-snapshot.md +2 -2
  10. package/docs/languages/c.md +66 -9
  11. package/docs/languages/csharp.md +4 -3
  12. package/docs/languages/elixir.md +10 -7
  13. package/docs/languages/go.md +17 -12
  14. package/docs/languages/java.md +110 -60
  15. package/docs/languages/javascript.md +41 -19
  16. package/docs/languages/julia.md +103 -12
  17. package/docs/languages/php.md +63 -20
  18. package/docs/languages/python.md +35 -81
  19. package/docs/languages/ruby.md +20 -32
  20. package/docs/languages/rust.md +37 -8
  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/c.systing.cpu.base.systing.md +824 -0
  28. package/examples/output/c.systing.cpu.current.systing.md +825 -0
  29. package/examples/output/c.systing.cpu.diff.systing.md +238 -0
  30. package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
  31. package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
  32. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
  33. package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
  34. package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
  35. package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
  36. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
  37. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
  38. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
  39. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
  40. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
  41. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
  42. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
  43. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
  44. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
  45. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
  46. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
  47. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
  48. package/examples/output/go.pprof.block.base.pprof.md +86 -0
  49. package/examples/output/go.pprof.block.current.pprof.md +83 -0
  50. package/examples/output/go.pprof.block.diff.pprof.md +42 -0
  51. package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
  52. package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
  53. package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
  54. package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
  55. package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
  56. package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
  57. package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
  58. package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
  59. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
  60. package/examples/output/go.pprof.heap.base.pprof.md +154 -0
  61. package/examples/output/go.pprof.heap.current.pprof.md +146 -0
  62. package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
  63. package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
  64. package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
  65. package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
  66. package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
  67. package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
  68. package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
  69. package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
  70. package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
  71. package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
  72. package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
  73. package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
  74. package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
  75. package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
  76. package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
  77. package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
  78. package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
  79. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
  80. package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
  81. package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
  82. package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
  83. package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
  84. package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
  85. package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
  86. package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
  87. package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
  88. package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
  89. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
  90. package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
  91. package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
  92. package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
  93. package/examples/output/java.jdk.all.base.jfr.md +1024 -0
  94. package/examples/output/java.jdk.all.current.jfr.md +1010 -0
  95. package/examples/output/java.jdk.all.diff.jfr.md +311 -0
  96. package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
  97. package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
  98. package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
  99. package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
  100. package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
  101. package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
  102. package/examples/output/java.jdk.live.base.jfr.md +1029 -0
  103. package/examples/output/java.jdk.live.current.jfr.md +1035 -0
  104. package/examples/output/java.jdk.live.diff.jfr.md +289 -0
  105. package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
  106. package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
  107. package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
  108. package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
  109. package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
  110. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
  111. package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
  112. package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
  113. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
  114. package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
  115. package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
  116. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
  117. package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
  118. package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
  119. package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
  120. package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
  121. package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
  122. package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
  123. package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
  124. package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
  125. package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
  126. package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
  127. package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
  128. package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
  129. package/examples/output/javascript.node.base.cpuprofile.md +136 -0
  130. package/examples/output/javascript.node.base.heapprofile.md +56 -0
  131. package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
  132. package/examples/output/javascript.node.current.cpuprofile.md +119 -0
  133. package/examples/output/javascript.node.current.heapprofile.md +52 -0
  134. package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
  135. package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
  136. package/examples/output/javascript.node.diff.heapprofile.md +34 -0
  137. package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
  138. package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
  139. package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
  140. package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
  141. package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
  142. package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
  143. package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
  144. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
  145. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
  146. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
  147. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
  148. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
  149. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
  150. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
  151. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
  152. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
  153. package/examples/output/julia.pprof-jl.wall.base.pprof.md +181 -0
  154. package/examples/output/julia.pprof-jl.wall.current.pprof.md +193 -0
  155. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +64 -0
  156. package/examples/output/julia.profile.base.heapsnapshot.md +590 -0
  157. package/examples/output/julia.profile.current.heapsnapshot.md +590 -0
  158. package/examples/output/julia.profile.diff.heapsnapshot.md +288 -0
  159. package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
  160. package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
  161. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
  162. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
  163. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
  164. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
  165. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
  166. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
  167. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
  168. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
  169. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
  170. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
  171. package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
  172. package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
  173. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
  174. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
  175. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
  176. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
  177. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
  178. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
  179. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
  180. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
  181. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
  182. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
  183. package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
  184. package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
  185. package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
  186. package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
  187. package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
  188. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
  189. package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
  190. package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
  191. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
  192. package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
  193. package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
  194. package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
  195. package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
  196. package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
  197. package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
  198. package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
  199. package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
  200. package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
  201. package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
  202. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
  203. package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
  204. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
  205. package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
  206. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
  207. package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
  208. package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
  209. package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
  210. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
  211. package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
  212. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
  213. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
  214. package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
  215. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
  216. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
  217. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
  218. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
  219. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
  220. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
  221. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
  222. package/package.json +17 -12
  223. package/readme.md +158 -48
  224. package/skills/profile-optimize/SKILL.md +160 -0
  225. package/docs/languages/cpp.md +0 -136
  226. package/docs/languages/erlang.md +0 -42
  227. package/docs/languages/fsharp.md +0 -49
  228. package/docs/languages/kotlin.md +0 -120
  229. package/docs/languages/typescript.md +0 -254
  230. package/examples/bun.cpuprofile.md +0 -475
  231. package/examples/deno.cpuprofile.md +0 -481
  232. package/examples/jsc-heap-snapshot.base.json.md +0 -507
  233. package/examples/jsc-heap-snapshot.current.json.md +0 -504
  234. package/examples/jsc-heap-snapshot.diff.json.md +0 -119
  235. package/examples/node.base.cpuprofile.md +0 -451
  236. package/examples/node.current.cpuprofile.md +0 -449
  237. package/examples/node.diff.cpuprofile.md +0 -82
  238. package/examples/node.heapprofile.md +0 -281
  239. package/examples/node.heapsnapshot.md +0 -694
  240. package/examples/node.pprof.md +0 -441
  241. package/examples/python.base.collapsed.md +0 -116
  242. package/examples/python.current.collapsed.md +0 -125
  243. package/examples/python.diff.collapsed.md +0 -51
  244. package/examples/rust.base.pprof.md +0 -477
  245. package/examples/rust.current.pprof.md +0 -480
  246. package/examples/rust.diff.pprof.md +0 -117
  247. 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 a single metric per profile and multiple profiles per file.
15
+
16
+ Files use the `.jfr` extension.
@@ -2,12 +2,12 @@
2
2
 
3
3
  The
4
4
  [JSC heap snapshot](https://webkit.org/blog/6425/memory-debugging-with-web-inspector)
5
- is a JSON format produced by JavaScriptCore, the engine powering Safari and
5
+ is a JSON format produced by JavaScriptCore, the JavaScript engine of Safari and
6
6
  WebKit, that captures the full live object graph at a point in time.
7
7
 
8
8
  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")`).
@@ -1,12 +1,14 @@
1
1
  # pprof
2
2
 
3
3
  [pprof](https://github.com/google/pprof) is a binary
4
- ([protobuf](https://github.com/protocolbuffers/protobuf)) sampled-based
5
- profiling format originally from Google. It is the de facto standard
6
- cross-language profiling format.
4
+ ([protobuf](https://github.com/protocolbuffers/protobuf)) sample-based profiling
5
+ format originally from Google. It is the de facto standard cross-language
6
+ profiling format.
7
7
 
8
- It supports arbitrary metric units, multiple metrics in a single profile, and a
9
- single profile per file. Locations support inlined call frames, meaning a single
10
- instruction address can correspond to multiple logical stack frames.
8
+ Locations support inlined call frames, meaning a single instruction address can
9
+ correspond to multiple logical stack frames.
10
+
11
+ It supports arbitrary metric units, multiple metrics per profile, and a single
12
+ profile per file.
11
13
 
12
14
  Files are commonly gzip-compressed (extension `.pb.gz`).
@@ -1,11 +1,12 @@
1
1
  # Speedscope
2
2
 
3
3
  Speedscope is a JSON profiling format used by
4
- [speedscope.app](https://www.speedscope.app), a flame graph visualizer. Each
5
- profile within a file has a type: `sampled` (call stacks at points in time) or
6
- `evented` (frame open/close timestamps).
4
+ [speedscope.app](https://www.speedscope.app), a flame graph visualizer.
5
+
6
+ Each profile within a file has a type: `sampled` (call stacks at points in time)
7
+ or `evented` (frame open/close timestamps).
7
8
 
8
9
  It supports arbitrary metric units, a single metric per profile, and multiple
9
- profiles in a single file.
10
+ profiles per file.
10
11
 
11
12
  Files use the `.speedscope.json` extension.
@@ -0,0 +1,25 @@
1
+ # systing profile export
2
+
3
+ The line-oriented profile export written by
4
+ [systing](https://github.com/josefbacik/systing), a Linux eBPF system profiler:
5
+ a JSON header line describing the recording (sampling event and period,
6
+ event-type legend, system info), then one JSON array per record: interned
7
+ frames, interned leaf-first stacks, and per-thread sample counts. systing's
8
+ [`docs/PROFILE_EXPORT_FORMAT.md`](https://github.com/josefbacik/systing/blob/main/docs/PROFILE_EXPORT_FORMAT.md)
9
+ specifies the format.
10
+
11
+ A recording samples on-CPU execution and takes a stack each time a thread
12
+ sleeps, so it converts to up to three profiles: CPU (measured in time for
13
+ `cpu-clock` sampling, cycles for `cpu-cycles`), uninterruptible sleep, and
14
+ interruptible sleep (both measured in sleep occurrences). Stacks mix kernel,
15
+ native user, and Python frames; systing's frame markers (`[kernel]`,
16
+ `[gvisor:*]`, `[jit:*]` label modules) determine categorization. Sleep stacks
17
+ are taken at the context switch, so they always end in the kernel's scheduler
18
+ internals: self costs accumulate on scheduler frames, and the total costs show
19
+ which callers slept.
20
+
21
+ Produce it with `systing --output profile.systing -- <command>`, or from an
22
+ existing trace database with
23
+ `systing-util convert trace.duckdb --output profile.systing`.
24
+
25
+ Files use the `.systing` extension, optionally gzipped as `.systing.gz`.
@@ -1,7 +1,7 @@
1
1
  # V8 heap snapshot
2
2
 
3
- The V8 heap snapshot is a JSON format that captures the full live object graph
4
- at a point in time.
3
+ The V8 heap snapshot is a JSON format produced by the V8 JavaScript engine's
4
+ heap profiler that captures the full live object graph at a point in time.
5
5
 
6
6
  Unlike heap profiles, which sample allocations, snapshots show what objects
7
7
  currently exist in memory. This is useful for diagnosing memory leaks rather
@@ -1,6 +1,7 @@
1
1
  # C/C++
2
2
 
3
- C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools).
3
+ C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools),
4
+ or [systing](https://github.com/josefbacik/systing).
4
5
 
5
6
  ## CPU profiling
6
7
 
@@ -9,8 +10,8 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
9
10
  Link with `-lprofiler`:
10
11
 
11
12
  ```sh
12
- gcc -O2 -lprofiler -o program program.c # C
13
- g++ -O2 -lprofiler -o program program.cpp # C++
13
+ gcc -O2 -Wl,--no-as-needed -lprofiler -o program program.c # C
14
+ g++ -O2 -Wl,--no-as-needed -lprofiler -o program program.cpp # C++
14
15
  ```
15
16
 
16
17
  ### CLI
@@ -53,8 +54,8 @@ finding memory leaks and allocation hot spots.
53
54
  Link with `-ltcmalloc`:
54
55
 
55
56
  ```sh
56
- gcc -O2 -ltcmalloc -o program program.c # C
57
- g++ -O2 -ltcmalloc -o program program.cpp # C++
57
+ gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
58
+ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
58
59
  ```
59
60
 
60
61
  ### CLI
@@ -95,13 +96,13 @@ HeapProfilerStop();
95
96
  ## Heap checking
96
97
 
97
98
  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.
99
+ leaks. Useful for confirming a code path frees everything it allocates.
99
100
 
100
101
  Link with `-ltcmalloc`:
101
102
 
102
103
  ```sh
103
- gcc -O2 -ltcmalloc -o program program.c # C
104
- g++ -O2 -ltcmalloc -o program program.cpp # C++
104
+ gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
105
+ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
105
106
  ```
106
107
 
107
108
  ### CLI
@@ -132,5 +133,61 @@ HeapLeakChecker checker("my_check");
132
133
 
133
134
  // Code to check...
134
135
 
135
- if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
136
+ if (!checker.NoLeaks()) abort(); // fails if any net allocation leaked
136
137
  ```
138
+
139
+ ## System profiling
140
+
141
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler that
142
+ samples on-CPU stacks and records a stack each time a thread sleeps, across user
143
+ and kernel code. It needs root (BPF) and a kernel with BTF
144
+ (`/sys/kernel/btf/vmlinux`).
145
+
146
+ ```sh
147
+ # Record a command (and its children) for 30 seconds
148
+ sudo systing --duration 30 --output profile.systing -- ./program args
149
+
150
+ # Or attach to a running process
151
+ sudo systing --duration 30 --output profile.systing --pid <pid>
152
+ ```
153
+
154
+ Build what you profile with frame pointers so systing's unwinder can walk the
155
+ stack, and with symbols for readable frames:
156
+
157
+ ```sh
158
+ gcc -O2 -g -fno-omit-frame-pointer -o program program.c
159
+ ```
160
+
161
+ ### CLI flags
162
+
163
+ | Flag | Default | Description |
164
+ | --------------------------------- | ---------- | ------------------------------------------------------------------ |
165
+ | `--duration` | — | Recording duration in seconds |
166
+ | `--output` | `trace.pb` | Output path; `.systing` selects the profile export this tool reads |
167
+ | `--sample-freq` | `1000` | CPU stack-sampling rate in Hz |
168
+ | `--no-sleep-stack-traces` | off | Skip uninterruptible-sleep stacks |
169
+ | `--no-interruptible-stack-traces` | off | Skip interruptible-sleep stacks |
170
+
171
+ ## Tips
172
+
173
+ ### Symbols
174
+
175
+ gperftools symbolizes addresses from the binary's and its shared libraries'
176
+ symbol tables, so build and link what you profile with symbols (`-g`, not
177
+ stripped). If the hot code lives in a stripped shared library, statically link
178
+ an unstripped build instead.
179
+
180
+ ### Linking
181
+
182
+ Modern toolchains link with `--as-needed` by default, which drops
183
+ `-lprofiler`/`-ltcmalloc` when your program references no symbol from them,
184
+ exactly the case when you enable profiling through the environment variables
185
+ instead of the programmatic API. Force the link with `-Wl,--no-as-needed`, or
186
+ preload the library at runtime with `LD_PRELOAD`. The programmatic API
187
+ (`ProfilerStart`, etc.) references the symbols, so plain
188
+ `-lprofiler`/`-ltcmalloc` works there.
189
+
190
+ ### Converting
191
+
192
+ `pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
193
+ `pprof`/`google-pprof` has no protobuf output.
@@ -1,9 +1,7 @@
1
1
  # C#/F#
2
2
 
3
3
  .NET profiling (C#, F#, and other CLR languages) uses
4
- [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace),
5
- a cross-platform diagnostics tool that collects traces through the runtime's
6
- EventPipe without a native profiler.
4
+ [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace).
7
5
 
8
6
  Install it as a global tool:
9
7
 
@@ -11,6 +9,9 @@ Install it as a global tool:
11
9
  dotnet tool install --global dotnet-trace
12
10
  ```
13
11
 
12
+ The latest `dotnet-trace` needs a matching .NET runtime. If yours is older,
13
+ install a compatible version with `--version`.
14
+
14
15
  ## CPU profiling
15
16
 
16
17
  Periodically samples the call stack. Useful for finding CPU hot spots.
@@ -1,21 +1,24 @@
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).
6
5
 
7
6
  ## CPU profiling
8
7
 
9
8
  Traces function calls and writes them as collapsed stacks. Useful for finding
10
9
  CPU hot spots.
11
10
 
12
- eflambe's default `brendan_gregg` output format is collapsed stacks. Add
13
- `eflambe` to your dependencies, then profile a specific function.
11
+ eflambe's default `brendan_gregg` format is collapsed stacks. Add `eflambe` to
12
+ your dependencies, then profile a specific function.
13
+
14
+ **Keep the call small.** eflambe traces _every_ function call. It doesn't
15
+ sample, so output grows with the number of calls. A single invocation over a
16
+ large input can produce hundreds of MB.
14
17
 
15
18
  ### Elixir
16
19
 
17
20
  ```elixir
18
- # Profile a function as it runs during normal execution (capture 1 call)
21
+ # Profile a function during normal execution (capture 1 call)
19
22
  :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
20
23
 
21
24
  # Directly invoke and profile a function
@@ -25,7 +28,7 @@ eflambe's default `brendan_gregg` output format is collapsed stacks. Add
25
28
  ### Erlang
26
29
 
27
30
  ```erlang
28
- %% Profile a function as it runs during normal execution (capture 1 call)
31
+ %% Profile a function during normal execution (capture 1 call)
29
32
  eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
30
33
 
31
34
  %% Directly invoke and profile a function
@@ -37,6 +40,6 @@ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_g
37
40
  | Option | Default | Description |
38
41
  | ------------------ | --------------- | --------------------------------------------------- |
39
42
  | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
40
- | `output_directory` | project root | Directory to write the output file to |
43
+ | `output_directory` | project root | Directory for the output file |
41
44
  | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
42
45
  | `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
@@ -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
 
@@ -114,9 +114,9 @@ Captures stack traces that led to blocking on synchronization primitives
114
114
  diagnosing synchronization bottlenecks.
115
115
 
116
116
  Disabled by default. Call `runtime.SetBlockProfileRate(rate)` in your program
117
- before the code you want to profile. This applies whether you collect via HTTP
118
- or the programmatic API. Rate is in nanoseconds: `1` captures every blocking
119
- event; higher values sample less.
117
+ before the code to profile. This applies whether you collect via HTTP or the
118
+ programmatic API. Rate is in nanoseconds: `1` captures every blocking event;
119
+ higher values sample less.
120
120
 
121
121
  ```go
122
122
  runtime.SetBlockProfileRate(1)
@@ -145,9 +145,9 @@ Captures stack traces of goroutines holding a contended mutex when another
145
145
  goroutine tries to acquire it. Useful for finding lock contention hot spots.
146
146
 
147
147
  Disabled by default. Call `runtime.SetMutexProfileFraction(rate)` in your
148
- program before the code you want to profile. This applies whether you collect
149
- via HTTP or the programmatic API. `1` captures every contended event; `n`
150
- samples roughly `1/n` events.
148
+ program before the code to profile. This applies whether you collect via HTTP or
149
+ the programmatic API. `1` captures every contended event; `n` samples roughly
150
+ `1/n` events.
151
151
 
152
152
  ```go
153
153
  runtime.SetMutexProfileFraction(1)
@@ -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
4
- [async-profiler](https://github.com/async-profiler/async-profiler), a low
5
- overhead sampling profiler that works with any JVM language.
3
+ Java and Kotlin profiling works with any JVM language, using
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), which also
7
+ resolves native frames and works on older JDKs.
6
8
 
7
9
  ## CPU profiling
8
10
 
9
- Periodically samples the call stack. Useful for finding CPU hot spots.
11
+ Periodically samples the call stack while on CPU. Useful for finding CPU hot
12
+ spots. Recorded as `jdk.ExecutionSample` events, plus `jdk.NativeMethodSample`
13
+ events for threads running native methods.
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,+jdk.NativeMethodSample#enabled=true,+jdk.NativeMethodSample#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`, via the lock recipe
60
+ 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 chunks as it grows
140
+ (`-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` at once.
150
+ Add `--nofree` to suppress the high-volume native `free` events, which otherwise
151
+ 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`.