profiler-md 0.5.0 → 0.7.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 (235) hide show
  1. package/dist/cli/index.mjs +14155 -5081
  2. package/dist/index.d.mts +1312 -263
  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 +3 -3
  11. package/docs/formats/jsc-heap-snapshot.md +11 -5
  12. package/docs/formats/memray.md +30 -0
  13. package/docs/formats/perf.md +74 -0
  14. package/docs/formats/pprof.md +10 -6
  15. package/docs/formats/speedscope.md +7 -5
  16. package/docs/formats/systing.md +27 -0
  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 +10 -5
  20. package/docs/formats/webkit-timeline-recording.md +6 -0
  21. package/docs/languages/c.md +138 -18
  22. package/docs/languages/csharp.md +7 -7
  23. package/docs/languages/elixir.md +22 -15
  24. package/docs/languages/fortran.md +141 -0
  25. package/docs/languages/go.md +36 -13
  26. package/docs/languages/haskell.md +134 -0
  27. package/docs/languages/java.md +89 -34
  28. package/docs/languages/javascript.md +37 -31
  29. package/docs/languages/julia.md +96 -14
  30. package/docs/languages/php.md +10 -4
  31. package/docs/languages/python.md +121 -15
  32. package/docs/languages/ruby.md +19 -22
  33. package/docs/languages/rust.md +40 -10
  34. package/docs/languages/swift.md +135 -0
  35. package/docs/languages/zig.md +155 -0
  36. package/package.json +47 -46
  37. package/readme.md +306 -242
  38. package/skills/profile-optimize/SKILL.md +162 -0
  39. package/docs/languages/cpp.md +0 -160
  40. package/docs/languages/erlang.md +0 -46
  41. package/docs/languages/fsharp.md +0 -52
  42. package/docs/languages/kotlin.md +0 -170
  43. package/docs/languages/typescript.md +0 -276
  44. package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
  45. package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
  46. package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
  47. package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
  48. package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
  49. package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
  50. package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
  51. package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
  52. package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
  53. package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
  54. package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
  55. package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
  56. package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
  57. package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
  58. package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
  59. package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
  60. package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
  61. package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
  62. package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
  63. package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
  64. package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
  65. package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
  66. package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
  67. package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
  68. package/examples/output/go.pprof.block.base.pprof.md +0 -86
  69. package/examples/output/go.pprof.block.current.pprof.md +0 -83
  70. package/examples/output/go.pprof.block.diff.pprof.md +0 -42
  71. package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
  72. package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
  73. package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
  74. package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
  75. package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
  76. package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
  77. package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
  78. package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
  79. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
  80. package/examples/output/go.pprof.heap.base.pprof.md +0 -154
  81. package/examples/output/go.pprof.heap.current.pprof.md +0 -146
  82. package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
  83. package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
  84. package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
  85. package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
  86. package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
  87. package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
  88. package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
  89. package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
  90. package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
  91. package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
  92. package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
  93. package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
  94. package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
  95. package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
  96. package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
  97. package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
  98. package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
  99. package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
  100. package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
  101. package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
  102. package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
  103. package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
  104. package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
  105. package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
  106. package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
  107. package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
  108. package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
  109. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
  110. package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
  111. package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
  112. package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
  113. package/examples/output/java.jdk.all.base.jfr.md +0 -1024
  114. package/examples/output/java.jdk.all.current.jfr.md +0 -1010
  115. package/examples/output/java.jdk.all.diff.jfr.md +0 -311
  116. package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
  117. package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
  118. package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
  119. package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
  120. package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
  121. package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
  122. package/examples/output/java.jdk.live.base.jfr.md +0 -1029
  123. package/examples/output/java.jdk.live.current.jfr.md +0 -1035
  124. package/examples/output/java.jdk.live.diff.jfr.md +0 -289
  125. package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
  126. package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
  127. package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
  128. package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
  129. package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
  130. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
  131. package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
  132. package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
  133. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
  134. package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
  135. package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
  136. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
  137. package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
  138. package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
  139. package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
  140. package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
  141. package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
  142. package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
  143. package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
  144. package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
  145. package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
  146. package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
  147. package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
  148. package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
  149. package/examples/output/javascript.node.base.cpuprofile.md +0 -136
  150. package/examples/output/javascript.node.base.heapprofile.md +0 -56
  151. package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
  152. package/examples/output/javascript.node.current.cpuprofile.md +0 -119
  153. package/examples/output/javascript.node.current.heapprofile.md +0 -52
  154. package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
  155. package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
  156. package/examples/output/javascript.node.diff.heapprofile.md +0 -34
  157. package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
  158. package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
  159. package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
  160. package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
  161. package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
  162. package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
  163. package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
  164. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
  165. package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
  166. package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
  167. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
  168. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
  169. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
  170. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
  171. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
  172. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
  173. package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
  174. package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
  175. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
  176. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
  177. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
  178. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
  179. package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
  180. package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
  181. package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
  182. package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
  183. package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
  184. package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
  185. package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
  186. package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
  187. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
  188. package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
  189. package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
  190. package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
  191. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
  192. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
  193. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
  194. package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
  195. package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
  196. package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
  197. package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
  198. package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
  199. package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
  200. package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
  201. package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
  202. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
  203. package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
  204. package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
  205. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
  206. package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
  207. package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
  208. package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
  209. package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
  210. package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
  211. package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
  212. package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
  213. package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
  214. package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
  215. package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
  216. package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
  217. package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
  218. package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
  219. package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
  220. package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
  221. package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
  222. package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
  223. package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
  224. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
  225. package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
  226. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
  227. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
  228. package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
  229. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
  230. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
  231. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
  232. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
  233. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
  234. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
  235. 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,9 +8,9 @@ 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
- It supports one metric per profile and multiple profiles per file.
14
+ It supports a single metric per profile and multiple profiles per file.
15
15
 
16
16
  Files use the `.jfr` extension.
@@ -2,12 +2,18 @@
2
2
 
3
3
  The
4
4
  [JSC heap snapshot](https://webkit.org/blog/6425/memory-debugging-with-web-inspector)
5
- is a JSON format produced by JavaScriptCore, the engine powering Safari and
5
+ is a JSON format produced by JavaScriptCore, the JavaScript engine of Safari and
6
6
  WebKit, that captures the full live object graph at a point in time.
7
7
 
8
- 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.
@@ -1,12 +1,16 @@
1
1
  # pprof
2
2
 
3
3
  [pprof](https://github.com/google/pprof) is a binary
4
- ([protobuf](https://github.com/protocolbuffers/protobuf)) sampled-based
5
- profiling format originally from Google. It is the de facto standard
6
- cross-language profiling format.
4
+ ([protobuf](https://github.com/protocolbuffers/protobuf)) sample-based profiling
5
+ format originally from Google. It is the de facto standard cross-language
6
+ profiling format.
7
7
 
8
- It supports arbitrary metric units, multiple metrics in a single profile, and a
9
- single profile per file. Locations support inlined call frames, meaning a single
10
- instruction address can correspond to multiple logical stack frames.
8
+ Locations support inlined call frames, meaning a single instruction address can
9
+ correspond to multiple logical stack frames.
10
+
11
+ It supports arbitrary metric units, multiple metrics per profile, and 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.
11
15
 
12
16
  Files are commonly gzip-compressed (extension `.pb.gz`).
@@ -1,11 +1,13 @@
1
1
  # Speedscope
2
2
 
3
3
  Speedscope is a JSON profiling format used by
4
- [speedscope.app](https://www.speedscope.app), a flame graph visualizer. Each
5
- profile within a file has a type: `sampled` (call stacks at points in time) or
6
- `evented` (frame open/close timestamps).
4
+ [speedscope.app](https://www.speedscope.app), a flame graph visualizer.
7
5
 
8
- It supports arbitrary metric units, a single metric per profile, and multiple
9
- profiles in a single file.
6
+ Each profile within a file has a type: `sampled` (call stacks at points in time)
7
+ or `evented` (frame open/close timestamps).
8
+
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.
10
12
 
11
13
  Files use the `.speedscope.json` extension.
@@ -0,0 +1,27 @@
1
+ # systing profile export
2
+
3
+ The line-oriented profile export written by
4
+ [systing](https://github.com/josefbacik/systing), a Linux eBPF system profiler,
5
+ 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.
16
+
17
+ A recording samples on-CPU execution and takes a stack each time a thread
18
+ sleeps, so it converts to up to three profiles: CPU (measured in time for
19
+ `cpu-clock` sampling, cycles for `cpu-cycles`), uninterruptible sleep, and
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.
24
+
25
+ It supports a single metric per profile and multiple profiles per file.
26
+
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
 
@@ -1,10 +1,15 @@
1
1
  # V8 heap snapshot
2
2
 
3
- The V8 heap snapshot is a JSON format that captures the full live object graph
4
- at a point in time.
3
+ The V8 heap snapshot is a JSON format produced by the V8 JavaScript engine's
4
+ heap profiler that captures the full live object graph at a point in time.
5
5
 
6
- 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.