profiler-md 0.6.0 → 0.8.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 (239) hide show
  1. package/dist/cli/index.mjs +12953 -4258
  2. package/dist/index.d.mts +1182 -435
  3. package/dist/index.js +2 -2
  4. package/docs/api.md +138 -0
  5. package/docs/formats/callgrind.md +25 -0
  6. package/docs/formats/collapsed.md +5 -3
  7. package/docs/formats/ghc-eventlog.md +20 -0
  8. package/docs/formats/ghc-json-profile.md +23 -0
  9. package/docs/formats/hprof.md +21 -0
  10. package/docs/formats/jfr.md +2 -2
  11. package/docs/formats/jsc-heap-snapshot.md +10 -4
  12. package/docs/formats/memray.md +30 -0
  13. package/docs/formats/perf.md +74 -0
  14. package/docs/formats/pprof.md +4 -2
  15. package/docs/formats/speedscope.md +3 -2
  16. package/docs/formats/systing.md +17 -15
  17. package/docs/formats/v8-cpu-profile.md +4 -3
  18. package/docs/formats/v8-heap-profile.md +8 -5
  19. package/docs/formats/v8-heap-snapshot.md +8 -3
  20. package/docs/formats/webkit-timeline-recording.md +6 -0
  21. package/docs/languages/c.md +119 -32
  22. package/docs/languages/csharp.md +5 -3
  23. package/docs/languages/elixir.md +19 -11
  24. package/docs/languages/fortran.md +141 -0
  25. package/docs/languages/go.md +33 -10
  26. package/docs/languages/haskell.md +134 -0
  27. package/docs/languages/java.md +81 -26
  28. package/docs/languages/javascript.md +43 -25
  29. package/docs/languages/julia.md +21 -18
  30. package/docs/languages/php.md +19 -0
  31. package/docs/languages/python.md +105 -14
  32. package/docs/languages/ruby.md +15 -16
  33. package/docs/languages/rust.md +11 -10
  34. package/docs/languages/swift.md +135 -0
  35. package/docs/languages/zig.md +155 -0
  36. package/package.json +42 -42
  37. package/readme.md +302 -259
  38. package/skills/profile-optimize/SKILL.md +4 -2
  39. package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
  40. package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
  41. package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
  42. package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
  43. package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
  44. package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
  45. package/examples/output/c.systing.cpu.base.systing.md +0 -824
  46. package/examples/output/c.systing.cpu.current.systing.md +0 -825
  47. package/examples/output/c.systing.cpu.diff.systing.md +0 -238
  48. package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
  49. package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
  50. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
  51. package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
  52. package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
  53. package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
  54. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
  55. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
  56. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
  57. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
  58. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
  59. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
  60. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
  61. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
  62. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
  63. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
  64. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
  65. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
  66. package/examples/output/go.pprof.block.base.pprof.md +0 -86
  67. package/examples/output/go.pprof.block.current.pprof.md +0 -83
  68. package/examples/output/go.pprof.block.diff.pprof.md +0 -42
  69. package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
  70. package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
  71. package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
  72. package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
  73. package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
  74. package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
  75. package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
  76. package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
  77. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
  78. package/examples/output/go.pprof.heap.base.pprof.md +0 -154
  79. package/examples/output/go.pprof.heap.current.pprof.md +0 -146
  80. package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
  81. package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
  82. package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
  83. package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
  84. package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
  85. package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
  86. package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
  87. package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
  88. package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
  89. package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
  90. package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
  91. package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
  92. package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
  93. package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
  94. package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
  95. package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
  96. package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
  97. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
  98. package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
  99. package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
  100. package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
  101. package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
  102. package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
  103. package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
  104. package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
  105. package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
  106. package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
  107. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
  108. package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
  109. package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
  110. package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
  111. package/examples/output/java.jdk.all.base.jfr.md +0 -1024
  112. package/examples/output/java.jdk.all.current.jfr.md +0 -1010
  113. package/examples/output/java.jdk.all.diff.jfr.md +0 -311
  114. package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
  115. package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
  116. package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
  117. package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
  118. package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
  119. package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
  120. package/examples/output/java.jdk.live.base.jfr.md +0 -1029
  121. package/examples/output/java.jdk.live.current.jfr.md +0 -1035
  122. package/examples/output/java.jdk.live.diff.jfr.md +0 -289
  123. package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
  124. package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
  125. package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
  126. package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
  127. package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
  128. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
  129. package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
  130. package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
  131. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
  132. package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
  133. package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
  134. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
  135. package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
  136. package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
  137. package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
  138. package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
  139. package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
  140. package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
  141. package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
  142. package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
  143. package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
  144. package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
  145. package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
  146. package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
  147. package/examples/output/javascript.node.base.cpuprofile.md +0 -136
  148. package/examples/output/javascript.node.base.heapprofile.md +0 -56
  149. package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
  150. package/examples/output/javascript.node.current.cpuprofile.md +0 -119
  151. package/examples/output/javascript.node.current.heapprofile.md +0 -52
  152. package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
  153. package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
  154. package/examples/output/javascript.node.diff.heapprofile.md +0 -34
  155. package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
  156. package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
  157. package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
  158. package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
  159. package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
  160. package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
  161. package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
  162. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
  163. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
  164. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
  165. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
  166. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
  167. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
  168. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
  169. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
  170. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
  171. package/examples/output/julia.pprof-jl.wall.base.pprof.md +0 -181
  172. package/examples/output/julia.pprof-jl.wall.current.pprof.md +0 -193
  173. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +0 -64
  174. package/examples/output/julia.profile.base.heapsnapshot.md +0 -590
  175. package/examples/output/julia.profile.current.heapsnapshot.md +0 -590
  176. package/examples/output/julia.profile.diff.heapsnapshot.md +0 -288
  177. package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
  178. package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
  179. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
  180. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
  181. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
  182. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
  183. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
  184. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
  185. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
  186. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
  187. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
  188. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
  189. package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
  190. package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
  191. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
  192. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
  193. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
  194. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
  195. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
  196. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
  197. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
  198. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
  199. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
  200. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
  201. package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
  202. package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
  203. package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
  204. package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
  205. package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
  206. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
  207. package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
  208. package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
  209. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
  210. package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
  211. package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
  212. package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
  213. package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
  214. package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
  215. package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
  216. package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
  217. package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
  218. package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
  219. package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
  220. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
  221. package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
  222. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
  223. package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
  224. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
  225. package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
  226. package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
  227. package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
  228. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
  229. package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
  230. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
  231. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
  232. package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
  233. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
  234. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
  235. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
  236. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
  237. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
  238. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
  239. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +0 -24
package/docs/api.md ADDED
@@ -0,0 +1,138 @@
1
+ # API
2
+
3
+ The API accepts the same inputs and options as the CLI: pass a profile (or two,
4
+ to diff) and get Markdown back. Every function has a sync and an async variant.
5
+ The async variants accept a `Blob`, so large profiles stream instead of loading
6
+ into memory.
7
+
8
+ ## Converting
9
+
10
+ The API auto-detects the format and origin by default:
11
+
12
+ ```js
13
+ import { openAsBlob, readFileSync } from 'node:fs'
14
+ import { profileToMd, profileToMdAsync } from 'profiler-md'
15
+
16
+ // Async (streams the input)
17
+ console.log(await profileToMdAsync(await openAsBlob(`example.cpuprofile`)))
18
+ console.log(await profileToMdAsync(await openAsBlob(`example.pprof`)))
19
+
20
+ // Sync
21
+ console.log(profileToMd(readFileSync(`example.cpuprofile`, `utf8`)))
22
+ console.log(profileToMd(readFileSync(`example.pprof`)))
23
+ ```
24
+
25
+ Pass an object to specify the format or origin explicitly:
26
+
27
+ ```js
28
+ console.log(
29
+ await profileToMdAsync({
30
+ data: await openAsBlob(`example.pprof`),
31
+ format: `pprof`,
32
+ }),
33
+ )
34
+ console.log(
35
+ await profileToMdAsync({
36
+ data: await openAsBlob(`example.cpuprofile`),
37
+ origin: `deno`,
38
+ }),
39
+ )
40
+ console.log(
41
+ profileToMd({
42
+ data: readFileSync(`example.pprof`),
43
+ format: `pprof`,
44
+ origin: `node-pprof`,
45
+ }),
46
+ )
47
+ ```
48
+
49
+ ## Diffing
50
+
51
+ Diff two profiles or two heap snapshots:
52
+
53
+ ```js
54
+ import { openAsBlob, readFileSync } from 'node:fs'
55
+ import { diffProfiles, diffProfilesAsync } from 'profiler-md'
56
+
57
+ // Async, auto-detect
58
+ console.log(
59
+ await diffProfilesAsync(
60
+ await openAsBlob(`base.cpuprofile`),
61
+ await openAsBlob(`current.cpuprofile`),
62
+ ),
63
+ )
64
+ console.log(
65
+ await diffProfilesAsync(
66
+ await openAsBlob(`base.heapsnapshot`),
67
+ await openAsBlob(`current.heapsnapshot`),
68
+ ),
69
+ )
70
+
71
+ // Sync, explicit format
72
+ console.log(
73
+ diffProfiles(
74
+ { data: readFileSync(`base.pprof`), format: `pprof` },
75
+ { data: readFileSync(`current.pprof`), format: `pprof` },
76
+ ),
77
+ )
78
+ ```
79
+
80
+ ## Options
81
+
82
+ All functions take an options object as their last argument. The default for
83
+ each callback option is exported so a custom callback can build on it:
84
+
85
+ ```js
86
+ import { openAsBlob } from 'node:fs'
87
+ import {
88
+ defaultCategorizeFunctions,
89
+ defaultMatchEntry,
90
+ defaultShowEntry,
91
+ diffProfilesAsync,
92
+ profileToMdAsync,
93
+ } from 'profiler-md'
94
+
95
+ const options = {
96
+ // Show the top 10 functions of each ranking instead of the default 20.
97
+ topN: 10,
98
+ // Break a ranking down by category, one subsection per category accounting
99
+ // for at least 5% of the shown functions instead of the default 1%. Pass 0 to
100
+ // break down every category.
101
+ minCategoryShare: 0.05,
102
+ // Make paths relative to a custom base URL or directory, or pass `auto` to
103
+ // infer the profiled files' common ancestor directory.
104
+ baseURL: `/path/to/project`,
105
+ matchEntry: (entry, context) => {
106
+ if (entry.location?.url?.pathname.includes(`/bundle.`)) {
107
+ // Match bundled entries when diffing by name only, ignoring
108
+ // content-hashed filenames.
109
+ return { name: entry.name }
110
+ }
111
+ return defaultMatchEntry(entry, context)
112
+ },
113
+ categorizeFunctions: (entries, context) => {
114
+ const categories = defaultCategorizeFunctions(entries, context)
115
+ return entries.map((entry, index) =>
116
+ // Treat an additional vendor directory as third-party.
117
+ entry.location?.url?.pathname.includes(`/vendor/`)
118
+ ? `third-party`
119
+ : categories[index],
120
+ )
121
+ },
122
+ showEntry: entry =>
123
+ defaultShowEntry(entry) &&
124
+ // Exclude entries from a specific file.
125
+ !entry.location?.url?.pathname.includes(`/path/to/project/src/noisy`),
126
+ }
127
+ console.log(await profileToMdAsync(await openAsBlob(`example.pprof`), options))
128
+
129
+ // The same options apply to diffs. `matchEntry` takes effect only here, where
130
+ // it controls which entries count as the same across the two sides.
131
+ console.log(
132
+ await diffProfilesAsync(
133
+ await openAsBlob(`base.pprof`),
134
+ await openAsBlob(`current.pprof`),
135
+ options,
136
+ ),
137
+ )
138
+ ```
@@ -0,0 +1,25 @@
1
+ # Callgrind
2
+
3
+ Callgrind is the plain-text call graph profiling format written by
4
+ [Valgrind](https://valgrind.org)'s
5
+ [Callgrind](https://valgrind.org/docs/manual/cl-manual.html) tool.
6
+ `callgrind_annotate` and KCachegrind/QCachegrind read it, and other profilers
7
+ (e.g. rbspy, R's proftools) emit it too.
8
+
9
+ A header declares the cost events (`events:`, e.g. `Ir` for instructions
10
+ executed) and position columns (`positions:`). The body attributes per-line
11
+ costs to functions (`fl=`/`fn=` specs followed by cost lines) and records each
12
+ call's count and inclusive cost (`cfn=`/`calls=`).
13
+
14
+ It stores a weighted call graph instead of call stacks, so the output shows
15
+ per-function and per-line self costs plus each function's callers and callees
16
+ with their recorded call counts and inclusive costs. A function's total is its
17
+ self cost plus its outgoing calls' inclusive costs. It excludes the calls within
18
+ a recursion cycle, which re-count the same work. Those calls still appear as
19
+ callers and callees, so their percentages can exceed 100%.
20
+
21
+ It supports arbitrary metric units, multiple metrics per call graph, and a
22
+ single call graph per file.
23
+
24
+ Files have no standard extension. `callgrind.out.<pid>` and `.callgrind` are
25
+ common.
@@ -1,12 +1,14 @@
1
1
  # Collapsed stacks
2
2
 
3
3
  Collapsed stacks is the plain-text interchange format from Brendan Gregg's
4
- [FlameGraph](https://github.com/brendangregg/FlameGraph) tooling. It is emitted
5
- by many profilers.
4
+ [FlameGraph](https://github.com/brendangregg/FlameGraph) tooling. Many profilers
5
+ emit it.
6
6
 
7
7
  Each line is one call stack, written root-to-leaf and joined by `;`, followed by
8
8
  a space and an integer sample count. Frames are opaque strings and carry no
9
9
  units.
10
10
 
11
- Files have no standard extension; `.collapsed`, `.folded`, and `.txt` are all
11
+ It supports no metrics and a single profile per file.
12
+
13
+ Files have no standard extension. `.collapsed`, `.folded`, and `.txt` are
12
14
  common.
@@ -0,0 +1,20 @@
1
+ # GHC eventlog
2
+
3
+ The binary event stream
4
+ [GHC](https://downloads.haskell.org/ghc/latest/docs/users_guide/eventlog-formats.html)'s
5
+ runtime writes for a program run with `+RTS -l`, recording what the runtime did
6
+ and when: garbage collections and thread scheduling. A program compiled with
7
+ `-prof` and run with `+RTS -p` adds one cost-centre sample per tick.
8
+
9
+ A log opens with a header declaring every event type the runtime can write, each
10
+ with its payload size. The events follow, in the order they happened: the
11
+ cost-centre definitions the runtime writes at startup, then the samples
12
+ referencing them.
13
+
14
+ The samples are the cost-centre stacks the profiler observed, so the log
15
+ converts to the time profile they record. It omits the allocation totals the
16
+ JSON report contains.
17
+
18
+ It supports a single metric per profile and a single profile per file.
19
+
20
+ Files use the `.eventlog` extension.
@@ -0,0 +1,23 @@
1
+ # GHC JSON profile
2
+
3
+ The GHC JSON profile is the machine-readable report
4
+ [GHC](https://downloads.haskell.org/ghc/latest/docs/users_guide/profiling.html)'s
5
+ runtime writes for a program compiled with `-prof` and run with `+RTS -pj`. It
6
+ contains the same measurements as the text report `+RTS -p` writes.
7
+
8
+ The report is a table of the program's cost centres, each a binding GHC
9
+ annotated, and a tree of cost-centre stacks. A node contains the costs of that
10
+ stack alone, excluding the stacks extending it: the ticks the profiler sampled,
11
+ the bytes the program allocated, and the times it entered the stack.
12
+
13
+ Ticks and allocation are measured differently, so each converts to its own
14
+ profile. A tick is one sample of the time profile, taken every millisecond by
15
+ default. The tick timer samples every capability whether or not it is running
16
+ Haskell, so the time profile measures wall time and attributes the idle ticks to
17
+ the built-in `IDLE` cost centre. The runtime counts bytes and entries exactly
18
+ and independently, so the allocation profile reports both as measured quantities
19
+ and states no rate.
20
+
21
+ It supports multiple metrics per profile and a single report per file.
22
+
23
+ Files use the `.prof` extension, named after the program as `<program>.prof`.
@@ -0,0 +1,21 @@
1
+ # HPROF
2
+
3
+ [HPROF](https://github.com/openjdk/jdk/blob/master/src/hotspot/share/services/heapDumper.cpp)
4
+ is the JVM's binary heap dump format, written by HotSpot's own heap dumper
5
+ behind `jmap -dump`, `jcmd GC.heap_dump`, `HotSpotDiagnosticMXBean.dumpHeap`,
6
+ and `-XX:+HeapDumpOnOutOfMemoryError`.
7
+
8
+ A dump begins with a format name (`JAVA PROFILE 1.0.2`), an identifier size, and
9
+ a timestamp, followed by tagged records: the runtime's symbols, the classes it
10
+ loaded, and heap dump segments holding a record per class, instance, and array,
11
+ plus the GC roots the live objects are reachable from.
12
+
13
+ It captures the object graph at a single point in time, so it shows what the
14
+ heap holds rather than where allocation happens. Sizes are the bytes the dump
15
+ records for each object. The dump omits object headers, so a class's instances
16
+ measure smaller here than the memory they occupy.
17
+
18
+ Android's ART writes a dialect of the format with records of its own, which this
19
+ tool doesn't read.
20
+
21
+ Files use the `.hprof` extension.
@@ -8,8 +8,8 @@ binary profiling format, written by the JDK's built-in
8
8
  A recording splits into self-contained chunks of LEB128 varint-encoded events.
9
9
  One recording can mix event kinds, so it converts to one profile per kind:
10
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.
11
+ sampling measured by allocated bytes, live-object sampling measured by retained
12
+ bytes, and lock contention measured by blocked time.
13
13
 
14
14
  It supports a single metric per profile and multiple profiles per file.
15
15
 
@@ -5,9 +5,15 @@ The
5
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
- Unlike heap profiles, which sample allocations, snapshots show what objects
9
- currently exist in memory. This is useful for diagnosing memory leaks rather
10
- than allocation hotspots.
8
+ A snapshot is a flat integer array of node records (an id, a self size, a class
9
+ name, and flags marking VM-internal instances) and a flat integer array of edge
10
+ records (the two nodes it connects, a type, and a name), alongside the string
11
+ tables the class and edge names index into.
12
+
13
+ Snapshots show what objects exist in memory, unlike heap profiles, which sample
14
+ allocations. That makes them useful for diagnosing memory leaks rather than
15
+ allocation hotspots.
11
16
 
12
17
  Files use the `.json` extension and contain `"type": "Inspector"` and a
13
- `"version"` of `2` (Safari/JSC) or `3` (Bun's `generateHeapSnapshot("jsc")`).
18
+ `"version"`: `3` in current WebKit and in Bun's `generateHeapSnapshot("jsc")`,
19
+ and `2` in the older Safari releases that wrote the previous revision.
@@ -0,0 +1,30 @@
1
+ # memray
2
+
3
+ The capture file [memray](https://github.com/bloomberg/memray), Bloomberg's
4
+ Python memory profiler, writes for its own reporters to read.
5
+
6
+ A capture is a binary stream of records describing a program's allocations: the
7
+ code objects its functions belong to, each thread's frame pushes and pops, and
8
+ every allocation and deallocation with its address, size, and allocator. A
9
+ capture written with `--aggregate` states each stack's peak and leaked totals
10
+ instead of every allocation. `memray run` compresses either one with LZ4, which
11
+ this tool decompresses itself.
12
+
13
+ A capture contains no totals, so both measures come from replaying the stream:
14
+ peak memory from the allocations live at the moment total memory was highest,
15
+ and leaked memory from those still live at the end. `memray flamegraph` and
16
+ `memray flamegraph --leaks` report those measures. The measures count different
17
+ allocations, so a capture converts to a profile each. Because memray records
18
+ every allocation, the output states bytes per allocation rather than a sampling
19
+ rate.
20
+
21
+ This tool skips native frames, recorded by `memray run --native`, because
22
+ resolving them means symbolizing instruction pointers against the binaries the
23
+ traced process ran. A capture recorded with them still converts, showing its
24
+ Python frames.
25
+
26
+ It supports a single byte metric per profile and multiple profiles per file.
27
+
28
+ Files use the `.bin` extension. This tool reads capture versions 12 and 13,
29
+ written by memray 1.19 and 1.20. In version 13 the header ends with the traced
30
+ process's module search paths, and the records are encoded as in version 12.
@@ -0,0 +1,74 @@
1
+ # perf.data
2
+
3
+ The binary file [Linux `perf`](https://perfwiki.github.io/main/) writes: the
4
+ on-disk form of the kernel's own `perf_event` records, specified by the kernel's
5
+ [`perf.data` file format documentation](https://github.com/torvalds/linux/blob/master/tools/perf/Documentation/perf.data-file-format.txt)
6
+ and
7
+ [`perf_event.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/perf_event.h).
8
+ Android's
9
+ [simpleperf](https://android.googlesource.com/platform/system/extras/+/refs/heads/main/simpleperf/doc/README.md)
10
+ records the same layout, with extra feature sections of its own.
11
+
12
+ A header names the recorded events and how they were sampled, a data section
13
+ holds the records the kernel produced (samples carrying an instruction pointer,
14
+ a call chain, a thread, and how many event units the sample stands for, plus the
15
+ memory mappings each process made), and feature sections hold the metadata
16
+ `perf` collected about the machine.
17
+
18
+ Each recorded event becomes its own profile, measured in the units its period
19
+ counts: nanoseconds for the `cpu-clock` and `task-clock` software events, and
20
+ the counted event otherwise (cycles, instructions, page faults).
21
+
22
+ It supports a single metric per profile and multiple profiles per file.
23
+
24
+ Files use the `perf.data` name and extension, optionally gzipped as
25
+ `perf.data.gz`.
26
+
27
+ ## Addresses instead of function names
28
+
29
+ A `perf.data` file holds no symbol tables. `perf report` reads the recorded
30
+ program and its shared libraries off the machine that recorded them, so a file
31
+ alone resolves an address no further than the mapped file it fell in. Every
32
+ frame is therefore one address, named by its offset into that file and located
33
+ at the file's path, the same form `perf script` prints for a frame it cannot
34
+ symbolize. An address in memory a program obtained without a file (an `//anon`
35
+ mapping) is located at that name and categorized as JIT code.
36
+
37
+ Resolve an offset against the same build with `addr2line`:
38
+
39
+ ```sh
40
+ addr2line -fCe ./program 0x5f800
41
+ ```
42
+
43
+ The offset is file-relative rather than the address the code ran at, so it is
44
+ the same across runs of the same build, and a diff of two recordings pairs the
45
+ addresses that moved. A kernel frame's offset is from the start of the kernel's
46
+ text (`_text`), which the kernel randomizes on every boot, so it too pairs
47
+ across boots. Resolve one against the matching `vmlinux` by adding the address
48
+ of `_text` from its `System.map`, or from `/proc/kallsyms` on the recording
49
+ machine.
50
+
51
+ For function names in the output, symbolize while converting instead: pipe
52
+ `perf script` through FlameGraph's `stackcollapse-perf.pl` and pass the
53
+ collapsed stacks, which this tool also reads.
54
+
55
+ ```sh
56
+ perf script -i perf.data | stackcollapse-perf.pl > profile.collapsed
57
+ ```
58
+
59
+ ## Recordings this tool reads
60
+
61
+ Record with `perf record -g`, which `profiler-md --help c` and
62
+ `profiler-md --help zig` cover. This tool reads only the call chains the kernel
63
+ walked, so it rejects a file recorded with `--call-graph dwarf`. That option
64
+ leaves the chain holding one user-space frame and copies the rest of the stack
65
+ into every sample for `perf report` to unwind. This tool also leaves
66
+ `--call-graph lbr` branch histories unread. simpleperf's `record -g` unwinds
67
+ that copy while recording and writes the frames into the chain, so this tool
68
+ reads its files. On arm64, `perf report` adds one caller below the innermost
69
+ frame by unwinding the sampled link register, so a stack there can name a caller
70
+ this tool leaves out.
71
+
72
+ It also rejects, with the reason, a file recorded with `perf record -z`
73
+ (compressed), streamed to a pipe (`perf record -o -`), or written on a machine
74
+ of the opposite byte order.
@@ -8,7 +8,9 @@ profiling format.
8
8
  Locations support inlined call frames, meaning a single instruction address can
9
9
  correspond to multiple logical stack frames.
10
10
 
11
- It supports arbitrary metric units, multiple metrics per profile, and a single
12
- profile per file.
11
+ It supports arbitrary metric units, multiple metrics per profile, and multiple
12
+ profiles per file. A file containing several counts (a heap profile's
13
+ `alloc_objects` and `inuse_objects`) becomes one profile per count, each
14
+ reporting the metrics measured over it.
13
15
 
14
16
  Files are commonly gzip-compressed (extension `.pb.gz`).
@@ -6,7 +6,8 @@ Speedscope is a JSON profiling format used by
6
6
  Each profile within a file has a type: `sampled` (call stacks at points in time)
7
7
  or `evented` (frame open/close timestamps).
8
8
 
9
- It supports arbitrary metric units, a single metric per profile, and multiple
10
- profiles per file.
9
+ It supports one metric per profile, measured in one of six units (nanoseconds,
10
+ microseconds, milliseconds, seconds, bytes, or none), and multiple profiles per
11
+ file.
11
12
 
12
13
  Files use the `.speedscope.json` extension.
@@ -1,25 +1,27 @@
1
1
  # systing profile export
2
2
 
3
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.
4
+ [systing](https://github.com/josefbacik/systing), a Linux eBPF system profiler,
5
+ specified by its
6
+ [`docs/PROFILE_EXPORT_FORMAT.md`](https://github.com/josefbacik/systing/blob/main/docs/PROFILE_EXPORT_FORMAT.md).
7
+ `systing-util convert trace.duckdb --output profile.systing` writes one from an
8
+ existing trace database.
9
+
10
+ An export opens with a JSON header line describing the recording (sampling event
11
+ and period, event-type legend, system info), followed by one JSON array per
12
+ record: interned frames, interned leaf-first stacks, and per-thread sample
13
+ counts. Frames mix kernel, native user, and Python code, marked by systing's own
14
+ labels (`[kernel]`, `[gvisor:*]`, `[jit:*]`). The labels determine
15
+ categorization.
10
16
 
11
17
  A recording samples on-CPU execution and takes a stack each time a thread
12
18
  sleeps, so it converts to up to three profiles: CPU (measured in time for
13
19
  `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
+ interruptible sleep (both measured in sleep occurrences). Sleep stacks are taken
21
+ at the context switch, so they always end in the kernel's scheduler internals:
22
+ self costs fall on scheduler frames, and the total costs show which callers
23
+ slept.
20
24
 
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`.
25
+ It supports a single metric per profile and multiple profiles per file.
24
26
 
25
27
  Files use the `.systing` extension, optionally gzipped as `.systing.gz`.
@@ -3,9 +3,10 @@
3
3
  The V8 CPU profile is a JSON format produced by the
4
4
  [V8 JavaScript engine's sampling profiler](https://v8.dev/docs/profile).
5
5
 
6
- It stores both a call tree (nodes) and a sequence of timed samples. The call
7
- tree enables accurate self-time attribution even from a sparse sample stream,
8
- unlike formats that store only raw stacks.
6
+ It stores a call tree (nodes) and the sequence of samples taken from it, each
7
+ sample with the microseconds elapsed since the one before it. A profile
8
+ therefore states how long every sample stood for, rather than leaving its reader
9
+ to derive that from a nominal sampling rate.
9
10
 
10
11
  It supports a single microsecond metric per profile and a single profile per
11
12
  file.
@@ -1,12 +1,15 @@
1
1
  # V8 heap profile
2
2
 
3
3
  The V8 heap profile is a JSON format produced by
4
- [V8's sampling heap profiler](https://v8.dev/docs/profile). It is generated by
5
- Node.js and Chrome DevTools.
4
+ [V8's sampling heap profiler](https://v8.dev/docs/profile). Node.js and Chrome
5
+ DevTools generate it.
6
6
 
7
- Unlike heap snapshots, which capture all live objects at a point in time, heap
8
- profiles sample allocations. This makes them useful for finding allocation
9
- hotspots rather than diagnosing what is currently live in memory.
7
+ It stores an allocation call tree whose nodes each state the bytes allocated at
8
+ that call site, and a sequence of samples referencing those nodes.
9
+
10
+ Heap profiles sample allocations, unlike heap snapshots, which capture all live
11
+ objects at a point in time. That makes them useful for finding allocation
12
+ hotspots rather than diagnosing what is live in memory.
10
13
 
11
14
  It supports a single byte metric per profile and a single profile per file.
12
15
 
@@ -3,8 +3,13 @@
3
3
  The V8 heap snapshot is a JSON format produced by the V8 JavaScript engine's
4
4
  heap profiler that captures the full live object graph at a point in time.
5
5
 
6
- Unlike heap profiles, which sample allocations, snapshots show what objects
7
- currently exist in memory. This is useful for diagnosing memory leaks rather
8
- than allocation hotspots.
6
+ A snapshot is a `meta` object declaring the layout of the records that follow,
7
+ flat integer arrays of node and edge records, a strings table the node and edge
8
+ names index into, and a flat array of the source locations of the functions and
9
+ objects the nodes stand for.
10
+
11
+ Snapshots show what objects exist in memory, unlike heap profiles, which sample
12
+ allocations. That makes them useful for diagnosing memory leaks rather than
13
+ allocation hotspots.
9
14
 
10
15
  Files use the `.heapsnapshot` extension.
@@ -6,4 +6,10 @@ from sampling, a browser activity breakdown (layout, rendering, script
6
6
  execution, network requests), and optionally in-use memory readings and heap
7
7
  allocation snapshots when those instruments are enabled.
8
8
 
9
+ The recording holds the sampled call stacks alongside the duration each sample
10
+ spans, so it converts to the time profile they record. This tool leaves the
11
+ activity breakdown and the memory readings unread.
12
+
13
+ It supports a single second metric per profile and a single profile per file.
14
+
9
15
  Files use the `.json` extension.