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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "profiler-md",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "author": {
5
5
  "name": "Tomer Aberbach",
6
6
  "email": "tomer@aberba.ch",
@@ -46,9 +46,10 @@
46
46
  },
47
47
  "license": "MIT",
48
48
  "files": [
49
- "examples",
49
+ "examples/output",
50
50
  "dist",
51
- "docs"
51
+ "docs",
52
+ "skills"
52
53
  ],
53
54
  "type": "module",
54
55
  "sideEffects": false,
@@ -67,20 +68,23 @@
67
68
  },
68
69
  "prettier": "@tomer/prettier-config",
69
70
  "dependencies": {
70
- "@optique/core": "^1.1.0",
71
- "@optique/run": "^1.1.0",
71
+ "@optique/core": "^1.1.1",
72
+ "@optique/run": "^1.1.1",
72
73
  "@shikijs/core": "^4.2.0",
73
74
  "@shikijs/engine-oniguruma": "^4.2.0",
74
75
  "@shikijs/langs": "^4.2.0",
75
- "@shikijs/themes": "^4.2.0",
76
76
  "ansis": "^4.3.1",
77
77
  "convert-source-map": "^2.0.0",
78
78
  "globals": "^17.6.0",
79
79
  "jumbo-json": "^0.2.0",
80
+ "mdast-util-from-markdown": "^2.0.3",
81
+ "mdast-util-gfm-table": "^2.0.0",
82
+ "mdast-util-to-markdown": "^2.1.2",
83
+ "micromark-extension-gfm-table": "^2.1.1",
80
84
  "picomatch": "^4.0.4",
81
85
  "plur": "^6.0.0",
82
- "pprof-format": "^2.2.1",
83
- "pretty-bytes": "^7.1.0",
86
+ "pprof-format": "^2.2.2",
87
+ "pretty-bytes": "^7.1.1",
84
88
  "pretty-ms": "^9.3.0",
85
89
  "source-map-js": "^1.2.1"
86
90
  },
@@ -94,10 +98,10 @@
94
98
  "@types/picomatch": "^4.0.3",
95
99
  "@vitest/coverage-v8": "^4.1.9",
96
100
  "dedent": "^1.7.2",
97
- "diff": "^9.0.0",
98
101
  "eslint": "^10.5.0",
99
102
  "jsdom": "^29.1.1",
100
- "mdast-util-from-markdown": "^2.0.3",
103
+ "knip": "^6.24.0",
104
+ "limit-concur": "^4.0.0",
101
105
  "mdast-util-gfm": "^3.1.0",
102
106
  "micromark-extension-gfm": "^3.0.0",
103
107
  "prettier": "^3.8.4",
@@ -113,14 +117,15 @@
113
117
  "lint:base": "eslint --cache --cache-location node_modules/.cache/eslint/ --fix",
114
118
  "lint": "pnpm lint:base .",
115
119
  "typecheck": "tsc --noEmit",
120
+ "knip": "knip",
116
121
  "test": "vitest",
117
122
  "coverage": "vitest --coverage",
118
123
  "bench": "./scripts/bench",
119
124
  "build": "tsdown",
125
+ "generate-inputs": "./scripts/generate-inputs",
120
126
  "update-readme": "node scripts/update-readme.ts",
121
127
  "check-readme": "node scripts/update-readme.ts --check",
122
128
  "update-examples": "node scripts/update-examples.ts",
123
- "check-examples": "node scripts/update-examples.ts --check",
124
- "pub": "./scripts/publish"
129
+ "check-examples": "node scripts/update-examples.ts --check"
125
130
  }
126
131
  }
package/readme.md CHANGED
@@ -30,42 +30,136 @@
30
30
 
31
31
  - **Polyglot:** supports many profile and heap snapshot formats across many
32
32
  languages
33
- - **Diffing:** compare two profiles or two heap snapshots to see what changed
34
- - **Heap analysis:** reports self and retained size with dominator-based
35
- retention for heap snapshots
33
+ - **Profile analysis:** summarizes sampling rates and category breakdowns, ranks
34
+ the hottest functions by self and total time (or allocations, locks, or
35
+ whatever else was sampled) with per-line, caller, and callee breakdowns, and
36
+ lists the hottest call stacks
37
+ - **Heap analysis:** reports self and retained size with
38
+ [dominator](<https://en.wikipedia.org/wiki/Dominator_(graph_theory)>)-based
39
+ retention, retainer paths, and the largest constructors, closures, and strings
40
+ - **Diffing:** compare two profiles or two heap snapshots to see ranked
41
+ regressions and improvements, with entry matching that ignores run-varying
42
+ identifiers like build hashes
36
43
  - **Source maps:** resolves minified and transpiled locations back to original
37
- sources
38
- - **Zero config:** auto-detects the format, transparently decompresses
39
- gzip/brotli, and reads from stdin
44
+ sources, from standalone or inline source maps
45
+ - **Zero config:** auto-detects the format and the profiler and runtime that
46
+ produced it, decompresses gzip/brotli, and reads from stdin
47
+ - **Fast:** parses and detects formats while streaming the input, and uses
48
+ specialized data structures so large profiles and snapshots convert quickly
49
+ - **Configurable:** control the number of top entries shown, the base URL or
50
+ directory that locations are shown relative to, entry categorization and
51
+ third-party detection, entry filtering, and diff matching; the defaults are
52
+ exported for custom hooks to build on
53
+ - **CLI and API:** use it from the command line or programmatically via a
54
+ fully-typed API with sync and async variants
40
55
  - **Readable in the terminal:** ANSI syntax highlighting with heat-map coloring
41
56
  and automatic paging
42
- - **Configurable:** control the number of top entries shown, working directory
43
- for relative paths, third-party detection, and entry filtering
44
- - **CLI and API:** use it from the command line or programmatically
57
+ - **Self-documenting:** `--help <language>` and `--help <format>` explain how to
58
+ generate and understand each profile type, and shell completions cover bash,
59
+ fish, zsh, and PowerShell
60
+ - **Agent-ready:** ships a [skill](./skills/profile-optimize/SKILL.md) that
61
+ guides an agent through profiling and optimizing your code
45
62
 
46
63
  ## Languages and formats
47
64
 
48
65
  We list a format for a language only if its ecosystem's tools natively generate
49
66
  it. Third-party tools can often convert others, though.
50
67
 
68
+ <!-- prettier-ignore-start -->
69
+
51
70
  <!-- LANGUAGE_MATRIX START -->
52
71
 
53
- | Language | Formats |
54
- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
55
- | [C](docs/languages/c.md)⁠/⁠[C++](docs/languages/cpp.md) | [pprof](docs/formats/pprof.md) |
56
- | [C#](docs/languages/csharp.md)⁠/⁠[F#](docs/languages/fsharp.md) | [Speedscope](docs/formats/speedscope.md) |
57
- | [Elixir](docs/languages/elixir.md)⁠/⁠[Erlang](docs/languages/erlang.md) | [Collapsed stacks](docs/formats/collapsed.md) |
58
- | [Go](docs/languages/go.md) | [pprof](docs/formats/pprof.md) |
59
- | [Java](docs/languages/java.md)⁠/⁠[Kotlin](docs/languages/kotlin.md) | [Collapsed stacks](docs/formats/collapsed.md)<br>[pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
60
- | [JavaScript](docs/languages/javascript.md)⁠/⁠[TypeScript](docs/languages/typescript.md) | [JSC heap snapshot](docs/formats/jsc-heap-snapshot.md) ([Safari](examples/jsc-heap-snapshot.base.json.md), [Safari diff](examples/jsc-heap-snapshot.diff.json.md))<br>[pprof](docs/formats/pprof.md) ([Node.js](examples/node.pprof.md))<br>[V8 CPU profile](docs/formats/v8-cpu-profile.md) ([Node.js](examples/node.base.cpuprofile.md), [Node.js diff](examples/node.diff.cpuprofile.md), [Deno](examples/deno.cpuprofile.md), [Bun](examples/bun.cpuprofile.md))<br>[V8 heap profile](docs/formats/v8-heap-profile.md) ([Node.js](examples/node.heapprofile.md))<br>[V8 heap snapshot](docs/formats/v8-heap-snapshot.md) ([Node.js](examples/node.heapsnapshot.md))<br>[WebKit timeline recording](docs/formats/webkit-timeline-recording.md) ([example](examples/webkit-timeline-recording.json.md)) |
61
- | [Julia](docs/languages/julia.md) | [pprof](docs/formats/pprof.md) |
62
- | [PHP](docs/languages/php.md) | [Speedscope](docs/formats/speedscope.md) |
63
- | [Python](docs/languages/python.md) | [Collapsed stacks](docs/formats/collapsed.md) ([Tachyon](examples/python.base.collapsed.md), [Tachyon diff](examples/python.diff.collapsed.md))<br>[pprof](docs/formats/pprof.md)<br>[Speedscope](docs/formats/speedscope.md) |
64
- | [Ruby](docs/languages/ruby.md) | [Speedscope](docs/formats/speedscope.md) |
65
- | [Rust](docs/languages/rust.md) | [pprof](docs/formats/pprof.md) ([base](examples/rust.base.pprof.md), [diff](examples/rust.diff.pprof.md)) |
72
+ <table>
73
+ <thead>
74
+ <tr><th>Language</th><th>Formats</th></tr>
75
+ </thead>
76
+ <tbody>
77
+ <tr>
78
+ <td><a href="docs/languages/c.md">C⁠/⁠C++</a></td>
79
+ <td>
80
+ <div><a href="docs/formats/pprof.md">pprof</a>:<ul><li>C CPU (<a href="examples/output/c.gperftools.cpu.base.pprof.md">base</a>, <a href="examples/output/c.gperftools.cpu.current.pprof.md">current</a>, <a href="examples/output/c.gperftools.cpu.diff.pprof.md">diff</a>)</li><li>C Heap (<a href="examples/output/c.gperftools.heap.base.pprof.md">base</a>, <a href="examples/output/c.gperftools.heap.current.pprof.md">current</a>, <a href="examples/output/c.gperftools.heap.diff.pprof.md">diff</a>)</li><li>C++ CPU (<a href="examples/output/cpp.gperftools.cpu.base.pprof.md">base</a>, <a href="examples/output/cpp.gperftools.cpu.current.pprof.md">current</a>, <a href="examples/output/cpp.gperftools.cpu.diff.pprof.md">diff</a>)</li><li>C++ Heap (<a href="examples/output/cpp.gperftools.heap.base.pprof.md">base</a>, <a href="examples/output/cpp.gperftools.heap.current.pprof.md">current</a>, <a href="examples/output/cpp.gperftools.heap.diff.pprof.md">diff</a>)</li></ul></div>
81
+ <div><a href="docs/formats/systing.md">systing profile export</a>: <a href="examples/output/c.systing.cpu.base.systing.md">base</a>, <a href="examples/output/c.systing.cpu.current.systing.md">current</a>, <a href="examples/output/c.systing.cpu.diff.systing.md">diff</a></div>
82
+ </td>
83
+ </tr>
84
+ <tr>
85
+ <td><a href="docs/languages/csharp.md">C#⁠/⁠F#</a></td>
86
+ <td>
87
+ <div><a href="docs/formats/speedscope.md">Speedscope</a>:<ul><li>C# (<a href="examples/output/csharp.dotnet-trace.base.speedscope.json.md">base</a>, <a href="examples/output/csharp.dotnet-trace.current.speedscope.json.md">current</a>, <a href="examples/output/csharp.dotnet-trace.diff.speedscope.json.md">diff</a>)</li><li>F# (<a href="examples/output/fsharp.dotnet-trace.base.speedscope.json.md">base</a>, <a href="examples/output/fsharp.dotnet-trace.current.speedscope.json.md">current</a>, <a href="examples/output/fsharp.dotnet-trace.diff.speedscope.json.md">diff</a>)</li></ul></div>
88
+ </td>
89
+ </tr>
90
+ <tr>
91
+ <td><a href="docs/languages/elixir.md">Elixir⁠/⁠Erlang</a></td>
92
+ <td>
93
+ <div><a href="docs/formats/collapsed.md">Collapsed stacks</a>:<ul><li>Elixir (<a href="examples/output/elixir.eflambe.cpu.base.collapsed.md">base</a>, <a href="examples/output/elixir.eflambe.cpu.current.collapsed.md">current</a>, <a href="examples/output/elixir.eflambe.cpu.diff.collapsed.md">diff</a>)</li><li>Erlang (<a href="examples/output/erlang.eflambe.cpu.base.collapsed.md">base</a>, <a href="examples/output/erlang.eflambe.cpu.current.collapsed.md">current</a>, <a href="examples/output/erlang.eflambe.cpu.diff.collapsed.md">diff</a>)</li></ul></div>
94
+ </td>
95
+ </tr>
96
+ <tr>
97
+ <td><a href="docs/languages/go.md">Go</a></td>
98
+ <td>
99
+ <div><a href="docs/formats/pprof.md">pprof</a>:<ul><li>Block (<a href="examples/output/go.pprof.block.base.pprof.md">base</a>, <a href="examples/output/go.pprof.block.current.pprof.md">current</a>, <a href="examples/output/go.pprof.block.diff.pprof.md">diff</a>)</li><li>CPU (<a href="examples/output/go.pprof.cpu.base.pprof.md">base</a>, <a href="examples/output/go.pprof.cpu.current.pprof.md">current</a>, <a href="examples/output/go.pprof.cpu.diff.pprof.md">diff</a>)</li><li>Goroutine (<a href="examples/output/go.pprof.goroutine.base.pprof.md">base</a>, <a href="examples/output/go.pprof.goroutine.current.pprof.md">current</a>, <a href="examples/output/go.pprof.goroutine.diff.pprof.md">diff</a>)</li><li>Heap (<a href="examples/output/go.pprof.heap.base.pprof.md">base</a>, <a href="examples/output/go.pprof.heap.current.pprof.md">current</a>, <a href="examples/output/go.pprof.heap.diff.pprof.md">diff</a>)</li><li>Heap allocations (<a href="examples/output/go.pprof.heap-alloc.base.pprof.md">base</a>, <a href="examples/output/go.pprof.heap-alloc.current.pprof.md">current</a>, <a href="examples/output/go.pprof.heap-alloc.diff.pprof.md">diff</a>)</li><li>Mutex (<a href="examples/output/go.pprof.mutex.base.pprof.md">base</a>, <a href="examples/output/go.pprof.mutex.current.pprof.md">current</a>, <a href="examples/output/go.pprof.mutex.diff.pprof.md">diff</a>)</li><li>Thread creation (<a href="examples/output/go.pprof.threadcreate.base.pprof.md">base</a>, <a href="examples/output/go.pprof.threadcreate.current.pprof.md">current</a>, <a href="examples/output/go.pprof.threadcreate.diff.pprof.md">diff</a>)</li></ul></div>
100
+ </td>
101
+ </tr>
102
+ <tr>
103
+ <td><a href="docs/languages/java.md">Java⁠/⁠Kotlin</a></td>
104
+ <td>
105
+ <div><a href="docs/formats/collapsed.md">Collapsed stacks</a>:<ul><li>Java (<a href="examples/output/java.async-profiler.cpu.base.collapsed.md">base</a>, <a href="examples/output/java.async-profiler.cpu.current.collapsed.md">current</a>, <a href="examples/output/java.async-profiler.cpu.diff.collapsed.md">diff</a>)</li><li>Kotlin (<a href="examples/output/kotlin.async-profiler.cpu.base.collapsed.md">base</a>, <a href="examples/output/kotlin.async-profiler.cpu.current.collapsed.md">current</a>, <a href="examples/output/kotlin.async-profiler.cpu.diff.collapsed.md">diff</a>)</li></ul></div>
106
+ <div><a href="docs/formats/jfr.md">JFR</a>:<ul><li>Java async-profiler All (<a href="examples/output/java.async-profiler.all.base.jfr.md">base</a>, <a href="examples/output/java.async-profiler.all.current.jfr.md">current</a>, <a href="examples/output/java.async-profiler.all.diff.jfr.md">diff</a>)</li><li>Java async-profiler Allocations (<a href="examples/output/java.async-profiler.alloc.base.jfr.md">base</a>, <a href="examples/output/java.async-profiler.alloc.current.jfr.md">current</a>, <a href="examples/output/java.async-profiler.alloc.diff.jfr.md">diff</a>)</li><li>Java async-profiler CPU (<a href="examples/output/java.async-profiler.cpu.base.jfr.md">base</a>, <a href="examples/output/java.async-profiler.cpu.current.jfr.md">current</a>, <a href="examples/output/java.async-profiler.cpu.diff.jfr.md">diff</a>)</li><li>Java async-profiler Live (<a href="examples/output/java.async-profiler.live.base.jfr.md">base</a>, <a href="examples/output/java.async-profiler.live.current.jfr.md">current</a>, <a href="examples/output/java.async-profiler.live.diff.jfr.md">diff</a>)</li><li>Java async-profiler Lock (<a href="examples/output/java.async-profiler.lock.base.jfr.md">base</a>, <a href="examples/output/java.async-profiler.lock.current.jfr.md">current</a>, <a href="examples/output/java.async-profiler.lock.diff.jfr.md">diff</a>)</li><li>Java async-profiler Native memory (<a href="examples/output/java.async-profiler.nativemem.base.jfr.md">base</a>, <a href="examples/output/java.async-profiler.nativemem.current.jfr.md">current</a>, <a href="examples/output/java.async-profiler.nativemem.diff.jfr.md">diff</a>)</li><li>Java async-profiler Wall (<a href="examples/output/java.async-profiler.wall.base.jfr.md">base</a>, <a href="examples/output/java.async-profiler.wall.current.jfr.md">current</a>, <a href="examples/output/java.async-profiler.wall.diff.jfr.md">diff</a>)</li><li>Java JDK All (<a href="examples/output/java.jdk.all.base.jfr.md">base</a>, <a href="examples/output/java.jdk.all.current.jfr.md">current</a>, <a href="examples/output/java.jdk.all.diff.jfr.md">diff</a>)</li><li>Java JDK Allocations (<a href="examples/output/java.jdk.alloc.base.jfr.md">base</a>, <a href="examples/output/java.jdk.alloc.current.jfr.md">current</a>, <a href="examples/output/java.jdk.alloc.diff.jfr.md">diff</a>)</li><li>Java JDK CPU (<a href="examples/output/java.jdk.cpu.base.jfr.md">base</a>, <a href="examples/output/java.jdk.cpu.current.jfr.md">current</a>, <a href="examples/output/java.jdk.cpu.diff.jfr.md">diff</a>)</li><li>Java JDK Live (<a href="examples/output/java.jdk.live.base.jfr.md">base</a>, <a href="examples/output/java.jdk.live.current.jfr.md">current</a>, <a href="examples/output/java.jdk.live.diff.jfr.md">diff</a>)</li><li>Java JDK Lock (<a href="examples/output/java.jdk.lock.base.jfr.md">base</a>, <a href="examples/output/java.jdk.lock.current.jfr.md">current</a>, <a href="examples/output/java.jdk.lock.diff.jfr.md">diff</a>)</li><li>Kotlin async-profiler All (<a href="examples/output/kotlin.async-profiler.all.base.jfr.md">base</a>, <a href="examples/output/kotlin.async-profiler.all.current.jfr.md">current</a>, <a href="examples/output/kotlin.async-profiler.all.diff.jfr.md">diff</a>)</li><li>Kotlin async-profiler Allocations (<a href="examples/output/kotlin.async-profiler.alloc.base.jfr.md">base</a>, <a href="examples/output/kotlin.async-profiler.alloc.current.jfr.md">current</a>, <a href="examples/output/kotlin.async-profiler.alloc.diff.jfr.md">diff</a>)</li><li>Kotlin async-profiler CPU (<a href="examples/output/kotlin.async-profiler.cpu.base.jfr.md">base</a>, <a href="examples/output/kotlin.async-profiler.cpu.current.jfr.md">current</a>, <a href="examples/output/kotlin.async-profiler.cpu.diff.jfr.md">diff</a>)</li><li>Kotlin async-profiler Live (<a href="examples/output/kotlin.async-profiler.live.base.jfr.md">base</a>, <a href="examples/output/kotlin.async-profiler.live.current.jfr.md">current</a>, <a href="examples/output/kotlin.async-profiler.live.diff.jfr.md">diff</a>)</li><li>Kotlin async-profiler Lock (<a href="examples/output/kotlin.async-profiler.lock.base.jfr.md">base</a>, <a href="examples/output/kotlin.async-profiler.lock.current.jfr.md">current</a>, <a href="examples/output/kotlin.async-profiler.lock.diff.jfr.md">diff</a>)</li><li>Kotlin async-profiler Native memory (<a href="examples/output/kotlin.async-profiler.nativemem.base.jfr.md">base</a>, <a href="examples/output/kotlin.async-profiler.nativemem.current.jfr.md">current</a>, <a href="examples/output/kotlin.async-profiler.nativemem.diff.jfr.md">diff</a>)</li><li>Kotlin async-profiler Wall (<a href="examples/output/kotlin.async-profiler.wall.base.jfr.md">base</a>, <a href="examples/output/kotlin.async-profiler.wall.current.jfr.md">current</a>, <a href="examples/output/kotlin.async-profiler.wall.diff.jfr.md">diff</a>)</li><li>Kotlin JDK All (<a href="examples/output/kotlin.jdk.all.base.jfr.md">base</a>, <a href="examples/output/kotlin.jdk.all.current.jfr.md">current</a>, <a href="examples/output/kotlin.jdk.all.diff.jfr.md">diff</a>)</li><li>Kotlin JDK Allocations (<a href="examples/output/kotlin.jdk.alloc.base.jfr.md">base</a>, <a href="examples/output/kotlin.jdk.alloc.current.jfr.md">current</a>, <a href="examples/output/kotlin.jdk.alloc.diff.jfr.md">diff</a>)</li><li>Kotlin JDK CPU (<a href="examples/output/kotlin.jdk.cpu.base.jfr.md">base</a>, <a href="examples/output/kotlin.jdk.cpu.current.jfr.md">current</a>, <a href="examples/output/kotlin.jdk.cpu.diff.jfr.md">diff</a>)</li><li>Kotlin JDK Live (<a href="examples/output/kotlin.jdk.live.base.jfr.md">base</a>, <a href="examples/output/kotlin.jdk.live.current.jfr.md">current</a>, <a href="examples/output/kotlin.jdk.live.diff.jfr.md">diff</a>)</li><li>Kotlin JDK Lock (<a href="examples/output/kotlin.jdk.lock.base.jfr.md">base</a>, <a href="examples/output/kotlin.jdk.lock.current.jfr.md">current</a>, <a href="examples/output/kotlin.jdk.lock.diff.jfr.md">diff</a>)</li></ul></div>
107
+ </td>
108
+ </tr>
109
+ <tr>
110
+ <td><a href="docs/languages/javascript.md">JavaScript⁠/⁠TypeScript</a></td>
111
+ <td>
112
+ <div><a href="docs/formats/jsc-heap-snapshot.md">JSC heap snapshot</a>: <a href="examples/output/javascript.bun.base.jsc-heap-snapshot.json.md">base</a>, <a href="examples/output/javascript.bun.current.jsc-heap-snapshot.json.md">current</a>, <a href="examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md">diff</a></div>
113
+ <div><a href="docs/formats/pprof.md">pprof</a>:<ul><li>CPU (<a href="examples/output/javascript.pprof.cpu.base.pprof.md">base</a>, <a href="examples/output/javascript.pprof.cpu.current.pprof.md">current</a>, <a href="examples/output/javascript.pprof.cpu.diff.pprof.md">diff</a>)</li><li>Heap (<a href="examples/output/javascript.pprof.heap.base.pprof.md">base</a>, <a href="examples/output/javascript.pprof.heap.current.pprof.md">current</a>, <a href="examples/output/javascript.pprof.heap.diff.pprof.md">diff</a>)</li></ul></div>
114
+ <div><a href="docs/formats/v8-cpu-profile.md">V8 CPU profile</a>:<ul><li>Bun (<a href="examples/output/javascript.bun.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.bun.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.bun.diff.cpuprofile.md">diff</a>)</li><li>Chrome (<a href="examples/output/javascript.chrome.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.chrome.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.chrome.diff.cpuprofile.md">diff</a>)</li><li>Deno (<a href="examples/output/javascript.deno.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.deno.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.deno.diff.cpuprofile.md">diff</a>)</li><li>Node.js (<a href="examples/output/javascript.node.base.cpuprofile.md">base</a>, <a href="examples/output/javascript.node.current.cpuprofile.md">current</a>, <a href="examples/output/javascript.node.diff.cpuprofile.md">diff</a>)</li></ul></div>
115
+ <div><a href="docs/formats/v8-heap-profile.md">V8 heap profile</a>:<ul><li>Chrome (<a href="examples/output/javascript.chrome.base.heapprofile.md">base</a>, <a href="examples/output/javascript.chrome.current.heapprofile.md">current</a>, <a href="examples/output/javascript.chrome.diff.heapprofile.md">diff</a>)</li><li>Node.js (<a href="examples/output/javascript.node.base.heapprofile.md">base</a>, <a href="examples/output/javascript.node.current.heapprofile.md">current</a>, <a href="examples/output/javascript.node.diff.heapprofile.md">diff</a>)</li></ul></div>
116
+ <div><a href="docs/formats/v8-heap-snapshot.md">V8 heap snapshot</a>:<ul><li>Bun (<a href="examples/output/javascript.bun.base.heapsnapshot.md">base</a>, <a href="examples/output/javascript.bun.current.heapsnapshot.md">current</a>, <a href="examples/output/javascript.bun.diff.heapsnapshot.md">diff</a>)</li><li>Chrome (<a href="examples/output/javascript.chrome.base.heapsnapshot.md">base</a>, <a href="examples/output/javascript.chrome.current.heapsnapshot.md">current</a>, <a href="examples/output/javascript.chrome.diff.heapsnapshot.md">diff</a>)</li><li>Node.js (<a href="examples/output/javascript.node.base.heapsnapshot.md">base</a>, <a href="examples/output/javascript.node.current.heapsnapshot.md">current</a>, <a href="examples/output/javascript.node.diff.heapsnapshot.md">diff</a>)</li></ul></div>
117
+ <div><a href="docs/formats/webkit-timeline-recording.md">WebKit timeline recording</a>: <a href="examples/output/javascript.safari.base.webkit-timeline-recording.json.md">base</a>, <a href="examples/output/javascript.safari.current.webkit-timeline-recording.json.md">current</a>, <a href="examples/output/javascript.safari.diff.webkit-timeline-recording.json.md">diff</a></div>
118
+ </td>
119
+ </tr>
120
+ <tr>
121
+ <td><a href="docs/languages/julia.md">Julia</a></td>
122
+ <td>
123
+ <div><a href="docs/formats/pprof.md">pprof</a>:<ul><li>Allocations (<a href="examples/output/julia.pprof-jl.alloc.base.pprof.md">base</a>, <a href="examples/output/julia.pprof-jl.alloc.current.pprof.md">current</a>, <a href="examples/output/julia.pprof-jl.alloc.diff.pprof.md">diff</a>)</li><li>CPU (<a href="examples/output/julia.pprof-jl.cpu.base.pprof.md">base</a>, <a href="examples/output/julia.pprof-jl.cpu.current.pprof.md">current</a>, <a href="examples/output/julia.pprof-jl.cpu.diff.pprof.md">diff</a>)</li><li>Wall (<a href="examples/output/julia.pprof-jl.wall.base.pprof.md">base</a>, <a href="examples/output/julia.pprof-jl.wall.current.pprof.md">current</a>, <a href="examples/output/julia.pprof-jl.wall.diff.pprof.md">diff</a>)</li></ul></div>
124
+ <div><a href="docs/formats/v8-heap-snapshot.md">V8 heap snapshot</a>: <a href="examples/output/julia.profile.base.heapsnapshot.md">base</a>, <a href="examples/output/julia.profile.current.heapsnapshot.md">current</a>, <a href="examples/output/julia.profile.diff.heapsnapshot.md">diff</a></div>
125
+ </td>
126
+ </tr>
127
+ <tr>
128
+ <td><a href="docs/languages/php.md">PHP</a></td>
129
+ <td>
130
+ <div><a href="docs/formats/speedscope.md">Speedscope</a>: <a href="examples/output/php.excimer.wall.base.speedscope.json.md">base</a>, <a href="examples/output/php.excimer.wall.current.speedscope.json.md">current</a>, <a href="examples/output/php.excimer.wall.diff.speedscope.json.md">diff</a></div>
131
+ </td>
132
+ </tr>
133
+ <tr>
134
+ <td><a href="docs/languages/python.md">Python</a></td>
135
+ <td>
136
+ <div><a href="docs/formats/collapsed.md">Collapsed stacks</a>:<ul><li>CPU (<a href="examples/output/python.py-spy.cpu.base.collapsed.md">base</a>, <a href="examples/output/python.py-spy.cpu.current.collapsed.md">current</a>, <a href="examples/output/python.py-spy.cpu.diff.collapsed.md">diff</a>)</li><li>Wall (<a href="examples/output/python.py-spy.wall.base.collapsed.md">base</a>, <a href="examples/output/python.py-spy.wall.current.collapsed.md">current</a>, <a href="examples/output/python.py-spy.wall.diff.collapsed.md">diff</a>)</li></ul></div>
137
+ <div><a href="docs/formats/speedscope.md">Speedscope</a>: <a href="examples/output/python.py-spy.cpu.base.speedscope.json.md">base</a>, <a href="examples/output/python.py-spy.cpu.current.speedscope.json.md">current</a>, <a href="examples/output/python.py-spy.cpu.diff.speedscope.json.md">diff</a></div>
138
+ <div><a href="docs/formats/systing.md">systing profile export</a></div>
139
+ </td>
140
+ </tr>
141
+ <tr>
142
+ <td><a href="docs/languages/ruby.md">Ruby</a></td>
143
+ <td>
144
+ <div><a href="docs/formats/collapsed.md">Collapsed stacks</a>: <a href="examples/output/ruby.rbspy.cpu.base.collapsed.md">base</a>, <a href="examples/output/ruby.rbspy.cpu.current.collapsed.md">current</a>, <a href="examples/output/ruby.rbspy.cpu.diff.collapsed.md">diff</a></div>
145
+ <div><a href="docs/formats/pprof.md">pprof</a>: <a href="examples/output/ruby.rbspy.cpu.base.pprof.md">base</a>, <a href="examples/output/ruby.rbspy.cpu.current.pprof.md">current</a>, <a href="examples/output/ruby.rbspy.cpu.diff.pprof.md">diff</a></div>
146
+ <div><a href="docs/formats/speedscope.md">Speedscope</a>: <a href="examples/output/ruby.rbspy.cpu.base.speedscope.json.md">base</a>, <a href="examples/output/ruby.rbspy.cpu.current.speedscope.json.md">current</a>, <a href="examples/output/ruby.rbspy.cpu.diff.speedscope.json.md">diff</a></div>
147
+ </td>
148
+ </tr>
149
+ <tr>
150
+ <td><a href="docs/languages/rust.md">Rust</a></td>
151
+ <td>
152
+ <div><a href="docs/formats/pprof.md">pprof</a>: <a href="examples/output/rust.pprof-rs.cpu.base.pprof.md">base</a>, <a href="examples/output/rust.pprof-rs.cpu.current.pprof.md">current</a>, <a href="examples/output/rust.pprof-rs.cpu.diff.pprof.md">diff</a></div>
153
+ <div><a href="docs/formats/systing.md">systing profile export</a></div>
154
+ </td>
155
+ </tr>
156
+ </tbody>
157
+ </table>
66
158
 
67
159
  <!-- LANGUAGE_MATRIX END -->
68
160
 
161
+ <!-- prettier-ignore-end -->
162
+
69
163
  ## Install
70
164
 
71
165
  ```sh
@@ -82,18 +176,20 @@ $ npm i -g profiler-md
82
176
 
83
177
  ```sh
84
178
  $ profiler-md --help
85
- Usage: profiler-md [(-h/--help [TOPIC])] [-f/--format FORMAT] [-o/--output FILE]
86
- [--top-n N] [--base-url STRING] [--source-maps GLOB...] [--match
87
- REGEX=REPLACEMENT...] [--third-party GLOB...] [--no-pager] [(--color |
88
- --no-color)] ([FILE] | BASE CURRENT)
179
+ Usage: profiler-md [(-h/--help [TOPIC])] [-f/--format FORMAT] [-r/--origin
180
+ ORIGIN] [-o/--output FILE] [--top-n N] [--base-url STRING] [--source-maps
181
+ GLOB...] [--match REGEX=REPLACEMENT...] [--third-party GLOB...] [
182
+ --no-pager] [--color/--no-color] ([FILE] | BASE CURRENT)
89
183
 
90
184
  Converts performance profiles to human and LLM friendly Markdown.
91
185
 
92
186
  -h, --help [TOPIC] Show this help message or topic docs
93
187
  -f, --format FORMAT Input profile format (default: auto)
188
+ -r, --origin ORIGIN Input profile origin (default: auto)
94
189
  -o, --output FILE Output file (default: - for stdout)
95
- --top-n N Number of top entries to show (default: 20)
96
- --base-url STRING Base URL or path to show paths relative to
190
+ --top-n N Top entries to show (default: 20)
191
+ --base-url STRING Base URL or path to show paths relative to, or
192
+ "auto" to infer the common ancestor directory
97
193
  (default: cwd)
98
194
  --source-maps GLOB Source maps (JSON or inline) to apply to profile
99
195
  locations (repeatable)
@@ -102,16 +198,16 @@ Converts performance profiles to human and LLM friendly Markdown.
102
198
  (repeatable)
103
199
  --third-party GLOB Additional URLs or paths to consider third-party
104
200
  (repeatable)
105
- --no-pager Disable stdout output paging (default: auto)
106
- --color Enable or disable ANSI syntax highlighting
201
+ --no-pager Disable stdout paging (default: auto)
202
+ --color, --no-color Enable or disable ANSI syntax highlighting
107
203
  (default: auto)
108
- --no-color
109
- FILE Profile to convert (reads from stdin if omitted)
204
+ FILE Profile to convert (default: stdin)
110
205
  BASE Base profile to diff
111
206
  CURRENT Current profile to diff against the base
112
207
 
113
- Formats: collapsed, jsc-heap-snapshot, pprof, speedscope, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, webkit-timeline-recording
114
- Languages: c, cpp, csharp, fsharp, elixir, erlang, go, java, kotlin, javascript, typescript, julia, php, python, ruby, rust
208
+ Formats: collapsed, jfr, jsc-heap-snapshot, pprof, speedscope, systing, v8-cpu-profile, v8-heap-profile, v8-heap-snapshot, webkit-timeline-recording
209
+ Origins: beam, bun, deno, dotnet-trace, go, jvm, node, node-pprof, pprof-jl, pprof-rs, py-spy, rbspy, safari, systing, tachyon, unknown
210
+ Languages: c/cpp, csharp/fsharp, elixir/erlang, go, java/kotlin, javascript/typescript, julia, php, python, ruby, rust
115
211
  ```
116
212
 
117
213
  <!-- CLI_HELP END -->
@@ -123,7 +219,7 @@ Languages: c, cpp, csharp, fsharp, elixir, erlang, go, java, kotlin, javascript,
123
219
  ```js
124
220
  import { openAsBlob, readFileSync } from 'node:fs'
125
221
  import {
126
- defaultCategorizeEntry,
222
+ defaultCategorizeEntries,
127
223
  defaultMatchEntry,
128
224
  defaultShowEntry,
129
225
  diffProfiles,
@@ -132,7 +228,7 @@ import {
132
228
  profileToMdAsync,
133
229
  } from 'profiler-md'
134
230
 
135
- // Auto-detect format (async)
231
+ // Auto-detect format and origin (async)
136
232
  console.log(await profileToMdAsync(await openAsBlob(`example.cpuprofile`)))
137
233
  console.log(await profileToMdAsync(await openAsBlob(`example.pprof`)))
138
234
 
@@ -143,14 +239,25 @@ console.log(
143
239
  format: `pprof`,
144
240
  }),
145
241
  )
242
+ // Explicit origin
243
+ console.log(
244
+ await profileToMdAsync({
245
+ data: await openAsBlob(`example.cpuprofile`),
246
+ origin: `deno`,
247
+ }),
248
+ )
146
249
 
147
250
  // Synchronous usage (auto-detect)
148
251
  console.log(profileToMd(readFileSync(`example.cpuprofile`, `utf8`)))
149
252
  console.log(profileToMd(readFileSync(`example.pprof`)))
150
253
 
151
- // Synchronous usage with explicit format
254
+ // Synchronous usage with explicit format and origin
152
255
  console.log(
153
- profileToMd({ data: readFileSync(`example.pprof`), format: `pprof` }),
256
+ profileToMd({
257
+ data: readFileSync(`example.pprof`),
258
+ format: `pprof`,
259
+ origin: `node-pprof`,
260
+ }),
154
261
  )
155
262
 
156
263
  // Diff two profiles or two heap snapshots (async, auto-detect)
@@ -179,22 +286,25 @@ console.log(
179
286
  const options = {
180
287
  // Show top 10 functions instead of the default 20.
181
288
  topN: 10,
182
- // Make paths relative to a custom base URL or directory.
289
+ // Make paths relative to a custom base URL or directory, or pass `auto` to
290
+ // infer the profiled files' common ancestor directory.
183
291
  baseURL: `/path/to/project`,
184
- matchEntry: entry => {
292
+ matchEntry: (entry, context) => {
185
293
  if (entry.location?.url.pathname.includes(`/bundle.`)) {
186
294
  // Match bundled entries when diffing by name only, ignoring
187
295
  // content-hashed filenames.
188
296
  return { name: entry.name }
189
297
  }
190
- return defaultMatchEntry(entry)
298
+ return defaultMatchEntry(entry, context)
191
299
  },
192
- categorizeEntry: entry => {
193
- if (entry.location?.url.pathname.includes(`/vendor/`)) {
300
+ categorizeEntries: (entries, context) => {
301
+ const categories = defaultCategorizeEntries(entries, context)
302
+ return entries.map((entry, index) =>
194
303
  // Treat an additional vendor directory as third-party.
195
- return `third-party`
196
- }
197
- return defaultCategorizeEntry(entry)
304
+ entry.location?.url?.pathname.includes(`/vendor/`)
305
+ ? `third-party`
306
+ : categories[index],
307
+ )
198
308
  },
199
309
  showEntry: entry =>
200
310
  defaultShowEntry(entry) &&
@@ -206,8 +316,8 @@ console.log(
206
316
  await profileToMdAsync(await openAsBlob(`example.cpuprofile`), options),
207
317
  )
208
318
 
209
- // The same options also apply to diffs. `matchEntry` only takes effect here,
210
- // where it controls which entries are considered the same across the two sides.
319
+ // The same options apply to diffs. `matchEntry` takes effect only here, where
320
+ // it controls which entries count as the same across the two sides.
211
321
  console.log(
212
322
  await diffProfilesAsync(
213
323
  await openAsBlob(`base.pprof`),
@@ -0,0 +1,160 @@
1
+ ---
2
+ name: profile-optimize
3
+ description: Generate a performance profile, identify hotspots, and optimize.
4
+ argument-hint: '[what to focus on]'
5
+ allowed-tools: Bash(profiler-md *)
6
+ ---
7
+
8
+ Generate a performance profile, identify hotspots, and optimize.
9
+
10
+ Focus: $ARGUMENTS
11
+
12
+ # Workflow
13
+
14
+ 1. Decide what to profile (time or memory) and write an isolated script that
15
+ exercises the slow path if nothing runs it directly. Run
16
+ `profiler-md --help <language>` for profiling instructions
17
+ 2. Capture a baseline: generate a profile, convert it with
18
+ `profiler-md path/to/profile`, and read the full report, focusing on:
19
+ - Hottest functions: self % shows where time is spent or memory is allocated,
20
+ not just passed through
21
+ - Hottest call stacks: the full call path to the hot functions
22
+ 3. Identify the hottest 1-3 functions by self % and read their source:
23
+ - Native functions are often unavoidable but may indicate unnecessary work
24
+ (e.g. parsing the same data twice, creating many intermediate arrays)
25
+ - Project functions are direct targets
26
+ 4. State a hypothesis (see "Hypotheses"). If the bottleneck is unclear, reread
27
+ the hot function and its callers
28
+ 5. Apply the minimal change that addresses the bottleneck, one optimization at a
29
+ time. Leave unrelated code alone. Optimize the general case, not the
30
+ benchmark: don't exploit quirks of the profiled input (its size, ordering,
31
+ value distribution, or hardcoded special cases for it) unless they're
32
+ guaranteed properties of real inputs
33
+ 6. Run the relevant tests: if any newly fail, fix the optimization or revert it
34
+ 7. Capture a new report as in step 2 and compare self % for the targeted
35
+ function(s) against the baseline: if the improvement is negligible or
36
+ unclear, revert and go back to step 4 instead of iterating blindly. If the
37
+ comparison is too noisy to call, collect more samples (see "Measurement");
38
+ don't fall back to manual timing
39
+ 8. If the goal is unmet and a clear bottleneck remains, repeat from step 3 with
40
+ the new profile as the baseline
41
+ 9. Report:
42
+ - Before vs after for the hot function(s)
43
+ - Any other functions that moved significantly (regressions)
44
+
45
+ # Measurement
46
+
47
+ profiler-md reports are the ONLY measurements in this workflow. NEVER time
48
+ manually (e.g. `time` or `performance.now()`).
49
+
50
+ Manual timing yields one noisy end-to-end number that can improve for reasons
51
+ unrelated to the change (machine load, caches, GC timing), and its
52
+ instrumentation distorts the hot path. A profile attributes work to functions,
53
+ so a before/after comparison proves the optimization removed the targeted work,
54
+ not merely that one run was faster.
55
+
56
+ If a profile has too few samples to trust, collect more:
57
+
58
+ - Run the workload longer or loop it more times
59
+ - Raise the sampling frequency if the profiler supports it (see
60
+ `profiler-md --help <language>`)
61
+ - Regenerate the profile and compare again
62
+
63
+ # Hypotheses
64
+
65
+ Before changing anything, state:
66
+
67
+ - What is the bottleneck? (e.g. "repeated object allocation in the hot loop",
68
+ "O(n²) suffix scan", "redundant map lookups")
69
+ - What is the expected fix? (e.g. "hoist allocation outside loop", "use a
70
+ two-pointer suffix scan", "cache the lookup result")
71
+ - Why will it be faster?
72
+
73
+ # Focus areas
74
+
75
+ Sub-bullets are examples, not exhaustive lists.
76
+
77
+ - Time complexity: reduce the asymptotic work per input element
78
+ - Replace `O(n²)` scans with single-pass or two-pointer algorithms
79
+ - Use heaps for top-N instead of fully sorting
80
+ - Sort once and binary search instead of repeated linear scans
81
+ - Redundant work: compute each result once
82
+ - Avoid parsing or computing the same data twice; cache or memoize repeated
83
+ lookups
84
+ - Hoist loop-invariant computation out of loops
85
+ - Build lookup tables once instead of searching repeatedly; intern repeated
86
+ values
87
+ - Update incrementally instead of recomputing from scratch
88
+ - Persist expensive results between invocations, keyed by input so stale
89
+ entries are never served
90
+ - Work avoidance: skip or defer computation whose result may never be used
91
+ - Exit early once the answer is known
92
+ - Filter before expensive transforms, not after
93
+ - Order checks cheapest-first so expensive predicates run last and rarely
94
+ - Add fast paths for the common input shape
95
+ - Defer initialization and large dependency loading until first use,
96
+ especially on the startup critical path
97
+ - Debounce or throttle work triggered by bursty events
98
+ - Data structure selection: match the structure to the access pattern
99
+ - Use sets/maps for membership and lookup instead of linear scans
100
+ - Use bitsets for dense boolean membership
101
+ - Use a ring buffer for FIFO access instead of shifting an array
102
+ - Cache locality: lay out data so hot loops read memory sequentially
103
+ - Compressed sparse row (CSR) format
104
+ - Data-oriented design (struct-of-arrays, packed primitive arrays)
105
+ - Sparse arrays indexed by sequential IDs instead of integer-keyed hash maps
106
+ - Iterate in storage order (e.g. row-major for nested arrays)
107
+ - Allocation and copying: allocate and copy less in hot paths
108
+ - Hoist allocations out of hot loops; reuse buffers instead of reallocating
109
+ - Preallocate arrays and buffers to their known final size instead of growing
110
+ incrementally
111
+ - Avoid intermediate collections from chained transforms; fuse them into one
112
+ pass
113
+ - Use views/slices over underlying data instead of copying; defer cloning
114
+ until mutation is needed
115
+ - Memory footprint: hold and retain only what the computation needs
116
+ - Stream or process incrementally instead of materializing intermediates
117
+ - Bound caches (e.g. LRU); use weak references for object-keyed caches
118
+ - Remove listeners, timers, and subscriptions when done
119
+ - Avoid closures capturing large outer scopes; drop references held by
120
+ long-lived structures once no longer needed
121
+ - String handling: minimize the strings created and scanned in hot paths
122
+ - Avoid repeated concatenation in loops
123
+ - Work with indices or char codes into the original string instead of creating
124
+ substrings
125
+ - Minimize serialization/deserialization round-trips
126
+ - Avoid regex in hot paths
127
+ - Runtime friendliness: stay on the JIT's optimized fast paths
128
+ - Keep object shapes consistent (same fields, same initialization order)
129
+ - Avoid polymorphic call sites and mixed-type arrays in hot paths
130
+ - Keep numbers in the runtime's fast representations; avoid deoptimization
131
+ triggers in hot loops
132
+ - I/O and queries: make fewer round-trips and move fewer bytes
133
+ - Read or write in large chunks instead of many small operations
134
+ - Eliminate N+1 patterns by coalescing small queries or requests into one
135
+ batch
136
+ - Push filtering, aggregation, and pagination down to the data store; add
137
+ indexes matching the hot query's predicates
138
+ - Compress or use binary encodings for large transfers; send only the fields
139
+ the consumer reads
140
+ - Concurrency: use idle hardware for independent work
141
+ - Run independent async operations concurrently, bounded to what the awaited
142
+ resource can absorb
143
+ - Overlap I/O waits with computation instead of strictly sequencing them
144
+ - Split CPU-bound work across threads or processes; use SIMD where the
145
+ platform supports it
146
+ - Contention and backpressure: keep concurrent parts from waiting on or
147
+ overwhelming each other
148
+ - Minimize time spent holding locks; shrink critical sections
149
+ - Shard or partition shared state; prefer immutable or thread-local data over
150
+ shared mutable state
151
+ - Bound queues so producers can't outrun consumers; shed or coalesce load when
152
+ the system is saturated
153
+ - Precision trade-offs: do cheaper work that's good enough, only when the
154
+ consumer tolerates the difference
155
+ - Use approximate algorithms (sampling, sketches, bloom filters)
156
+ - Lower resolution or cap iteration counts when the output tolerance allows
157
+ - Observability overhead: keep instrumentation cheap enough that it doesn't
158
+ distort the hot path
159
+ - Keep logging, tracing, and assertions out of hot loops
160
+ - Sample or gate expensive instrumentation behind flags