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.
- package/dist/cli/index.mjs +5789 -5181
- package/dist/index.d.mts +478 -137
- package/dist/index.js +2 -2
- package/docs/formats/jfr.md +1 -1
- package/docs/formats/jsc-heap-snapshot.md +1 -1
- package/docs/formats/pprof.md +8 -6
- package/docs/formats/speedscope.md +5 -4
- package/docs/formats/systing.md +25 -0
- package/docs/formats/v8-heap-snapshot.md +2 -2
- package/docs/languages/c.md +35 -2
- package/docs/languages/csharp.md +2 -4
- package/docs/languages/elixir.md +4 -5
- package/docs/languages/go.md +6 -6
- package/docs/languages/java.md +13 -13
- package/docs/languages/javascript.md +7 -7
- package/docs/languages/julia.md +92 -13
- package/docs/languages/php.md +3 -4
- package/docs/languages/python.md +28 -13
- package/docs/languages/ruby.md +4 -6
- package/docs/languages/rust.md +37 -8
- package/examples/output/c.gperftools.heap.base.pprof.md +151 -151
- package/examples/output/c.gperftools.heap.current.pprof.md +151 -151
- package/examples/output/c.gperftools.heap.diff.pprof.md +3 -3
- package/examples/output/c.systing.cpu.base.systing.md +824 -0
- package/examples/output/c.systing.cpu.current.systing.md +825 -0
- package/examples/output/c.systing.cpu.diff.systing.md +238 -0
- package/examples/output/cpp.gperftools.heap.base.pprof.md +24 -24
- package/examples/output/cpp.gperftools.heap.current.pprof.md +24 -24
- package/examples/output/cpp.gperftools.heap.diff.pprof.md +2 -2
- package/examples/output/go.pprof.block.base.pprof.md +40 -40
- package/examples/output/go.pprof.block.current.pprof.md +37 -37
- package/examples/output/go.pprof.block.diff.pprof.md +14 -14
- package/examples/output/go.pprof.goroutine.base.pprof.md +16 -16
- package/examples/output/go.pprof.goroutine.current.pprof.md +16 -16
- package/examples/output/go.pprof.heap-alloc.base.pprof.md +79 -79
- package/examples/output/go.pprof.heap-alloc.current.pprof.md +72 -72
- package/examples/output/go.pprof.heap-alloc.diff.pprof.md +25 -25
- package/examples/output/go.pprof.heap.base.pprof.md +79 -79
- package/examples/output/go.pprof.heap.current.pprof.md +72 -72
- package/examples/output/go.pprof.heap.diff.pprof.md +25 -25
- package/examples/output/go.pprof.mutex.base.pprof.md +26 -26
- package/examples/output/go.pprof.mutex.current.pprof.md +15 -15
- package/examples/output/go.pprof.mutex.diff.pprof.md +10 -10
- package/examples/output/java.async-profiler.all.base.jfr.md +192 -192
- package/examples/output/java.async-profiler.all.current.jfr.md +181 -181
- package/examples/output/java.async-profiler.all.diff.jfr.md +72 -72
- package/examples/output/java.async-profiler.alloc.base.jfr.md +189 -189
- package/examples/output/java.async-profiler.alloc.current.jfr.md +183 -183
- package/examples/output/java.async-profiler.alloc.diff.jfr.md +70 -70
- package/examples/output/java.async-profiler.live.base.jfr.md +303 -303
- package/examples/output/java.async-profiler.live.current.jfr.md +313 -313
- package/examples/output/java.async-profiler.live.diff.jfr.md +132 -132
- package/examples/output/java.async-profiler.nativemem.base.jfr.md +141 -141
- package/examples/output/java.async-profiler.nativemem.current.jfr.md +141 -141
- package/examples/output/java.async-profiler.nativemem.diff.jfr.md +48 -48
- package/examples/output/java.jdk.all.base.jfr.md +281 -281
- package/examples/output/java.jdk.all.current.jfr.md +267 -267
- package/examples/output/java.jdk.all.diff.jfr.md +103 -103
- package/examples/output/java.jdk.alloc.base.jfr.md +254 -254
- package/examples/output/java.jdk.alloc.current.jfr.md +293 -293
- package/examples/output/java.jdk.alloc.diff.jfr.md +102 -102
- package/examples/output/java.jdk.cpu.base.jfr.md +256 -256
- package/examples/output/java.jdk.cpu.current.jfr.md +276 -276
- package/examples/output/java.jdk.cpu.diff.jfr.md +93 -93
- package/examples/output/java.jdk.live.base.jfr.md +256 -256
- package/examples/output/java.jdk.live.current.jfr.md +250 -250
- package/examples/output/java.jdk.live.diff.jfr.md +78 -78
- package/examples/output/java.jdk.lock.base.jfr.md +285 -285
- package/examples/output/java.jdk.lock.current.jfr.md +285 -285
- package/examples/output/java.jdk.lock.diff.jfr.md +121 -121
- package/examples/output/javascript.bun.base.cpuprofile.md +36 -36
- package/examples/output/javascript.bun.base.heapsnapshot.md +215 -215
- package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +218 -218
- package/examples/output/javascript.bun.current.cpuprofile.md +34 -34
- package/examples/output/javascript.bun.current.heapsnapshot.md +215 -215
- package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +220 -220
- package/examples/output/javascript.bun.diff.cpuprofile.md +19 -19
- package/examples/output/javascript.bun.diff.heapsnapshot.md +23 -23
- package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +35 -35
- package/examples/output/javascript.chrome.base.heapprofile.md +17 -17
- package/examples/output/javascript.chrome.base.heapsnapshot.md +202 -202
- package/examples/output/javascript.chrome.current.heapprofile.md +17 -17
- package/examples/output/javascript.chrome.current.heapsnapshot.md +200 -200
- package/examples/output/javascript.chrome.diff.heapprofile.md +21 -21
- package/examples/output/javascript.chrome.diff.heapsnapshot.md +27 -27
- package/examples/output/javascript.deno.base.cpuprofile.md +63 -63
- package/examples/output/javascript.deno.current.cpuprofile.md +56 -56
- package/examples/output/javascript.deno.diff.cpuprofile.md +28 -28
- package/examples/output/javascript.node.base.cpuprofile.md +73 -73
- package/examples/output/javascript.node.base.heapprofile.md +32 -32
- package/examples/output/javascript.node.base.heapsnapshot.md +269 -269
- package/examples/output/javascript.node.current.cpuprofile.md +61 -61
- package/examples/output/javascript.node.current.heapprofile.md +28 -28
- package/examples/output/javascript.node.current.heapsnapshot.md +269 -269
- package/examples/output/javascript.node.diff.cpuprofile.md +32 -32
- package/examples/output/javascript.node.diff.heapprofile.md +17 -17
- package/examples/output/javascript.node.diff.heapsnapshot.md +19 -19
- package/examples/output/javascript.pprof.cpu.base.pprof.md +50 -50
- package/examples/output/javascript.pprof.cpu.current.pprof.md +66 -66
- package/examples/output/javascript.pprof.cpu.diff.pprof.md +28 -28
- package/examples/output/javascript.pprof.heap.base.pprof.md +46 -46
- package/examples/output/javascript.pprof.heap.current.pprof.md +34 -34
- package/examples/output/javascript.pprof.heap.diff.pprof.md +18 -18
- package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +1 -1
- package/examples/output/julia.pprof-jl.alloc.base.pprof.md +83 -83
- package/examples/output/julia.pprof-jl.alloc.current.pprof.md +85 -85
- package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +18 -18
- package/examples/output/julia.pprof-jl.cpu.base.pprof.md +107 -107
- package/examples/output/julia.pprof-jl.cpu.current.pprof.md +109 -109
- package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +29 -29
- package/examples/output/julia.pprof-jl.wall.base.pprof.md +181 -0
- package/examples/output/julia.pprof-jl.wall.current.pprof.md +193 -0
- package/examples/output/julia.pprof-jl.wall.diff.pprof.md +64 -0
- package/examples/output/julia.profile.base.heapsnapshot.md +590 -0
- package/examples/output/julia.profile.current.heapsnapshot.md +590 -0
- package/examples/output/julia.profile.diff.heapsnapshot.md +288 -0
- package/examples/output/kotlin.async-profiler.all.base.jfr.md +193 -193
- package/examples/output/kotlin.async-profiler.all.current.jfr.md +218 -218
- package/examples/output/kotlin.async-profiler.all.diff.jfr.md +93 -93
- package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +212 -212
- package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +183 -183
- package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +93 -93
- package/examples/output/kotlin.async-profiler.live.base.jfr.md +343 -343
- package/examples/output/kotlin.async-profiler.live.current.jfr.md +336 -336
- package/examples/output/kotlin.async-profiler.live.diff.jfr.md +186 -186
- package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +150 -150
- package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +150 -150
- package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +48 -48
- package/examples/output/kotlin.jdk.all.base.jfr.md +402 -402
- package/examples/output/kotlin.jdk.all.current.jfr.md +413 -413
- package/examples/output/kotlin.jdk.all.diff.jfr.md +169 -169
- package/examples/output/kotlin.jdk.alloc.base.jfr.md +418 -418
- package/examples/output/kotlin.jdk.alloc.current.jfr.md +405 -405
- package/examples/output/kotlin.jdk.alloc.diff.jfr.md +160 -160
- package/examples/output/kotlin.jdk.cpu.base.jfr.md +418 -418
- package/examples/output/kotlin.jdk.cpu.current.jfr.md +413 -413
- package/examples/output/kotlin.jdk.cpu.diff.jfr.md +148 -148
- package/examples/output/kotlin.jdk.live.base.jfr.md +420 -420
- package/examples/output/kotlin.jdk.live.current.jfr.md +411 -411
- package/examples/output/kotlin.jdk.live.diff.jfr.md +148 -148
- package/examples/output/kotlin.jdk.lock.base.jfr.md +417 -417
- package/examples/output/kotlin.jdk.lock.current.jfr.md +398 -398
- package/examples/output/kotlin.jdk.lock.diff.jfr.md +156 -156
- package/examples/output/php.excimer.wall.base.speedscope.json.md +6 -6
- package/examples/output/php.excimer.wall.current.speedscope.json.md +6 -6
- package/examples/output/php.excimer.wall.diff.speedscope.json.md +6 -6
- package/examples/output/ruby.rbspy.cpu.base.collapsed.md +14 -14
- package/examples/output/ruby.rbspy.cpu.base.pprof.md +14 -14
- package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +14 -14
- package/examples/output/ruby.rbspy.cpu.current.collapsed.md +12 -12
- package/examples/output/ruby.rbspy.cpu.current.pprof.md +21 -21
- package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +21 -21
- package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +5 -5
- package/examples/output/ruby.rbspy.cpu.diff.pprof.md +12 -12
- package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +12 -12
- package/examples/output/rust.pprof-rs.cpu.base.pprof.md +32 -32
- package/examples/output/rust.pprof-rs.cpu.current.pprof.md +32 -32
- package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +7 -7
- package/package.json +11 -10
- package/readme.md +53 -31
- package/skills/profile-optimize/SKILL.md +160 -0
- package/docs/languages/cpp.md +0 -160
- package/docs/languages/erlang.md +0 -46
- package/docs/languages/fsharp.md +0 -52
- package/docs/languages/kotlin.md +0 -170
- 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
|
package/docs/languages/cpp.md
DELETED
|
@@ -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.
|
package/docs/languages/erlang.md
DELETED
|
@@ -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` |
|
package/docs/languages/fsharp.md
DELETED
|
@@ -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 |
|
package/docs/languages/kotlin.md
DELETED
|
@@ -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`.
|