profiler-md 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/dist/cli/index.mjs +5789 -5181
  2. package/dist/index.d.mts +478 -137
  3. package/dist/index.js +2 -2
  4. package/docs/formats/jfr.md +1 -1
  5. package/docs/formats/jsc-heap-snapshot.md +1 -1
  6. package/docs/formats/pprof.md +8 -6
  7. package/docs/formats/speedscope.md +5 -4
  8. package/docs/formats/systing.md +25 -0
  9. package/docs/formats/v8-heap-snapshot.md +2 -2
  10. package/docs/languages/c.md +35 -2
  11. package/docs/languages/csharp.md +2 -4
  12. package/docs/languages/elixir.md +4 -5
  13. package/docs/languages/go.md +6 -6
  14. package/docs/languages/java.md +13 -13
  15. package/docs/languages/javascript.md +7 -7
  16. package/docs/languages/julia.md +92 -13
  17. package/docs/languages/php.md +3 -4
  18. package/docs/languages/python.md +28 -13
  19. package/docs/languages/ruby.md +4 -6
  20. package/docs/languages/rust.md +37 -8
  21. package/examples/output/c.gperftools.heap.base.pprof.md +151 -151
  22. package/examples/output/c.gperftools.heap.current.pprof.md +151 -151
  23. package/examples/output/c.gperftools.heap.diff.pprof.md +3 -3
  24. package/examples/output/c.systing.cpu.base.systing.md +824 -0
  25. package/examples/output/c.systing.cpu.current.systing.md +825 -0
  26. package/examples/output/c.systing.cpu.diff.systing.md +238 -0
  27. package/examples/output/cpp.gperftools.heap.base.pprof.md +24 -24
  28. package/examples/output/cpp.gperftools.heap.current.pprof.md +24 -24
  29. package/examples/output/cpp.gperftools.heap.diff.pprof.md +2 -2
  30. package/examples/output/go.pprof.block.base.pprof.md +40 -40
  31. package/examples/output/go.pprof.block.current.pprof.md +37 -37
  32. package/examples/output/go.pprof.block.diff.pprof.md +14 -14
  33. package/examples/output/go.pprof.goroutine.base.pprof.md +16 -16
  34. package/examples/output/go.pprof.goroutine.current.pprof.md +16 -16
  35. package/examples/output/go.pprof.heap-alloc.base.pprof.md +79 -79
  36. package/examples/output/go.pprof.heap-alloc.current.pprof.md +72 -72
  37. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +25 -25
  38. package/examples/output/go.pprof.heap.base.pprof.md +79 -79
  39. package/examples/output/go.pprof.heap.current.pprof.md +72 -72
  40. package/examples/output/go.pprof.heap.diff.pprof.md +25 -25
  41. package/examples/output/go.pprof.mutex.base.pprof.md +26 -26
  42. package/examples/output/go.pprof.mutex.current.pprof.md +15 -15
  43. package/examples/output/go.pprof.mutex.diff.pprof.md +10 -10
  44. package/examples/output/java.async-profiler.all.base.jfr.md +192 -192
  45. package/examples/output/java.async-profiler.all.current.jfr.md +181 -181
  46. package/examples/output/java.async-profiler.all.diff.jfr.md +72 -72
  47. package/examples/output/java.async-profiler.alloc.base.jfr.md +189 -189
  48. package/examples/output/java.async-profiler.alloc.current.jfr.md +183 -183
  49. package/examples/output/java.async-profiler.alloc.diff.jfr.md +70 -70
  50. package/examples/output/java.async-profiler.live.base.jfr.md +303 -303
  51. package/examples/output/java.async-profiler.live.current.jfr.md +313 -313
  52. package/examples/output/java.async-profiler.live.diff.jfr.md +132 -132
  53. package/examples/output/java.async-profiler.nativemem.base.jfr.md +141 -141
  54. package/examples/output/java.async-profiler.nativemem.current.jfr.md +141 -141
  55. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +48 -48
  56. package/examples/output/java.jdk.all.base.jfr.md +281 -281
  57. package/examples/output/java.jdk.all.current.jfr.md +267 -267
  58. package/examples/output/java.jdk.all.diff.jfr.md +103 -103
  59. package/examples/output/java.jdk.alloc.base.jfr.md +254 -254
  60. package/examples/output/java.jdk.alloc.current.jfr.md +293 -293
  61. package/examples/output/java.jdk.alloc.diff.jfr.md +102 -102
  62. package/examples/output/java.jdk.cpu.base.jfr.md +256 -256
  63. package/examples/output/java.jdk.cpu.current.jfr.md +276 -276
  64. package/examples/output/java.jdk.cpu.diff.jfr.md +93 -93
  65. package/examples/output/java.jdk.live.base.jfr.md +256 -256
  66. package/examples/output/java.jdk.live.current.jfr.md +250 -250
  67. package/examples/output/java.jdk.live.diff.jfr.md +78 -78
  68. package/examples/output/java.jdk.lock.base.jfr.md +285 -285
  69. package/examples/output/java.jdk.lock.current.jfr.md +285 -285
  70. package/examples/output/java.jdk.lock.diff.jfr.md +121 -121
  71. package/examples/output/javascript.bun.base.cpuprofile.md +36 -36
  72. package/examples/output/javascript.bun.base.heapsnapshot.md +215 -215
  73. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +218 -218
  74. package/examples/output/javascript.bun.current.cpuprofile.md +34 -34
  75. package/examples/output/javascript.bun.current.heapsnapshot.md +215 -215
  76. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +220 -220
  77. package/examples/output/javascript.bun.diff.cpuprofile.md +19 -19
  78. package/examples/output/javascript.bun.diff.heapsnapshot.md +23 -23
  79. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +35 -35
  80. package/examples/output/javascript.chrome.base.heapprofile.md +17 -17
  81. package/examples/output/javascript.chrome.base.heapsnapshot.md +202 -202
  82. package/examples/output/javascript.chrome.current.heapprofile.md +17 -17
  83. package/examples/output/javascript.chrome.current.heapsnapshot.md +200 -200
  84. package/examples/output/javascript.chrome.diff.heapprofile.md +21 -21
  85. package/examples/output/javascript.chrome.diff.heapsnapshot.md +27 -27
  86. package/examples/output/javascript.deno.base.cpuprofile.md +63 -63
  87. package/examples/output/javascript.deno.current.cpuprofile.md +56 -56
  88. package/examples/output/javascript.deno.diff.cpuprofile.md +28 -28
  89. package/examples/output/javascript.node.base.cpuprofile.md +73 -73
  90. package/examples/output/javascript.node.base.heapprofile.md +32 -32
  91. package/examples/output/javascript.node.base.heapsnapshot.md +269 -269
  92. package/examples/output/javascript.node.current.cpuprofile.md +61 -61
  93. package/examples/output/javascript.node.current.heapprofile.md +28 -28
  94. package/examples/output/javascript.node.current.heapsnapshot.md +269 -269
  95. package/examples/output/javascript.node.diff.cpuprofile.md +32 -32
  96. package/examples/output/javascript.node.diff.heapprofile.md +17 -17
  97. package/examples/output/javascript.node.diff.heapsnapshot.md +19 -19
  98. package/examples/output/javascript.pprof.cpu.base.pprof.md +50 -50
  99. package/examples/output/javascript.pprof.cpu.current.pprof.md +66 -66
  100. package/examples/output/javascript.pprof.cpu.diff.pprof.md +28 -28
  101. package/examples/output/javascript.pprof.heap.base.pprof.md +46 -46
  102. package/examples/output/javascript.pprof.heap.current.pprof.md +34 -34
  103. package/examples/output/javascript.pprof.heap.diff.pprof.md +18 -18
  104. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +1 -1
  105. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +83 -83
  106. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +85 -85
  107. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +18 -18
  108. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +107 -107
  109. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +109 -109
  110. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +29 -29
  111. package/examples/output/julia.pprof-jl.wall.base.pprof.md +181 -0
  112. package/examples/output/julia.pprof-jl.wall.current.pprof.md +193 -0
  113. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +64 -0
  114. package/examples/output/julia.profile.base.heapsnapshot.md +590 -0
  115. package/examples/output/julia.profile.current.heapsnapshot.md +590 -0
  116. package/examples/output/julia.profile.diff.heapsnapshot.md +288 -0
  117. package/examples/output/kotlin.async-profiler.all.base.jfr.md +193 -193
  118. package/examples/output/kotlin.async-profiler.all.current.jfr.md +218 -218
  119. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +93 -93
  120. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +212 -212
  121. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +183 -183
  122. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +93 -93
  123. package/examples/output/kotlin.async-profiler.live.base.jfr.md +343 -343
  124. package/examples/output/kotlin.async-profiler.live.current.jfr.md +336 -336
  125. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +186 -186
  126. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +150 -150
  127. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +150 -150
  128. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +48 -48
  129. package/examples/output/kotlin.jdk.all.base.jfr.md +402 -402
  130. package/examples/output/kotlin.jdk.all.current.jfr.md +413 -413
  131. package/examples/output/kotlin.jdk.all.diff.jfr.md +169 -169
  132. package/examples/output/kotlin.jdk.alloc.base.jfr.md +418 -418
  133. package/examples/output/kotlin.jdk.alloc.current.jfr.md +405 -405
  134. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +160 -160
  135. package/examples/output/kotlin.jdk.cpu.base.jfr.md +418 -418
  136. package/examples/output/kotlin.jdk.cpu.current.jfr.md +413 -413
  137. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +148 -148
  138. package/examples/output/kotlin.jdk.live.base.jfr.md +420 -420
  139. package/examples/output/kotlin.jdk.live.current.jfr.md +411 -411
  140. package/examples/output/kotlin.jdk.live.diff.jfr.md +148 -148
  141. package/examples/output/kotlin.jdk.lock.base.jfr.md +417 -417
  142. package/examples/output/kotlin.jdk.lock.current.jfr.md +398 -398
  143. package/examples/output/kotlin.jdk.lock.diff.jfr.md +156 -156
  144. package/examples/output/php.excimer.wall.base.speedscope.json.md +6 -6
  145. package/examples/output/php.excimer.wall.current.speedscope.json.md +6 -6
  146. package/examples/output/php.excimer.wall.diff.speedscope.json.md +6 -6
  147. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +14 -14
  148. package/examples/output/ruby.rbspy.cpu.base.pprof.md +14 -14
  149. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +14 -14
  150. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +12 -12
  151. package/examples/output/ruby.rbspy.cpu.current.pprof.md +21 -21
  152. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +21 -21
  153. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +5 -5
  154. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +12 -12
  155. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +12 -12
  156. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +32 -32
  157. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +32 -32
  158. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +7 -7
  159. package/package.json +11 -10
  160. package/readme.md +53 -31
  161. package/skills/profile-optimize/SKILL.md +160 -0
  162. package/docs/languages/cpp.md +0 -160
  163. package/docs/languages/erlang.md +0 -46
  164. package/docs/languages/fsharp.md +0 -52
  165. package/docs/languages/kotlin.md +0 -170
  166. package/docs/languages/typescript.md +0 -276
@@ -0,0 +1,160 @@
1
+ ---
2
+ name: profile-optimize
3
+ description: Generate a performance profile, identify hotspots, and optimize.
4
+ argument-hint: '[what to focus on]'
5
+ allowed-tools: Bash(profiler-md *)
6
+ ---
7
+
8
+ Generate a performance profile, identify hotspots, and optimize.
9
+
10
+ Focus: $ARGUMENTS
11
+
12
+ # Workflow
13
+
14
+ 1. Decide what to profile (time or memory) and write an isolated script that
15
+ exercises the slow path if nothing runs it directly. Run
16
+ `profiler-md --help <language>` for profiling instructions
17
+ 2. Capture a baseline: generate a profile, convert it with
18
+ `profiler-md path/to/profile`, and read the full report, focusing on:
19
+ - Hottest functions: self % shows where time is spent or memory is allocated,
20
+ not just passed through
21
+ - Hottest call stacks: the full call path to the hot functions
22
+ 3. Identify the hottest 1-3 functions by self % and read their source:
23
+ - Native functions are often unavoidable but may indicate unnecessary work
24
+ (e.g. parsing the same data twice, creating many intermediate arrays)
25
+ - Project functions are direct targets
26
+ 4. State a hypothesis (see "Hypotheses"). If the bottleneck is unclear, reread
27
+ the hot function and its callers
28
+ 5. Apply the minimal change that addresses the bottleneck, one optimization at a
29
+ time. Leave unrelated code alone. Optimize the general case, not the
30
+ benchmark: don't exploit quirks of the profiled input (its size, ordering,
31
+ value distribution, or hardcoded special cases for it) unless they're
32
+ guaranteed properties of real inputs
33
+ 6. Run the relevant tests: if any newly fail, fix the optimization or revert it
34
+ 7. Capture a new report as in step 2 and compare self % for the targeted
35
+ function(s) against the baseline: if the improvement is negligible or
36
+ unclear, revert and go back to step 4 instead of iterating blindly. If the
37
+ comparison is too noisy to call, collect more samples (see "Measurement");
38
+ don't fall back to manual timing
39
+ 8. If the goal is unmet and a clear bottleneck remains, repeat from step 3 with
40
+ the new profile as the baseline
41
+ 9. Report:
42
+ - Before vs after for the hot function(s)
43
+ - Any other functions that moved significantly (regressions)
44
+
45
+ # Measurement
46
+
47
+ profiler-md reports are the ONLY measurements in this workflow. NEVER time
48
+ manually (e.g. `time` or `performance.now()`).
49
+
50
+ Manual timing yields one noisy end-to-end number that can improve for reasons
51
+ unrelated to the change (machine load, caches, GC timing), and its
52
+ instrumentation distorts the hot path. A profile attributes work to functions,
53
+ so a before/after comparison proves the optimization removed the targeted work,
54
+ not merely that one run was faster.
55
+
56
+ If a profile has too few samples to trust, collect more:
57
+
58
+ - Run the workload longer or loop it more times
59
+ - Raise the sampling frequency if the profiler supports it (see
60
+ `profiler-md --help <language>`)
61
+ - Regenerate the profile and compare again
62
+
63
+ # Hypotheses
64
+
65
+ Before changing anything, state:
66
+
67
+ - What is the bottleneck? (e.g. "repeated object allocation in the hot loop",
68
+ "O(n²) suffix scan", "redundant map lookups")
69
+ - What is the expected fix? (e.g. "hoist allocation outside loop", "use a
70
+ two-pointer suffix scan", "cache the lookup result")
71
+ - Why will it be faster?
72
+
73
+ # Focus areas
74
+
75
+ Sub-bullets are examples, not exhaustive lists.
76
+
77
+ - Time complexity: reduce the asymptotic work per input element
78
+ - Replace `O(n²)` scans with single-pass or two-pointer algorithms
79
+ - Use heaps for top-N instead of fully sorting
80
+ - Sort once and binary search instead of repeated linear scans
81
+ - Redundant work: compute each result once
82
+ - Avoid parsing or computing the same data twice; cache or memoize repeated
83
+ lookups
84
+ - Hoist loop-invariant computation out of loops
85
+ - Build lookup tables once instead of searching repeatedly; intern repeated
86
+ values
87
+ - Update incrementally instead of recomputing from scratch
88
+ - Persist expensive results between invocations, keyed by input so stale
89
+ entries are never served
90
+ - Work avoidance: skip or defer computation whose result may never be used
91
+ - Exit early once the answer is known
92
+ - Filter before expensive transforms, not after
93
+ - Order checks cheapest-first so expensive predicates run last and rarely
94
+ - Add fast paths for the common input shape
95
+ - Defer initialization and large dependency loading until first use,
96
+ especially on the startup critical path
97
+ - Debounce or throttle work triggered by bursty events
98
+ - Data structure selection: match the structure to the access pattern
99
+ - Use sets/maps for membership and lookup instead of linear scans
100
+ - Use bitsets for dense boolean membership
101
+ - Use a ring buffer for FIFO access instead of shifting an array
102
+ - Cache locality: lay out data so hot loops read memory sequentially
103
+ - Compressed sparse row (CSR) format
104
+ - Data-oriented design (struct-of-arrays, packed primitive arrays)
105
+ - Sparse arrays indexed by sequential IDs instead of integer-keyed hash maps
106
+ - Iterate in storage order (e.g. row-major for nested arrays)
107
+ - Allocation and copying: allocate and copy less in hot paths
108
+ - Hoist allocations out of hot loops; reuse buffers instead of reallocating
109
+ - Preallocate arrays and buffers to their known final size instead of growing
110
+ incrementally
111
+ - Avoid intermediate collections from chained transforms; fuse them into one
112
+ pass
113
+ - Use views/slices over underlying data instead of copying; defer cloning
114
+ until mutation is needed
115
+ - Memory footprint: hold and retain only what the computation needs
116
+ - Stream or process incrementally instead of materializing intermediates
117
+ - Bound caches (e.g. LRU); use weak references for object-keyed caches
118
+ - Remove listeners, timers, and subscriptions when done
119
+ - Avoid closures capturing large outer scopes; drop references held by
120
+ long-lived structures once no longer needed
121
+ - String handling: minimize the strings created and scanned in hot paths
122
+ - Avoid repeated concatenation in loops
123
+ - Work with indices or char codes into the original string instead of creating
124
+ substrings
125
+ - Minimize serialization/deserialization round-trips
126
+ - Avoid regex in hot paths
127
+ - Runtime friendliness: stay on the JIT's optimized fast paths
128
+ - Keep object shapes consistent (same fields, same initialization order)
129
+ - Avoid polymorphic call sites and mixed-type arrays in hot paths
130
+ - Keep numbers in the runtime's fast representations; avoid deoptimization
131
+ triggers in hot loops
132
+ - I/O and queries: make fewer round-trips and move fewer bytes
133
+ - Read or write in large chunks instead of many small operations
134
+ - Eliminate N+1 patterns by coalescing small queries or requests into one
135
+ batch
136
+ - Push filtering, aggregation, and pagination down to the data store; add
137
+ indexes matching the hot query's predicates
138
+ - Compress or use binary encodings for large transfers; send only the fields
139
+ the consumer reads
140
+ - Concurrency: use idle hardware for independent work
141
+ - Run independent async operations concurrently, bounded to what the awaited
142
+ resource can absorb
143
+ - Overlap I/O waits with computation instead of strictly sequencing them
144
+ - Split CPU-bound work across threads or processes; use SIMD where the
145
+ platform supports it
146
+ - Contention and backpressure: keep concurrent parts from waiting on or
147
+ overwhelming each other
148
+ - Minimize time spent holding locks; shrink critical sections
149
+ - Shard or partition shared state; prefer immutable or thread-local data over
150
+ shared mutable state
151
+ - Bound queues so producers can't outrun consumers; shed or coalesce load when
152
+ the system is saturated
153
+ - Precision trade-offs: do cheaper work that's good enough, only when the
154
+ consumer tolerates the difference
155
+ - Use approximate algorithms (sampling, sketches, bloom filters)
156
+ - Lower resolution or cap iteration counts when the output tolerance allows
157
+ - Observability overhead: keep instrumentation cheap enough that it doesn't
158
+ distort the hot path
159
+ - Keep logging, tracing, and assertions out of hot loops
160
+ - Sample or gate expensive instrumentation behind flags
@@ -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`.