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
@@ -0,0 +1,162 @@
1
+ ---
2
+ name: profile-optimize
3
+ description: |
4
+ Generate a performance profile, identify hotspots, and optimize.
5
+ argument-hint: '[what to focus on]'
6
+ allowed-tools: Bash(profiler-md *)
7
+ ---
8
+
9
+ Generate a performance profile, identify hotspots, and optimize.
10
+
11
+ Focus: $ARGUMENTS
12
+
13
+ # Workflow
14
+
15
+ 1. Decide what to profile (time or memory) and write an isolated script that
16
+ exercises the slow path if nothing runs it directly. Run
17
+ `profiler-md --help <language>` for profiling instructions
18
+ 2. Capture a baseline: generate a profile, convert it with
19
+ `profiler-md path/to/profile`, and read the full report, focusing on:
20
+ - Hottest functions: self % shows where time is spent or memory is allocated,
21
+ not just passed through
22
+ - Hottest call stacks: the call path to the hot functions, with `…` for
23
+ frames the entry filter hides
24
+ 3. Identify the hottest 1-3 functions by self % and read their source:
25
+ - Native functions are often unavoidable but may indicate unnecessary work
26
+ (e.g. parsing the same data twice, creating many intermediate arrays)
27
+ - Project functions are direct targets
28
+ 4. State a hypothesis (see "Hypotheses"). If the bottleneck is unclear, reread
29
+ the hot function and its callers
30
+ 5. Apply the minimal change that addresses the bottleneck, one optimization at a
31
+ time. Leave unrelated code alone. Optimize the general case, not the
32
+ benchmark: don't exploit quirks of the profiled input (its size, ordering,
33
+ value distribution, or hardcoded special cases for it) unless they're
34
+ guaranteed properties of real inputs
35
+ 6. Run the relevant tests: if any newly fail, fix the optimization or revert it
36
+ 7. Capture a new report as in step 2 and compare self % for the targeted
37
+ function(s) against the baseline: if the improvement is negligible or
38
+ unclear, revert and go back to step 4 instead of iterating blindly. If the
39
+ comparison is too noisy to call, collect more samples (see "Measurement");
40
+ don't fall back to manual timing
41
+ 8. If the goal is unmet and a clear bottleneck remains, repeat from step 3 with
42
+ the new profile as the baseline
43
+ 9. Report:
44
+ - Before vs after for the hot function(s)
45
+ - Any other functions that moved significantly (regressions)
46
+
47
+ # Measurement
48
+
49
+ profiler-md reports are the ONLY measurements in this workflow. NEVER time
50
+ manually (e.g. `time` or `performance.now()`).
51
+
52
+ Manual timing yields one noisy end-to-end number that can improve for reasons
53
+ unrelated to the change (machine load, caches, GC timing), and its
54
+ instrumentation distorts the hot path. A profile attributes work to functions,
55
+ so a before/after comparison proves the optimization removed the targeted work,
56
+ not merely that one run was faster.
57
+
58
+ If a profile has too few samples to trust, collect more:
59
+
60
+ - Run the workload longer or loop it more times
61
+ - Raise the sampling frequency if the profiler supports it (see
62
+ `profiler-md --help <language>`)
63
+ - Regenerate the profile and compare again
64
+
65
+ # Hypotheses
66
+
67
+ Before changing anything, state:
68
+
69
+ - What is the bottleneck? (e.g. "repeated object allocation in the hot loop",
70
+ "O(n²) suffix scan", "redundant map lookups")
71
+ - What is the expected fix? (e.g. "hoist allocation outside loop", "use a
72
+ two-pointer suffix scan", "cache the lookup result")
73
+ - Why will it be faster?
74
+
75
+ # Focus areas
76
+
77
+ Sub-bullets are examples, not exhaustive lists.
78
+
79
+ - Time complexity: reduce the asymptotic work per input element
80
+ - Replace `O(n²)` scans with single-pass or two-pointer algorithms
81
+ - Use heaps for top-N instead of fully sorting
82
+ - Sort once and binary search instead of repeated linear scans
83
+ - Redundant work: compute each result once
84
+ - Avoid parsing or computing the same data twice; cache or memoize repeated
85
+ lookups
86
+ - Hoist loop-invariant computation out of loops
87
+ - Build lookup tables once instead of searching repeatedly; intern repeated
88
+ values
89
+ - Update incrementally instead of recomputing from scratch
90
+ - Persist expensive results between invocations, keyed by input so stale
91
+ entries are never served
92
+ - Work avoidance: skip or defer computation whose result may never be used
93
+ - Exit early once the answer is known
94
+ - Filter before expensive transforms, not after
95
+ - Order checks cheapest-first so expensive predicates run last and rarely
96
+ - Add fast paths for the common input shape
97
+ - Defer initialization and large dependency loading until first use,
98
+ especially on the startup critical path
99
+ - Debounce or throttle work triggered by bursty events
100
+ - Data structure selection: match the structure to the access pattern
101
+ - Use sets/maps for membership and lookup instead of linear scans
102
+ - Use bitsets for dense boolean membership
103
+ - Use a ring buffer for FIFO access instead of shifting an array
104
+ - Cache locality: lay out data so hot loops read memory sequentially
105
+ - Compressed sparse row (CSR) format
106
+ - Data-oriented design (struct-of-arrays, packed primitive arrays)
107
+ - Sparse arrays indexed by sequential IDs instead of integer-keyed hash maps
108
+ - Iterate in storage order (e.g. row-major for nested arrays)
109
+ - Allocation and copying: allocate and copy less in hot paths
110
+ - Hoist allocations out of hot loops; reuse buffers instead of reallocating
111
+ - Preallocate arrays and buffers to their known final size instead of growing
112
+ incrementally
113
+ - Avoid intermediate collections from chained transforms; fuse them into one
114
+ pass
115
+ - Use views/slices over underlying data instead of copying; defer cloning
116
+ until mutation is needed
117
+ - Memory footprint: hold and retain only what the computation needs
118
+ - Stream or process incrementally instead of materializing intermediates
119
+ - Bound caches (e.g. LRU); use weak references for object-keyed caches
120
+ - Remove listeners, timers, and subscriptions when done
121
+ - Avoid closures capturing large outer scopes; drop references held by
122
+ long-lived structures once no longer needed
123
+ - String handling: minimize the strings created and scanned in hot paths
124
+ - Avoid repeated concatenation in loops
125
+ - Work with indices or char codes into the original string instead of creating
126
+ substrings
127
+ - Minimize serialization/deserialization round-trips
128
+ - Avoid regex in hot paths
129
+ - Runtime friendliness: stay on the JIT's optimized fast paths
130
+ - Keep object shapes consistent (same fields, same initialization order)
131
+ - Avoid polymorphic call sites and mixed-type arrays in hot paths
132
+ - Keep numbers in the runtime's fast representations; avoid deoptimization
133
+ triggers in hot loops
134
+ - I/O and queries: make fewer round-trips and move fewer bytes
135
+ - Read or write in large chunks instead of many small operations
136
+ - Eliminate N+1 patterns by coalescing small queries or requests into one
137
+ batch
138
+ - Push filtering, aggregation, and pagination down to the data store; add
139
+ indexes matching the hot query's predicates
140
+ - Compress or use binary encodings for large transfers; send only the fields
141
+ the consumer reads
142
+ - Concurrency: use idle hardware for independent work
143
+ - Run independent async operations concurrently, bounded to what the awaited
144
+ resource can absorb
145
+ - Overlap I/O waits with computation instead of strictly sequencing them
146
+ - Split CPU-bound work across threads or processes; use SIMD where the
147
+ platform supports it
148
+ - Contention and backpressure: keep concurrent parts from waiting on or
149
+ overwhelming each other
150
+ - Minimize time spent holding locks; shrink critical sections
151
+ - Shard or partition shared state; prefer immutable or thread-local data over
152
+ shared mutable state
153
+ - Bound queues so producers can't outrun consumers; shed or coalesce load when
154
+ the system is saturated
155
+ - Precision trade-offs: do cheaper work that's good enough, only when the
156
+ consumer tolerates the difference
157
+ - Use approximate algorithms (sampling, sketches, bloom filters)
158
+ - Lower resolution or cap iteration counts when the output tolerance allows
159
+ - Observability overhead: keep instrumentation cheap enough that it doesn't
160
+ distort the hot path
161
+ - Keep logging, tracing, and assertions out of hot loops
162
+ - Sample or gate expensive instrumentation behind flags
@@ -1,160 +0,0 @@
1
- # C/C++
2
-
3
- C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools).
4
-
5
- ## CPU profiling
6
-
7
- Periodically samples the call stack. Useful for finding CPU hot spots.
8
-
9
- Link with `-lprofiler`:
10
-
11
- ```sh
12
- gcc -O2 -Wl,--no-as-needed -lprofiler -o program program.c # C
13
- g++ -O2 -Wl,--no-as-needed -lprofiler -o program program.cpp # C++
14
- ```
15
-
16
- ### CLI
17
-
18
- ```sh
19
- # Generate a CPU profile
20
- CPUPROFILE=cpu.prof ./program
21
-
22
- # Convert to pprof protobuf format
23
- pprof --proto ./program cpu.prof > cpu.pprof
24
- ```
25
-
26
- #### Environment variables
27
-
28
- | Variable | Default | Description |
29
- | ---------------------- | ------- | -------------------------------------------------------------------------------- |
30
- | `CPUPROFILE` | — | Output filename; profiling is enabled when set |
31
- | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
32
- | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
33
- | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
34
-
35
- ### Programmatic API
36
-
37
- ```c
38
- #include <gperftools/profiler.h>
39
-
40
- ProfilerStart("cpu.prof");
41
-
42
- // Code to profile...
43
-
44
- ProfilerFlush(); // optional: flush buffered samples mid-run
45
- ProfilerStop();
46
- ```
47
-
48
- ## Memory profiling
49
-
50
- Periodically dumps the live heap, capturing allocation stack traces. Useful for
51
- finding memory leaks and allocation hot spots.
52
-
53
- Link with `-ltcmalloc`:
54
-
55
- ```sh
56
- gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
57
- g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
58
- ```
59
-
60
- ### CLI
61
-
62
- ```sh
63
- # Generate heap profiles (written as <prefix>.0000.heap, .0001.heap, …)
64
- HEAPPROFILE=heap.prof ./program
65
-
66
- # Convert a heap profile to pprof protobuf format
67
- pprof --proto ./program heap.prof.0001.heap > heap.pprof
68
- ```
69
-
70
- #### Environment variables
71
-
72
- | Variable | Default | Description |
73
- | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
74
- | `HEAPPROFILE` | — | Output filename prefix; heap profiling is enabled when set |
75
- | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
76
- | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
77
- | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
78
- | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
79
- | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
80
- | `HEAP_PROFILE_ONLY_MMAP` | `false` | Profile only `mmap`/`mremap`/`sbrk`; skip `malloc`/`new` |
81
-
82
- ### Programmatic API
83
-
84
- ```c
85
- #include <gperftools/heap-profiler.h>
86
-
87
- HeapProfilerStart("heap.prof");
88
-
89
- // Code to profile...
90
-
91
- HeapProfilerDump("checkpoint"); // optional mid-run profile dump
92
- HeapProfilerStop();
93
- ```
94
-
95
- ## Heap checking
96
-
97
- Compares the heap state before and after a region of code to detect memory
98
- leaks. Useful for confirming a code path frees everything it allocates.
99
-
100
- Link with `-ltcmalloc`:
101
-
102
- ```sh
103
- gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
104
- g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
105
- ```
106
-
107
- ### CLI
108
-
109
- ```sh
110
- # Report leaks at program exit
111
- HEAPCHECK=normal ./program
112
-
113
- # Also report still-reachable allocations at exit
114
- HEAPCHECK=strict ./program
115
-
116
- # Most aggressive: report all live allocations at exit
117
- HEAPCHECK=draconian ./program
118
- ```
119
-
120
- #### Environment variables
121
-
122
- | Variable | Default | Description |
123
- | ----------- | ------- | ------------------------------------------------------------------------------------ |
124
- | `HEAPCHECK` | — | Leak-checking mode (`minimal`, `normal`, `strict`, or `draconian`); enabled when set |
125
-
126
- ### Programmatic API
127
-
128
- ```c
129
- #include <gperftools/heap-checker.h>
130
-
131
- HeapLeakChecker checker("my_check");
132
-
133
- // Code to check...
134
-
135
- if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
136
- ```
137
-
138
- ## Tips
139
-
140
- ### Symbols
141
-
142
- gperftools symbolizes addresses from the binary's and its shared libraries'
143
- symbol tables, so build and link what you profile with symbols (`-g`, not
144
- stripped). If the hot code lives in a stripped shared library, statically link
145
- an unstripped build instead.
146
-
147
- ### Linking
148
-
149
- Modern toolchains link with `--as-needed` by default, which drops
150
- `-lprofiler`/`-ltcmalloc` when your program references no symbol from them,
151
- exactly the case when you enable profiling through the environment variables
152
- instead of the programmatic API. Force the link with `-Wl,--no-as-needed`, or
153
- preload the library at runtime with `LD_PRELOAD`. The programmatic API
154
- (`ProfilerStart`, etc.) references the symbols, so plain
155
- `-lprofiler`/`-ltcmalloc` works there.
156
-
157
- ### Converting
158
-
159
- `pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
160
- `pprof`/`google-pprof` has no protobuf output.
@@ -1,46 +0,0 @@
1
- # Elixir/Erlang
2
-
3
- Elixir and Erlang profiling uses
4
- [eflambe](https://github.com/Stratus3D/eflambe), a BEAM profiler that wraps the
5
- runtime's built-in tracing and writes flame graph output.
6
-
7
- ## CPU profiling
8
-
9
- Traces function calls and writes them as collapsed stacks. Useful for finding
10
- CPU hot spots.
11
-
12
- eflambe's default `brendan_gregg` format is collapsed stacks. Add `eflambe` to
13
- your dependencies, then profile a specific function.
14
-
15
- **Keep the call small.** eflambe traces _every_ function call. It doesn't
16
- sample, so output grows with the number of calls. A single invocation over a
17
- large input can produce hundreds of MB.
18
-
19
- ### Elixir
20
-
21
- ```elixir
22
- # Profile a function as it runs during normal execution (capture 1 call)
23
- :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
24
-
25
- # Directly invoke and profile a function
26
- :eflambe.apply({MyModule, :my_function, [arg1, arg2]}, output_format: :brendan_gregg)
27
- ```
28
-
29
- ### Erlang
30
-
31
- ```erlang
32
- %% Profile a function as it runs during normal execution (capture 1 call)
33
- eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
34
-
35
- %% Directly invoke and profile a function
36
- eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_gregg}]).
37
- ```
38
-
39
- ### Options
40
-
41
- | Option | Default | Description |
42
- | ------------------ | --------------- | --------------------------------------------------- |
43
- | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
44
- | `output_directory` | project root | Directory to write the output file to |
45
- | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
46
- | `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
@@ -1,52 +0,0 @@
1
- # C#/F#
2
-
3
- .NET profiling (C#, F#, and other CLR languages) uses
4
- [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace),
5
- a cross-platform diagnostics tool that collects traces through the runtime's
6
- EventPipe without a native profiler.
7
-
8
- Install it as a global tool:
9
-
10
- ```sh
11
- dotnet tool install --global dotnet-trace
12
- ```
13
-
14
- The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
15
- install a compatible version with `--version`.
16
-
17
- ## CPU profiling
18
-
19
- Periodically samples the call stack. Useful for finding CPU hot spots.
20
-
21
- With no `--profile` or `--providers`, `dotnet-trace collect` enables the
22
- `dotnet-common` and `dotnet-sampled-thread-time` profiles, sampling thread
23
- stacks at roughly 100 Hz.
24
-
25
- ### CLI
26
-
27
- ```sh
28
- # Attach to a running process, written directly as speedscope
29
- dotnet-trace collect --process-id <pid> --format speedscope
30
-
31
- # Launch and trace a command from startup (use `dotnet exec` so the dotnet CLI's
32
- # own child processes aren't traced instead of your app)
33
- dotnet-trace collect --format speedscope -- dotnet exec app.dll
34
-
35
- # Attach for a fixed duration (dd:hh:mm:ss)
36
- dotnet-trace collect --process-id <pid> --duration 00:00:00:30 --format speedscope
37
-
38
- # Convert an existing .nettrace to speedscope
39
- dotnet-trace convert trace.nettrace --format speedscope
40
- ```
41
-
42
- #### Flags
43
-
44
- | Flag | Default | Description |
45
- | --------------------- | ---------- | --------------------------------------------------- |
46
- | `-p` / `--process-id` | — | PID of the process to trace |
47
- | `-n` / `--name` | — | Name of the process to trace |
48
- | `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
49
- | `-o` / `--output` | `nettrace` | Output file path |
50
- | `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
51
- | `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
52
- | `--providers` | — | Comma-separated EventPipe providers to enable |
@@ -1,170 +0,0 @@
1
- # Java/Kotlin
2
-
3
- Java and Kotlin profiling works with any JVM language, using either
4
- [Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) (JFR),
5
- built into the JDK since JDK 11, or
6
- [async-profiler](https://github.com/async-profiler/async-profiler), a low
7
- overhead sampling profiler that additionally resolves native frames and works on
8
- older JDKs.
9
-
10
- ## CPU profiling
11
-
12
- Periodically samples the call stack while on CPU. Useful for finding CPU hot
13
- spots. Recorded as `jdk.ExecutionSample` events.
14
-
15
- ### Java Flight Recorder
16
-
17
- ```sh
18
- java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms -jar app.jar
19
- jfr summary cpu.jfr
20
- ```
21
-
22
- ### async-profiler
23
-
24
- #### CLI
25
-
26
- ```sh
27
- # Attach to a running JVM (JFR is the default output format)
28
- asprof -e cpu -d 30 -f cpu.jfr <pid>
29
-
30
- # Or write collapsed stacks
31
- asprof -e cpu -d 30 -o collapsed -f cpu.collapsed <pid>
32
- ```
33
-
34
- #### Programmatic API
35
-
36
- Add `async-profiler` to your dependencies, then control it in-process. The
37
- output format follows the file extension (`.jfr` or `.collapsed`), and `event`
38
- selects the metric:
39
-
40
- ```java
41
- import one.profiler.AsyncProfiler;
42
-
43
- AsyncProfiler profiler = AsyncProfiler.getInstance();
44
- profiler.execute("start,event=cpu,file=cpu.jfr");
45
-
46
- // Code to profile...
47
-
48
- profiler.execute("stop");
49
- ```
50
-
51
- ## Wall-clock profiling
52
-
53
- Samples wall-clock time rather than CPU time, including time threads spend
54
- waiting. Useful for I/O-bound or latency-sensitive code.
55
-
56
- ### Java Flight Recorder
57
-
58
- JFR has no wall-clock sampler, so this metric is async-profiler only. (JFR does
59
- record specific waiting events, such as `jdk.ThreadPark` and
60
- `jdk.JavaMonitorWait`, via the lock recipe below.)
61
-
62
- ### async-profiler
63
-
64
- ```sh
65
- asprof -e wall -d 30 -f wall.jfr <pid>
66
- ```
67
-
68
- Recorded as `profiler.WallClockSample` events. `cpu` and `wall` share the same
69
- sampling timer, so async-profiler records one or the other within a single
70
- recording, not both.
71
-
72
- ## Memory profiling
73
-
74
- Samples memory allocations, in allocated bytes. async-profiler offers three
75
- variants; JFR offers two:
76
-
77
- - **heap allocations**: every heap allocation sampled since profiling started;
78
- useful for finding allocation hot spots and reducing GC pressure
79
- - **live heap**: only allocations whose objects are still live at the end;
80
- useful for finding leaks
81
- - **native memory**: off-heap `malloc`/`free`; useful for finding native leaks
82
- (async-profiler only)
83
-
84
- ### Java Flight Recorder
85
-
86
- ```sh
87
- # Heap allocation hot spots (jdk.ObjectAllocationSample, JDK 16+)
88
- java -XX:StartFlightRecording=filename=alloc.jfr,settings=none,+jdk.ObjectAllocationSample#enabled=true,+jdk.ObjectAllocationSample#throttle=150/s -jar app.jar
89
-
90
- # Live objects, for leak finding (jdk.OldObjectSample)
91
- java -XX:StartFlightRecording=filename=live.jfr,settings=none,+jdk.OldObjectSample#enabled=true,+jdk.OldObjectSample#stackTrace=true -jar app.jar
92
- ```
93
-
94
- JFR's native memory tracking (`-XX:NativeMemoryTracking`) reports usage by
95
- category rather than call-stack-attributed allocations, so native allocation
96
- profiling is async-profiler only.
97
-
98
- ### async-profiler
99
-
100
- ```sh
101
- # Heap allocation hot spots (jdk.ObjectAllocationInNewTLAB/OutsideTLAB)
102
- asprof -e alloc -d 30 -f alloc.jfr <pid>
103
-
104
- # Live objects only, for leak finding (profiler.LiveObject)
105
- asprof -e alloc --live -d 30 -f live.jfr <pid>
106
-
107
- # Off-heap native memory (profiler.Malloc/Free); --nofree skips free events
108
- asprof -e nativemem -d 30 -f native.jfr <pid>
109
- ```
110
-
111
- `--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
112
- heap and native variants.
113
-
114
- ## Lock profiling
115
-
116
- Samples contended monitor and `java.util.concurrent` locks. Useful for finding
117
- lock contention hot spots. The sampled values are nanoseconds spent blocked.
118
- Recorded as `jdk.JavaMonitorEnter` and `jdk.ThreadPark` events.
119
-
120
- ### Java Flight Recorder
121
-
122
- ```sh
123
- java -XX:StartFlightRecording=filename=lock.jfr,settings=none,+jdk.JavaMonitorEnter#enabled=true,+jdk.JavaMonitorEnter#threshold=10ms,+jdk.ThreadPark#enabled=true,+jdk.ThreadPark#threshold=10ms -jar app.jar
124
- ```
125
-
126
- ### async-profiler
127
-
128
- ```sh
129
- asprof -e lock -d 30 -f lock.jfr <pid>
130
- ```
131
-
132
- Recorded as `profiler.NativeLock` events.
133
-
134
- ## Profiling all events
135
-
136
- ### Java Flight Recorder
137
-
138
- The `profile` template records execution samples, allocations, locks, GC, and
139
- many other JVM events at once. JFR rotates the recording into multiple chunks as
140
- it grows (`-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold).
141
-
142
- ```sh
143
- java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
144
- jfr summary all.jfr
145
- ```
146
-
147
- ### async-profiler
148
-
149
- `--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock`
150
- simultaneously. Add `--nofree` to suppress the high-volume native `free` events,
151
- which otherwise dominate the recording.
152
-
153
- ```sh
154
- asprof --all --nofree -d 30 -f all.jfr <pid>
155
- ```
156
-
157
- ## async-profiler flags
158
-
159
- | Flag | Default | Description |
160
- | ------------------- | ------- | ------------------------------------------------------------ |
161
- | `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock`, and others |
162
- | `-d` / `--duration` | — | Duration in seconds |
163
- | `-o` / `--output` | `jfr` | Output format (`jfr` or `collapsed`) |
164
- | `-f` / `--file` | — | Output file path |
165
- | `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
166
- | `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
167
- | `<pid>` | — | Target JVM PID, `jps`, or the application name |
168
-
169
- On macOS the default `cpu` event works (it samples CPU time via a timer), but
170
- hardware events like `cache-misses` require Linux `perf_events`.