profiler-md 0.6.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.
- package/dist/cli/index.mjs +12685 -4219
- package/dist/index.d.mts +1140 -432
- package/dist/index.js +2 -2
- package/docs/api.md +138 -0
- package/docs/formats/callgrind.md +25 -0
- package/docs/formats/collapsed.md +5 -3
- package/docs/formats/ghc-eventlog.md +20 -0
- package/docs/formats/ghc-json-profile.md +23 -0
- package/docs/formats/hprof.md +21 -0
- package/docs/formats/jfr.md +2 -2
- package/docs/formats/jsc-heap-snapshot.md +10 -4
- package/docs/formats/memray.md +30 -0
- package/docs/formats/perf.md +74 -0
- package/docs/formats/pprof.md +4 -2
- package/docs/formats/speedscope.md +3 -2
- package/docs/formats/systing.md +17 -15
- package/docs/formats/v8-cpu-profile.md +4 -3
- package/docs/formats/v8-heap-profile.md +8 -5
- package/docs/formats/v8-heap-snapshot.md +8 -3
- package/docs/formats/webkit-timeline-recording.md +6 -0
- package/docs/languages/c.md +119 -32
- package/docs/languages/csharp.md +5 -3
- package/docs/languages/elixir.md +19 -11
- package/docs/languages/fortran.md +141 -0
- package/docs/languages/go.md +33 -10
- package/docs/languages/haskell.md +134 -0
- package/docs/languages/java.md +81 -26
- package/docs/languages/javascript.md +33 -27
- package/docs/languages/julia.md +21 -18
- package/docs/languages/php.md +7 -0
- package/docs/languages/python.md +105 -14
- package/docs/languages/ruby.md +15 -16
- package/docs/languages/rust.md +11 -10
- package/docs/languages/swift.md +135 -0
- package/docs/languages/zig.md +155 -0
- package/package.json +42 -42
- package/readme.md +301 -259
- package/skills/profile-optimize/SKILL.md +4 -2
- package/examples/output/c.gperftools.cpu.base.pprof.md +0 -324
- package/examples/output/c.gperftools.cpu.current.pprof.md +0 -271
- package/examples/output/c.gperftools.cpu.diff.pprof.md +0 -98
- package/examples/output/c.gperftools.heap.base.pprof.md +0 -362
- package/examples/output/c.gperftools.heap.current.pprof.md +0 -362
- package/examples/output/c.gperftools.heap.diff.pprof.md +0 -28
- package/examples/output/c.systing.cpu.base.systing.md +0 -824
- package/examples/output/c.systing.cpu.current.systing.md +0 -825
- package/examples/output/c.systing.cpu.diff.systing.md +0 -238
- package/examples/output/cpp.gperftools.cpu.base.pprof.md +0 -557
- package/examples/output/cpp.gperftools.cpu.current.pprof.md +0 -573
- package/examples/output/cpp.gperftools.cpu.diff.pprof.md +0 -122
- package/examples/output/cpp.gperftools.heap.base.pprof.md +0 -67
- package/examples/output/cpp.gperftools.heap.current.pprof.md +0 -67
- package/examples/output/cpp.gperftools.heap.diff.pprof.md +0 -19
- package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +0 -411
- package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +0 -412
- package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +0 -122
- package/examples/output/elixir.eflambe.cpu.base.collapsed.md +0 -399
- package/examples/output/elixir.eflambe.cpu.current.collapsed.md +0 -398
- package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +0 -92
- package/examples/output/erlang.eflambe.cpu.base.collapsed.md +0 -147
- package/examples/output/erlang.eflambe.cpu.current.collapsed.md +0 -147
- package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +0 -18
- package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +0 -324
- package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +0 -314
- package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +0 -119
- package/examples/output/go.pprof.block.base.pprof.md +0 -86
- package/examples/output/go.pprof.block.current.pprof.md +0 -83
- package/examples/output/go.pprof.block.diff.pprof.md +0 -42
- package/examples/output/go.pprof.cpu.base.pprof.md +0 -81
- package/examples/output/go.pprof.cpu.current.pprof.md +0 -70
- package/examples/output/go.pprof.cpu.diff.pprof.md +0 -52
- package/examples/output/go.pprof.goroutine.base.pprof.md +0 -43
- package/examples/output/go.pprof.goroutine.current.pprof.md +0 -43
- package/examples/output/go.pprof.goroutine.diff.pprof.md +0 -13
- package/examples/output/go.pprof.heap-alloc.base.pprof.md +0 -154
- package/examples/output/go.pprof.heap-alloc.current.pprof.md +0 -146
- package/examples/output/go.pprof.heap-alloc.diff.pprof.md +0 -67
- package/examples/output/go.pprof.heap.base.pprof.md +0 -154
- package/examples/output/go.pprof.heap.current.pprof.md +0 -146
- package/examples/output/go.pprof.heap.diff.pprof.md +0 -67
- package/examples/output/go.pprof.mutex.base.pprof.md +0 -55
- package/examples/output/go.pprof.mutex.current.pprof.md +0 -41
- package/examples/output/go.pprof.mutex.diff.pprof.md +0 -31
- package/examples/output/go.pprof.threadcreate.base.pprof.md +0 -55
- package/examples/output/go.pprof.threadcreate.current.pprof.md +0 -55
- package/examples/output/go.pprof.threadcreate.diff.pprof.md +0 -19
- package/examples/output/java.async-profiler.all.base.jfr.md +0 -1071
- package/examples/output/java.async-profiler.all.current.jfr.md +0 -1007
- package/examples/output/java.async-profiler.all.diff.jfr.md +0 -268
- package/examples/output/java.async-profiler.alloc.base.jfr.md +0 -425
- package/examples/output/java.async-profiler.alloc.current.jfr.md +0 -413
- package/examples/output/java.async-profiler.alloc.diff.jfr.md +0 -99
- package/examples/output/java.async-profiler.cpu.base.collapsed.md +0 -367
- package/examples/output/java.async-profiler.cpu.base.jfr.md +0 -485
- package/examples/output/java.async-profiler.cpu.current.collapsed.md +0 -355
- package/examples/output/java.async-profiler.cpu.current.jfr.md +0 -488
- package/examples/output/java.async-profiler.cpu.diff.collapsed.md +0 -117
- package/examples/output/java.async-profiler.cpu.diff.jfr.md +0 -118
- package/examples/output/java.async-profiler.live.base.jfr.md +0 -697
- package/examples/output/java.async-profiler.live.current.jfr.md +0 -684
- package/examples/output/java.async-profiler.live.diff.jfr.md +0 -191
- package/examples/output/java.async-profiler.lock.base.jfr.md +0 -140
- package/examples/output/java.async-profiler.lock.current.jfr.md +0 -108
- package/examples/output/java.async-profiler.lock.diff.jfr.md +0 -44
- package/examples/output/java.async-profiler.nativemem.base.jfr.md +0 -222
- package/examples/output/java.async-profiler.nativemem.current.jfr.md +0 -222
- package/examples/output/java.async-profiler.nativemem.diff.jfr.md +0 -65
- package/examples/output/java.async-profiler.wall.base.jfr.md +0 -400
- package/examples/output/java.async-profiler.wall.current.jfr.md +0 -420
- package/examples/output/java.async-profiler.wall.diff.jfr.md +0 -94
- package/examples/output/java.jdk.all.base.jfr.md +0 -1024
- package/examples/output/java.jdk.all.current.jfr.md +0 -1010
- package/examples/output/java.jdk.all.diff.jfr.md +0 -311
- package/examples/output/java.jdk.alloc.base.jfr.md +0 -1024
- package/examples/output/java.jdk.alloc.current.jfr.md +0 -1046
- package/examples/output/java.jdk.alloc.diff.jfr.md +0 -312
- package/examples/output/java.jdk.cpu.base.jfr.md +0 -1023
- package/examples/output/java.jdk.cpu.current.jfr.md +0 -1039
- package/examples/output/java.jdk.cpu.diff.jfr.md +0 -285
- package/examples/output/java.jdk.live.base.jfr.md +0 -1029
- package/examples/output/java.jdk.live.current.jfr.md +0 -1035
- package/examples/output/java.jdk.live.diff.jfr.md +0 -289
- package/examples/output/java.jdk.lock.base.jfr.md +0 -1040
- package/examples/output/java.jdk.lock.current.jfr.md +0 -1051
- package/examples/output/java.jdk.lock.diff.jfr.md +0 -339
- package/examples/output/javascript.bun.base.cpuprofile.md +0 -73
- package/examples/output/javascript.bun.base.heapsnapshot.md +0 -608
- package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +0 -480
- package/examples/output/javascript.bun.current.cpuprofile.md +0 -73
- package/examples/output/javascript.bun.current.heapsnapshot.md +0 -608
- package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +0 -480
- package/examples/output/javascript.bun.diff.cpuprofile.md +0 -54
- package/examples/output/javascript.bun.diff.heapsnapshot.md +0 -48
- package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +0 -62
- package/examples/output/javascript.chrome.base.cpuprofile.md +0 -163
- package/examples/output/javascript.chrome.base.heapprofile.md +0 -32
- package/examples/output/javascript.chrome.base.heapsnapshot.md +0 -649
- package/examples/output/javascript.chrome.current.cpuprofile.md +0 -149
- package/examples/output/javascript.chrome.current.heapprofile.md +0 -32
- package/examples/output/javascript.chrome.current.heapsnapshot.md +0 -647
- package/examples/output/javascript.chrome.diff.cpuprofile.md +0 -65
- package/examples/output/javascript.chrome.diff.heapprofile.md +0 -50
- package/examples/output/javascript.chrome.diff.heapsnapshot.md +0 -73
- package/examples/output/javascript.deno.base.cpuprofile.md +0 -122
- package/examples/output/javascript.deno.current.cpuprofile.md +0 -114
- package/examples/output/javascript.deno.diff.cpuprofile.md +0 -66
- package/examples/output/javascript.node.base.cpuprofile.md +0 -136
- package/examples/output/javascript.node.base.heapprofile.md +0 -56
- package/examples/output/javascript.node.base.heapsnapshot.md +0 -660
- package/examples/output/javascript.node.current.cpuprofile.md +0 -119
- package/examples/output/javascript.node.current.heapprofile.md +0 -52
- package/examples/output/javascript.node.current.heapsnapshot.md +0 -660
- package/examples/output/javascript.node.diff.cpuprofile.md +0 -70
- package/examples/output/javascript.node.diff.heapprofile.md +0 -34
- package/examples/output/javascript.node.diff.heapsnapshot.md +0 -39
- package/examples/output/javascript.pprof.cpu.base.pprof.md +0 -104
- package/examples/output/javascript.pprof.cpu.current.pprof.md +0 -120
- package/examples/output/javascript.pprof.cpu.diff.pprof.md +0 -63
- package/examples/output/javascript.pprof.heap.base.pprof.md +0 -86
- package/examples/output/javascript.pprof.heap.current.pprof.md +0 -57
- package/examples/output/javascript.pprof.heap.diff.pprof.md +0 -42
- package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +0 -388
- package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +0 -378
- package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +0 -122
- package/examples/output/julia.pprof-jl.alloc.base.pprof.md +0 -124
- package/examples/output/julia.pprof-jl.alloc.current.pprof.md +0 -126
- package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +0 -30
- package/examples/output/julia.pprof-jl.cpu.base.pprof.md +0 -177
- package/examples/output/julia.pprof-jl.cpu.current.pprof.md +0 -179
- package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +0 -64
- package/examples/output/julia.pprof-jl.wall.base.pprof.md +0 -181
- package/examples/output/julia.pprof-jl.wall.current.pprof.md +0 -193
- package/examples/output/julia.pprof-jl.wall.diff.pprof.md +0 -64
- package/examples/output/julia.profile.base.heapsnapshot.md +0 -590
- package/examples/output/julia.profile.current.heapsnapshot.md +0 -590
- package/examples/output/julia.profile.diff.heapsnapshot.md +0 -288
- package/examples/output/kotlin.async-profiler.all.base.jfr.md +0 -920
- package/examples/output/kotlin.async-profiler.all.current.jfr.md +0 -925
- package/examples/output/kotlin.async-profiler.all.diff.jfr.md +0 -247
- package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +0 -467
- package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +0 -473
- package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +0 -122
- package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +0 -371
- package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +0 -472
- package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +0 -370
- package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +0 -445
- package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +0 -124
- package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +0 -125
- package/examples/output/kotlin.async-profiler.live.base.jfr.md +0 -934
- package/examples/output/kotlin.async-profiler.live.current.jfr.md +0 -917
- package/examples/output/kotlin.async-profiler.live.diff.jfr.md +0 -245
- package/examples/output/kotlin.async-profiler.lock.base.jfr.md +0 -1
- package/examples/output/kotlin.async-profiler.lock.current.jfr.md +0 -1
- package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +0 -1
- package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +0 -234
- package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +0 -234
- package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +0 -65
- package/examples/output/kotlin.async-profiler.wall.base.jfr.md +0 -452
- package/examples/output/kotlin.async-profiler.wall.current.jfr.md +0 -457
- package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +0 -125
- package/examples/output/kotlin.jdk.all.base.jfr.md +0 -1442
- package/examples/output/kotlin.jdk.all.current.jfr.md +0 -1343
- package/examples/output/kotlin.jdk.all.diff.jfr.md +0 -392
- package/examples/output/kotlin.jdk.alloc.base.jfr.md +0 -1418
- package/examples/output/kotlin.jdk.alloc.current.jfr.md +0 -1389
- package/examples/output/kotlin.jdk.alloc.diff.jfr.md +0 -383
- package/examples/output/kotlin.jdk.cpu.base.jfr.md +0 -1406
- package/examples/output/kotlin.jdk.cpu.current.jfr.md +0 -1374
- package/examples/output/kotlin.jdk.cpu.diff.jfr.md +0 -380
- package/examples/output/kotlin.jdk.live.base.jfr.md +0 -1378
- package/examples/output/kotlin.jdk.live.current.jfr.md +0 -1311
- package/examples/output/kotlin.jdk.live.diff.jfr.md +0 -381
- package/examples/output/kotlin.jdk.lock.base.jfr.md +0 -1427
- package/examples/output/kotlin.jdk.lock.current.jfr.md +0 -1374
- package/examples/output/kotlin.jdk.lock.diff.jfr.md +0 -386
- package/examples/output/php.excimer.wall.base.speedscope.json.md +0 -25
- package/examples/output/php.excimer.wall.current.speedscope.json.md +0 -25
- package/examples/output/php.excimer.wall.diff.speedscope.json.md +0 -29
- package/examples/output/python.py-spy.cpu.base.collapsed.md +0 -526
- package/examples/output/python.py-spy.cpu.base.speedscope.json.md +0 -37
- package/examples/output/python.py-spy.cpu.current.collapsed.md +0 -514
- package/examples/output/python.py-spy.cpu.current.speedscope.json.md +0 -37
- package/examples/output/python.py-spy.cpu.diff.collapsed.md +0 -122
- package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +0 -31
- package/examples/output/python.py-spy.wall.base.collapsed.md +0 -527
- package/examples/output/python.py-spy.wall.current.collapsed.md +0 -518
- package/examples/output/python.py-spy.wall.diff.collapsed.md +0 -122
- package/examples/output/ruby.rbspy.cpu.base.collapsed.md +0 -90
- package/examples/output/ruby.rbspy.cpu.base.pprof.md +0 -105
- package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +0 -105
- package/examples/output/ruby.rbspy.cpu.current.collapsed.md +0 -90
- package/examples/output/ruby.rbspy.cpu.current.pprof.md +0 -115
- package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +0 -115
- package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +0 -32
- package/examples/output/ruby.rbspy.cpu.diff.pprof.md +0 -44
- package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +0 -44
- package/examples/output/rust.pprof-rs.cpu.base.pprof.md +0 -60
- package/examples/output/rust.pprof-rs.cpu.current.pprof.md +0 -60
- package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +0 -24
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Haskell
|
|
2
|
+
|
|
3
|
+
Haskell profiling uses GHC's built-in
|
|
4
|
+
[cost-centre profiler](https://downloads.haskell.org/ghc/latest/docs/users_guide/profiling.html),
|
|
5
|
+
which writes a JSON report (`+RTS -pj`) and an eventlog (`+RTS -l`). A cost
|
|
6
|
+
centre is an annotation on a binding that the runtime attributes time and
|
|
7
|
+
allocation to.
|
|
8
|
+
|
|
9
|
+
## Wall-clock profiling
|
|
10
|
+
|
|
11
|
+
Periodically samples the cost-centre stack. Useful for finding hot spots,
|
|
12
|
+
including the time the program spends blocked, which the runtime attributes to
|
|
13
|
+
the built-in `IDLE` cost centre.
|
|
14
|
+
|
|
15
|
+
The timer runs on real time and samples every capability whether or not it is
|
|
16
|
+
running Haskell. The runtime also counts every byte the program allocates per
|
|
17
|
+
cost-centre stack and every time it enters one, and the JSON report includes
|
|
18
|
+
both counts. The eventlog omits them.
|
|
19
|
+
|
|
20
|
+
GHC inserts cost centres only into modules compiled with `-prof`, so compile
|
|
21
|
+
every library the program links with `-prof` too:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
# cabal, which rebuilds the dependencies with profiling as well
|
|
25
|
+
cabal build --enable-profiling
|
|
26
|
+
|
|
27
|
+
# stack
|
|
28
|
+
stack build --profile
|
|
29
|
+
|
|
30
|
+
# ghc directly
|
|
31
|
+
ghc -O2 -prof -fprof-auto-top -rtsopts Main.hs
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Cost centres
|
|
35
|
+
|
|
36
|
+
Annotating every binding costs time and prevents optimizations, so GHC inserts
|
|
37
|
+
only the cost centres one of these flags specifies. Add `{-# SCC "name" #-}` in
|
|
38
|
+
the source to annotate an expression by hand.
|
|
39
|
+
|
|
40
|
+
#### Flags
|
|
41
|
+
|
|
42
|
+
| Flag | Description |
|
|
43
|
+
| ------------------------ | ----------------------------------------------------------------------------------- |
|
|
44
|
+
| `-fprof-auto` | A cost centre for every binding, including local ones |
|
|
45
|
+
| `-fprof-auto-top` | A cost centre for every top-level binding |
|
|
46
|
+
| `-fprof-auto-exported` | A cost centre for every exported binding |
|
|
47
|
+
| `-fprof-auto-calls` | A cost centre at every call site, required for `-xc` stack traces |
|
|
48
|
+
| `-fprof-late` | A cost centre for every top-level binding, inserted after optimization (GHC ≥ 9.4) |
|
|
49
|
+
| `-fprof-late-overloaded` | A cost centre for every overloaded top-level binding, inserted after optimization |
|
|
50
|
+
| `-fno-prof-auto` | No automatic cost centres, keeping only the `{-# SCC #-}` annotations in the source |
|
|
51
|
+
|
|
52
|
+
Cabal picks the flag from `--profiling-detail`, which defaults to
|
|
53
|
+
`exported-functions` for a library and `toplevel-functions` for an executable.
|
|
54
|
+
Pass a GHC flag directly with `--ghc-options=-fprof-late`.
|
|
55
|
+
|
|
56
|
+
`-fprof-auto` and its variants insert their cost centres before optimization, so
|
|
57
|
+
the optimizer cannot inline or fuse the annotated code. The profiled program
|
|
58
|
+
then runs code a release build never runs. `-fprof-late` annotates the optimized
|
|
59
|
+
program instead, at the cost of names the compiler generated (`$wgo1`, `main2`)
|
|
60
|
+
in place of the source's.
|
|
61
|
+
|
|
62
|
+
### CLI
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
# The JSON report, written to Main.prof
|
|
66
|
+
cabal run --enable-profiling my-program -- +RTS -pj -RTS
|
|
67
|
+
|
|
68
|
+
# The JSON report and the eventlog, from one run
|
|
69
|
+
./Main +RTS -pj -l-au -RTS
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Prefer the JSON report, which contains the allocation totals as well as the
|
|
73
|
+
ticks. Use the eventlog when the program already records one, or when marking
|
|
74
|
+
phases with `Debug.Trace.traceEventIO` to profile a run in parts.
|
|
75
|
+
|
|
76
|
+
An eventlog contains cost-centre samples only when the time profiler runs, which
|
|
77
|
+
`-pj` turns on alongside the JSON report. `-p` turns it on too, but writes the
|
|
78
|
+
text report, which is for reading by hand, so profiler-md rejects it.
|
|
79
|
+
|
|
80
|
+
#### RTS options
|
|
81
|
+
|
|
82
|
+
| Option | Default | Description |
|
|
83
|
+
| ------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
84
|
+
| `-p` | — | Write a time and allocation report to `<program>.prof` |
|
|
85
|
+
| `-P` | — | As `-p`, plus per-cost-centre tick and byte counts |
|
|
86
|
+
| `-pj` | — | Write the report as JSON |
|
|
87
|
+
| `-l` | — | Write an eventlog to `<program>.eventlog` |
|
|
88
|
+
| `-ol` | — | The eventlog's path |
|
|
89
|
+
| `-V` | `0.001` | Seconds between samples, and the resolution of every other RTS timer. A build without `-prof` ticks every `0.01` seconds |
|
|
90
|
+
| `-xc` | — | Print the cost-centre stack on every exception |
|
|
91
|
+
|
|
92
|
+
`-l` takes the event classes to log. `-l-au` turns them all off and turns user
|
|
93
|
+
events back on, so the scheduler and heap events stay out of a log recorded for
|
|
94
|
+
its cost-centre samples.
|
|
95
|
+
|
|
96
|
+
## Tips
|
|
97
|
+
|
|
98
|
+
### Garbage collection
|
|
99
|
+
|
|
100
|
+
The runtime's collector reports as the `GC` cost centre. Read its share of the
|
|
101
|
+
ticks first, because a Haskell program that allocates heavily spends much of its
|
|
102
|
+
time collecting. Cutting the allocation the profile attributes to the program's
|
|
103
|
+
own cost centres also cuts the collector's share.
|
|
104
|
+
|
|
105
|
+
### Runtime cost centres
|
|
106
|
+
|
|
107
|
+
The runtime's own cost centres (`MAIN`, `CAF`, `GC`) have no source location.
|
|
108
|
+
|
|
109
|
+
### Boot libraries
|
|
110
|
+
|
|
111
|
+
A library compiled without `-prof` gets no cost centres, so the profile
|
|
112
|
+
attributes its time to the nearest annotated caller. A default GHC install ships
|
|
113
|
+
`base` and the other boot libraries that way, while
|
|
114
|
+
`cabal build --enable-profiling` and `stack build --profile` rebuild every
|
|
115
|
+
dependency with cost centres.
|
|
116
|
+
|
|
117
|
+
### Packages
|
|
118
|
+
|
|
119
|
+
A cost centre's source span is relative to the package GHC compiled the module
|
|
120
|
+
from, and the report names no package, so profiler-md counts a dependency's cost
|
|
121
|
+
centres as the program's own code rather than as `third-party`.
|
|
122
|
+
|
|
123
|
+
### Overhead
|
|
124
|
+
|
|
125
|
+
Time the profiled build against a plain one before treating the profile's
|
|
126
|
+
numbers as a release build's. Profiling adds a word to every closure and
|
|
127
|
+
prevents some optimizations, so a program that allocates heavily can run several
|
|
128
|
+
times slower.
|
|
129
|
+
|
|
130
|
+
### Benchmarks
|
|
131
|
+
|
|
132
|
+
GHC floats a benchmark loop's body out of the loop when it doesn't depend on the
|
|
133
|
+
iteration, so the run measures a single iteration. Vary the input per iteration,
|
|
134
|
+
or force the result with `Control.DeepSeq.deepseq`.
|
package/docs/languages/java.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Java/Kotlin
|
|
1
|
+
# Java/Kotlin/Groovy
|
|
2
2
|
|
|
3
|
-
Java and
|
|
3
|
+
Java, Kotlin, and Groovy profiling works with any JVM language, using
|
|
4
4
|
[Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) (JFR),
|
|
5
5
|
built into the JDK since JDK 11, or
|
|
6
6
|
[async-profiler](https://github.com/async-profiler/async-profiler), which also
|
|
@@ -24,7 +24,7 @@ jfr summary cpu.jfr
|
|
|
24
24
|
#### CLI
|
|
25
25
|
|
|
26
26
|
```sh
|
|
27
|
-
# Attach to a running JVM (
|
|
27
|
+
# Attach to a running JVM (the .jfr extension selects the JFR format)
|
|
28
28
|
asprof -e cpu -d 30 -f cpu.jfr <pid>
|
|
29
29
|
|
|
30
30
|
# Or write collapsed stacks
|
|
@@ -55,9 +55,9 @@ waiting. Useful for I/O-bound or latency-sensitive code.
|
|
|
55
55
|
|
|
56
56
|
### Java Flight Recorder
|
|
57
57
|
|
|
58
|
-
JFR has no wall-clock sampler, so this metric is async-profiler only.
|
|
59
|
-
record specific waiting events, such as `jdk.ThreadPark`,
|
|
60
|
-
below.
|
|
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`, through the lock
|
|
60
|
+
recipe below.
|
|
61
61
|
|
|
62
62
|
### async-profiler
|
|
63
63
|
|
|
@@ -65,20 +65,24 @@ below.)
|
|
|
65
65
|
asprof -e wall -d 30 -f wall.jfr <pid>
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
Recorded as `profiler.WallClockSample` events.
|
|
69
|
-
|
|
70
|
-
|
|
68
|
+
Recorded as `profiler.WallClockSample` events. To record wall-clock samples
|
|
69
|
+
alongside another event, pass the interval through `--wall` rather than
|
|
70
|
+
`-e wall`, which async-profiler rejects in combination with a second event:
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
asprof -e cpu --wall 100ms -d 30 -f combined.jfr <pid>
|
|
74
|
+
```
|
|
71
75
|
|
|
72
76
|
## Memory profiling
|
|
73
77
|
|
|
74
78
|
Samples memory allocations, in allocated bytes. async-profiler offers three
|
|
75
79
|
variants; JFR offers two:
|
|
76
80
|
|
|
77
|
-
- **heap allocations**: every heap allocation sampled since profiling started
|
|
81
|
+
- **heap allocations**: every heap allocation sampled since profiling started,
|
|
78
82
|
useful for finding allocation hot spots and reducing GC pressure
|
|
79
|
-
- **live heap**: only allocations whose objects are still live at the end
|
|
83
|
+
- **live heap**: only allocations whose objects are still live at the end,
|
|
80
84
|
useful for finding leaks
|
|
81
|
-
- **native memory**: off-heap `malloc`/`free
|
|
85
|
+
- **native memory**: off-heap `malloc`/`free`, useful for finding native leaks
|
|
82
86
|
(async-profiler only)
|
|
83
87
|
|
|
84
88
|
### Java Flight Recorder
|
|
@@ -111,6 +115,50 @@ asprof -e nativemem -d 30 -f native.jfr <pid>
|
|
|
111
115
|
`--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
|
|
112
116
|
heap and native variants.
|
|
113
117
|
|
|
118
|
+
## Heap dumps
|
|
119
|
+
|
|
120
|
+
Captures every live object on the heap, with the references between them. Useful
|
|
121
|
+
for finding what a leak retains, which the allocation profiles above don't
|
|
122
|
+
record. The JVM writes the dump in the HPROF format.
|
|
123
|
+
|
|
124
|
+
### CLI
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
# Attach to a running JVM (live objects only, after a full GC)
|
|
128
|
+
jcmd <pid> GC.heap_dump -all=false heap.hprof
|
|
129
|
+
|
|
130
|
+
# Or with jmap
|
|
131
|
+
jmap -dump:live,format=b,file=heap.hprof <pid>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### On out of memory
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=heap.hprof -jar app.jar
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
#### Flags
|
|
141
|
+
|
|
142
|
+
| Flag | Default | Description |
|
|
143
|
+
| --------------------------------- | ----------------- | ---------------------------------------------------- |
|
|
144
|
+
| `-XX:+HeapDumpOnOutOfMemoryError` | off | Dump the heap when the JVM throws `OutOfMemoryError` |
|
|
145
|
+
| `-XX:HeapDumpPath=<path>` | working directory | File or directory the dump is written to |
|
|
146
|
+
|
|
147
|
+
### Programmatic API
|
|
148
|
+
|
|
149
|
+
`HotSpotDiagnosticMXBean` dumps the heap from inside the process:
|
|
150
|
+
|
|
151
|
+
```java
|
|
152
|
+
import com.sun.management.HotSpotDiagnosticMXBean;
|
|
153
|
+
import java.lang.management.ManagementFactory;
|
|
154
|
+
|
|
155
|
+
HotSpotDiagnosticMXBean diagnostics = ManagementFactory.getPlatformMXBean(
|
|
156
|
+
HotSpotDiagnosticMXBean.class);
|
|
157
|
+
|
|
158
|
+
// Code to capture...
|
|
159
|
+
diagnostics.dumpHeap("heap.hprof", /* live= */ true);
|
|
160
|
+
```
|
|
161
|
+
|
|
114
162
|
## Lock profiling
|
|
115
163
|
|
|
116
164
|
Samples contended monitor and `java.util.concurrent` locks. Useful for finding
|
|
@@ -136,8 +184,8 @@ Recorded as `profiler.NativeLock` events.
|
|
|
136
184
|
### Java Flight Recorder
|
|
137
185
|
|
|
138
186
|
The `profile` template records execution samples, allocations, locks, GC, and
|
|
139
|
-
many other JVM events at once. JFR rotates the recording into chunks as it
|
|
140
|
-
|
|
187
|
+
many other JVM events at once. JFR rotates the recording into chunks as it
|
|
188
|
+
grows. `-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold.
|
|
141
189
|
|
|
142
190
|
```sh
|
|
143
191
|
java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
|
|
@@ -154,17 +202,24 @@ dominate the recording.
|
|
|
154
202
|
asprof --all --nofree -d 30 -f all.jfr <pid>
|
|
155
203
|
```
|
|
156
204
|
|
|
157
|
-
## async-profiler flags
|
|
205
|
+
## async-profiler CLI flags
|
|
206
|
+
|
|
207
|
+
| Flag | Default | Description |
|
|
208
|
+
| ------- | ------------------ | ------------------------------------------------------------ |
|
|
209
|
+
| `-e` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock`, and others |
|
|
210
|
+
| `-d` | — | Duration in seconds |
|
|
211
|
+
| `-o` | the `-f` extension | Output format (`jfr`, `collapsed`, `flamegraph`, and others) |
|
|
212
|
+
| `-f` | — | Output file path |
|
|
213
|
+
| `-i` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
|
|
214
|
+
| `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
|
|
215
|
+
| `<pid>` | — | Target JVM PID, `jps`, or the application name |
|
|
216
|
+
|
|
217
|
+
`-o` overrides the format the `-f` filename's extension selects. A run with
|
|
218
|
+
neither writes a text summary.
|
|
219
|
+
|
|
220
|
+
## Tips
|
|
158
221
|
|
|
159
|
-
|
|
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 |
|
|
222
|
+
### Platforms
|
|
168
223
|
|
|
169
|
-
|
|
170
|
-
|
|
224
|
+
The default `cpu` event works on macOS, where it samples CPU time through a
|
|
225
|
+
timer. Hardware events such as `cache-misses` require Linux `perf_events`.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# JavaScript
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
JavaScript profiling uses the profilers built into Node.js, Deno, Bun, Chrome
|
|
4
|
+
DevTools, and Safari's Web Inspector, which capture CPU profiles, heap profiles,
|
|
5
|
+
and heap snapshots in the V8 and JavaScriptCore formats.
|
|
5
6
|
|
|
6
7
|
## CPU profiling
|
|
7
8
|
|
|
@@ -22,12 +23,16 @@ bun --cpu-prof script.ts
|
|
|
22
23
|
|
|
23
24
|
#### Flags
|
|
24
25
|
|
|
25
|
-
| Flag | Default
|
|
26
|
-
| -------------------------- |
|
|
27
|
-
| `--cpu-prof` | —
|
|
28
|
-
| `--cpu-prof-interval=<µs>` | `1000`
|
|
29
|
-
| `--cpu-prof-dir=<dir>` | `.`
|
|
30
|
-
| `--cpu-prof-name=<name>` |
|
|
26
|
+
| Flag | Default | Description |
|
|
27
|
+
| -------------------------- | --------- | ------------------------------------ |
|
|
28
|
+
| `--cpu-prof` | — | Write a CPU profile on exit when set |
|
|
29
|
+
| `--cpu-prof-interval=<µs>` | `1000` | Sampling interval in microseconds |
|
|
30
|
+
| `--cpu-prof-dir=<dir>` | `.` | Directory for the profile |
|
|
31
|
+
| `--cpu-prof-name=<name>` | see below | Filename for the profile |
|
|
32
|
+
|
|
33
|
+
Node.js names the profile
|
|
34
|
+
`CPU.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.cpuprofile`, and Deno and Bun name it
|
|
35
|
+
`CPU.<timestamp>.<pid>.cpuprofile`.
|
|
31
36
|
|
|
32
37
|
### Programmatic API
|
|
33
38
|
|
|
@@ -66,12 +71,15 @@ node --heap-prof script.js
|
|
|
66
71
|
|
|
67
72
|
#### Flags
|
|
68
73
|
|
|
69
|
-
| Flag | Default
|
|
70
|
-
| ------------------------------ |
|
|
71
|
-
| `--heap-prof` | —
|
|
72
|
-
| `--heap-prof-interval=<bytes>` | `524288`
|
|
73
|
-
| `--heap-prof-dir=<dir>` | `.`
|
|
74
|
-
| `--heap-prof-name=<name>` |
|
|
74
|
+
| Flag | Default | Description |
|
|
75
|
+
| ------------------------------ | --------- | ------------------------------------------- |
|
|
76
|
+
| `--heap-prof` | — | Write a heap profile on exit when set |
|
|
77
|
+
| `--heap-prof-interval=<bytes>` | `524288` | Sampling interval in bytes (default 512 KB) |
|
|
78
|
+
| `--heap-prof-dir=<dir>` | `.` | Directory for the profile |
|
|
79
|
+
| `--heap-prof-name=<name>` | see below | Filename for the profile |
|
|
80
|
+
|
|
81
|
+
Node.js names the profile
|
|
82
|
+
`Heap.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.heapprofile`.
|
|
75
83
|
|
|
76
84
|
### Programmatic API
|
|
77
85
|
|
|
@@ -82,13 +90,11 @@ import { Session } from 'node:inspector/promises'
|
|
|
82
90
|
const session = new Session()
|
|
83
91
|
session.connect()
|
|
84
92
|
await session.post(`HeapProfiler.enable`)
|
|
85
|
-
await session.post(`HeapProfiler.
|
|
86
|
-
samplingInterval: 524_288,
|
|
87
|
-
})
|
|
93
|
+
await session.post(`HeapProfiler.startSampling`, { samplingInterval: 524_288 })
|
|
88
94
|
|
|
89
95
|
// Code to profile...
|
|
90
96
|
|
|
91
|
-
const { profile } = await session.post(`HeapProfiler.
|
|
97
|
+
const { profile } = await session.post(`HeapProfiler.stopSampling`)
|
|
92
98
|
writeFileSync(`heap.heapprofile`, JSON.stringify(profile))
|
|
93
99
|
```
|
|
94
100
|
|
|
@@ -104,7 +110,7 @@ memory leaks.
|
|
|
104
110
|
node --heapsnapshot-near-heap-limit=1 script.js
|
|
105
111
|
|
|
106
112
|
# Trigger on signal
|
|
107
|
-
node --heapsnapshot-signal=
|
|
113
|
+
node --heapsnapshot-signal=SIGUSR2 script.js # then: kill -USR2 <pid>
|
|
108
114
|
|
|
109
115
|
# Bun (on exit)
|
|
110
116
|
bun --heap-prof script.ts
|
|
@@ -115,15 +121,15 @@ bun --heap-prof script.ts
|
|
|
115
121
|
| Flag | Default | Description |
|
|
116
122
|
| ------------------------------------ | ------- | ---------------------------------------------------------- |
|
|
117
123
|
| `--heapsnapshot-near-heap-limit=<n>` | — | Write up to n snapshots when the heap approaches its limit |
|
|
118
|
-
| `--heapsnapshot-signal=<signal>` | — | Signal that triggers a snapshot on demand (e.g. `
|
|
124
|
+
| `--heapsnapshot-signal=<signal>` | — | Signal that triggers a snapshot on demand (e.g. `SIGUSR2`) |
|
|
119
125
|
|
|
120
126
|
#### Bun flags
|
|
121
127
|
|
|
122
|
-
| Flag | Default | Description
|
|
123
|
-
| ------------------------- | ------- |
|
|
124
|
-
| `--heap-prof` | — | Write a heap snapshot on exit
|
|
125
|
-
| `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot
|
|
126
|
-
| `--heap-prof-name=<name>` | — | Filename for the snapshot
|
|
128
|
+
| Flag | Default | Description |
|
|
129
|
+
| ------------------------- | ------- | -------------------------------------- |
|
|
130
|
+
| `--heap-prof` | — | Write a heap snapshot on exit when set |
|
|
131
|
+
| `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot |
|
|
132
|
+
| `--heap-prof-name=<name>` | — | Filename for the snapshot |
|
|
127
133
|
|
|
128
134
|
### Programmatic API
|
|
129
135
|
|
|
@@ -139,7 +145,7 @@ writeHeapSnapshot(`heap.heapsnapshot`)
|
|
|
139
145
|
|
|
140
146
|
Bun also offers
|
|
141
147
|
[`Bun.generateHeapSnapshot()`](https://bun.com/reference/bun/generateHeapSnapshot),
|
|
142
|
-
which emits
|
|
148
|
+
which emits both heap snapshot formats, selectable by argument:
|
|
143
149
|
|
|
144
150
|
```js
|
|
145
151
|
import { generateHeapSnapshot } from 'bun'
|
|
@@ -212,7 +218,7 @@ deno run --inspect script.ts
|
|
|
212
218
|
|
|
213
219
|
| Flag | Description |
|
|
214
220
|
| ------------------------------ | ----------------------------------------------------------- |
|
|
215
|
-
| `--inspect[=<host:port>]` | Start the inspector
|
|
221
|
+
| `--inspect[=<host:port>]` | Start the inspector and run the code immediately |
|
|
216
222
|
| `--inspect-wait[=<host:port>]` | Wait for a debugger to attach before running |
|
|
217
223
|
| `--inspect-brk[=<host:port>]` | Wait for a debugger to attach, then break on the first line |
|
|
218
224
|
|
package/docs/languages/julia.md
CHANGED
|
@@ -20,14 +20,15 @@ Profile.clear()
|
|
|
20
20
|
@profile my_function()
|
|
21
21
|
|
|
22
22
|
# `web = false` skips the UI. `from_c = false` drops C/runtime frames, leaving
|
|
23
|
-
#
|
|
23
|
+
# your Julia code.
|
|
24
24
|
pprof(out = "cpu.pb.gz", web = false, from_c = false)
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
###
|
|
27
|
+
### `Profile.init` options
|
|
28
28
|
|
|
29
|
-
Samples every 1 ms by default (10 ms on Windows). Configure with
|
|
30
|
-
before profiling
|
|
29
|
+
Samples every 1 ms by default (10 ms on 32-bit Windows). Configure with
|
|
30
|
+
`Profile.init` before profiling. Calling it with no arguments returns the
|
|
31
|
+
current settings.
|
|
31
32
|
|
|
32
33
|
```julia
|
|
33
34
|
Profile.init(n = 10^7, delay = 0.0005)
|
|
@@ -35,7 +36,7 @@ Profile.init(n = 10^7, delay = 0.0005)
|
|
|
35
36
|
|
|
36
37
|
| Option | Default | Description |
|
|
37
38
|
| ------- | ------- | --------------------------------------------------- |
|
|
38
|
-
| `n` | `10^
|
|
39
|
+
| `n` | `10^7` | Buffer capacity in instruction pointers, per thread |
|
|
39
40
|
| `delay` | `0.001` | Seconds between samples |
|
|
40
41
|
|
|
41
42
|
If profiling warns that the buffer filled up, increase `n` or `delay` and
|
|
@@ -101,7 +102,7 @@ using Profile
|
|
|
101
102
|
Profile.take_heap_snapshot("heap.heapsnapshot")
|
|
102
103
|
```
|
|
103
104
|
|
|
104
|
-
###
|
|
105
|
+
### `take_heap_snapshot` options
|
|
105
106
|
|
|
106
107
|
| Option | Default | Description |
|
|
107
108
|
| ------------- | ------- | ------------------------------------------------------------------------ |
|
|
@@ -110,24 +111,26 @@ Profile.take_heap_snapshot("heap.heapsnapshot")
|
|
|
110
111
|
|
|
111
112
|
A snapshot spans the entire runtime heap: `Base`, method tables, and every
|
|
112
113
|
loaded package. Expect files of hundreds of megabytes even for small programs.
|
|
113
|
-
They compress well
|
|
114
|
+
They compress well, and profiler-md accepts them gzipped as-is. For
|
|
114
115
|
memory-constrained processes, pass `streaming = true` and reassemble afterwards
|
|
115
116
|
with `Profile.HeapSnapshot.assemble_snapshot(prefix, "heap.heapsnapshot")`.
|
|
116
117
|
|
|
117
118
|
## `pprof` options
|
|
118
119
|
|
|
119
|
-
| Option | Default | Description
|
|
120
|
-
| ----------------- | ----------------- |
|
|
121
|
-
| `out` | `"profile.pb.gz"` | Output file path
|
|
122
|
-
| `web` | `true` | Launch the interactive web UI after exporting
|
|
123
|
-
| `from_c` | `true` | Include C and Julia runtime frames
|
|
124
|
-
| `drop_frames` | `
|
|
125
|
-
| `keep_frames` | `
|
|
126
|
-
| `full_signatures` | `true` | Use full method signatures as function names
|
|
120
|
+
| Option | Default | Description |
|
|
121
|
+
| ----------------- | ----------------- | ------------------------------------------------------------------- |
|
|
122
|
+
| `out` | `"profile.pb.gz"` | Output file path (`"alloc-profile.pb.gz"` for `PProf.Allocs.pprof`) |
|
|
123
|
+
| `web` | `true` | Launch the interactive web UI after exporting |
|
|
124
|
+
| `from_c` | `true` | Include C and Julia runtime frames |
|
|
125
|
+
| `drop_frames` | `nothing` | Regex of function names to drop from stacks |
|
|
126
|
+
| `keep_frames` | `nothing` | Regex of function names to keep despite dropping |
|
|
127
|
+
| `full_signatures` | `true` | Use full method signatures as function names |
|
|
127
128
|
|
|
128
129
|
## Tips
|
|
129
130
|
|
|
131
|
+
### Threads
|
|
132
|
+
|
|
130
133
|
Run single-threaded (`julia -t 1 --gcthreads=1`). Otherwise idle GC and
|
|
131
|
-
scheduler threads fill the profile with wait frames (`__psynch_cvwait`)
|
|
132
|
-
wall-time profiler
|
|
133
|
-
|
|
134
|
+
scheduler threads fill the profile with wait frames (`__psynch_cvwait`). The
|
|
135
|
+
wall-time profiler records more of those idle tasks, because it samples tasks
|
|
136
|
+
that are blocked as well as running ones.
|
package/docs/languages/php.md
CHANGED
|
@@ -4,10 +4,17 @@ PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
|
|
|
4
4
|
extension. Excimer samples from a PHP-controlled timer, so you start and stop it
|
|
5
5
|
within the program or a prepended bootstrap script.
|
|
6
6
|
|
|
7
|
+
A new `ExcimerProfiler` samples wall-clock time every 0.1 seconds, so the
|
|
8
|
+
recipes below set the event type and the period.
|
|
9
|
+
|
|
7
10
|
## CPU profiling
|
|
8
11
|
|
|
9
12
|
Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
10
13
|
|
|
14
|
+
Excimer defines `EXCIMER_CPU` only where POSIX timers provide a CPU clock, so
|
|
15
|
+
the constant is undefined on macOS, where Excimer uses kqueue instead. Check
|
|
16
|
+
with `defined('EXCIMER_CPU')` and fall back to wall-clock profiling.
|
|
17
|
+
|
|
11
18
|
```php
|
|
12
19
|
<?php
|
|
13
20
|
$prof = new ExcimerProfiler();
|
package/docs/languages/python.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Python
|
|
2
2
|
|
|
3
|
-
Python profiling uses [py-spy](https://github.com/benfred/py-spy)
|
|
3
|
+
Python profiling uses [py-spy](https://github.com/benfred/py-spy),
|
|
4
|
+
[pyinstrument](https://github.com/joerick/pyinstrument),
|
|
5
|
+
[memray](https://github.com/bloomberg/memray), or
|
|
4
6
|
[systing](https://github.com/josefbacik/systing).
|
|
5
7
|
|
|
6
8
|
## CPU profiling
|
|
@@ -43,23 +45,112 @@ py-spy dump --pid <pid>
|
|
|
43
45
|
py-spy dump --pid <pid> --locals
|
|
44
46
|
```
|
|
45
47
|
|
|
46
|
-
## CLI flags
|
|
48
|
+
## py-spy CLI flags
|
|
47
49
|
|
|
48
|
-
| Flag | Default | Description
|
|
49
|
-
| ------------------- | ------------ |
|
|
50
|
-
| `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`
|
|
51
|
-
| `-o` / `--output` | — | Output file path
|
|
52
|
-
| `-d` / `--duration` | — | Duration in seconds (default: until program exits)
|
|
53
|
-
| `-r` / `--rate` | `100` | Sampling rate in Hz
|
|
54
|
-
| `--idle` | off | Include stack traces for idle (sleeping/waiting) threads
|
|
55
|
-
| `--native` | off | Profile native Cython or C extensions
|
|
56
|
-
| `--nonblocking` | off | Sample without pausing the process (less accurate)
|
|
57
|
-
| `--subprocesses` | off | Also profile subprocesses of the target
|
|
50
|
+
| Flag | Default | Description |
|
|
51
|
+
| ------------------- | ------------ | --------------------------------------------------------------- |
|
|
52
|
+
| `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`, `chrometrace` |
|
|
53
|
+
| `-o` / `--output` | — | Output file path |
|
|
54
|
+
| `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
|
|
55
|
+
| `-r` / `--rate` | `100` | Sampling rate in Hz |
|
|
56
|
+
| `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
|
|
57
|
+
| `--native` | off | Profile native Cython or C extensions |
|
|
58
|
+
| `--nonblocking` | off | Sample without pausing the process (less accurate) |
|
|
59
|
+
| `--subprocesses` | off | Also profile subprocesses of the target |
|
|
60
|
+
|
|
61
|
+
## In-process wall-clock profiling
|
|
62
|
+
|
|
63
|
+
Samples wall-clock time rather than CPU time, from inside the interpreter rather
|
|
64
|
+
than through ptrace. Useful for I/O-bound or latency-sensitive code.
|
|
65
|
+
|
|
66
|
+
[pyinstrument](https://github.com/joerick/pyinstrument) samples the call stack
|
|
67
|
+
from inside the interpreter, so it needs no ptrace access. Its speedscope
|
|
68
|
+
renderer writes a format this tool reads.
|
|
69
|
+
|
|
70
|
+
### CLI
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
# Profile a script
|
|
74
|
+
pyinstrument -r speedscope -o profile.speedscope.json script.py
|
|
75
|
+
|
|
76
|
+
# Profile a console script, such as the one an installed package provides
|
|
77
|
+
pyinstrument -r speedscope -o profile.speedscope.json "$(which black)" file.py
|
|
78
|
+
|
|
79
|
+
# Keep every frame instead of those above the 1% threshold
|
|
80
|
+
pyinstrument --show-all -r speedscope -o profile.speedscope.json script.py
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Run a console script by its path rather than as `python -m package`. Under `-m`,
|
|
84
|
+
pyinstrument trims the leading `runpy` frames by descending into the first child
|
|
85
|
+
of each. That child is the import subtree rather than the module body, so the
|
|
86
|
+
export covers only the imports. `--show-all` can trim the run the same way.
|
|
87
|
+
|
|
88
|
+
By default the export keeps the frames above 1% of the total and folds the rest
|
|
89
|
+
into the self time of the frame that called them.
|
|
90
|
+
|
|
91
|
+
#### Flags
|
|
92
|
+
|
|
93
|
+
| Flag | Default | Description |
|
|
94
|
+
| --------------------- | --------- | ------------------------------------------------------------- |
|
|
95
|
+
| `-r` / `--renderer` | see below | Output format. `speedscope` writes the format this tool reads |
|
|
96
|
+
| `-o` / `--outfile` | — | Output file path |
|
|
97
|
+
| `-m` | — | Run a library module as a script |
|
|
98
|
+
| `-i` / `--interval` | `0.001` | Minimum seconds between stack samples |
|
|
99
|
+
| `--show-all` | off | Keep every frame, including the standard library's |
|
|
100
|
+
| `--hide` | — | Glob matching the file paths whose frames to hide |
|
|
101
|
+
| `-t` / `--timeline` | off | Keep call ordering instead of condensing repeated calls |
|
|
102
|
+
| `--use-timing-thread` | off | Time the sampling interval on a separate thread |
|
|
103
|
+
|
|
104
|
+
Without `-r`, pyinstrument picks the renderer from the `-o` filename's
|
|
105
|
+
extension, and writes text when there is no `-o`.
|
|
106
|
+
|
|
107
|
+
## Memory profiling
|
|
108
|
+
|
|
109
|
+
Traces every allocation with the Python call stack it came from. Useful for
|
|
110
|
+
finding where memory was held when the program's memory use was highest, and
|
|
111
|
+
what it never freed.
|
|
112
|
+
|
|
113
|
+
[memray](https://github.com/bloomberg/memray) traces the allocations the
|
|
114
|
+
interpreter makes, from inside the process.
|
|
115
|
+
|
|
116
|
+
### CLI
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
# Trace a script's allocations
|
|
120
|
+
memray run -o memory.bin script.py
|
|
121
|
+
|
|
122
|
+
# Trace a module, as `python -m` would run it
|
|
123
|
+
memray run -o memory.bin -m black file.py
|
|
124
|
+
|
|
125
|
+
# Keep per-stack totals only, for a smaller capture of a long run
|
|
126
|
+
memray run --aggregate -o memory.bin script.py
|
|
127
|
+
|
|
128
|
+
# Attach to a running process
|
|
129
|
+
memray attach --duration 60 -o memory.bin <pid>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Tracing from inside the process makes the program run several times slower, so
|
|
133
|
+
profile a workload small enough to finish with tracing on.
|
|
134
|
+
|
|
135
|
+
#### Flags
|
|
136
|
+
|
|
137
|
+
| Flag | Default | Description |
|
|
138
|
+
| --------------------------- | -------------------------- | ------------------------------------------------------------------- |
|
|
139
|
+
| `-o` / `--output` | `<process_name>.<pid>.bin` | Output file path |
|
|
140
|
+
| `-f` / `--force` | off | Overwrite the output file if it exists |
|
|
141
|
+
| `--aggregate` | off | Record each stack's totals instead of every allocation |
|
|
142
|
+
| `--native` | off | Also record C/C++ frames, which this tool skips |
|
|
143
|
+
| `--trace-python-allocators` | off | Record pymalloc's own allocations as well as the ones underneath it |
|
|
144
|
+
| `--follow-fork` | off | Also trace child processes, each into its own capture |
|
|
145
|
+
| `--no-compress` | off | Write the capture uncompressed rather than LZ4 compressed |
|
|
58
146
|
|
|
59
147
|
## System profiling
|
|
60
148
|
|
|
61
|
-
|
|
62
|
-
|
|
149
|
+
Samples on-CPU stacks and records a stack each time a thread sleeps. Useful for
|
|
150
|
+
costs outside the process: off-CPU waits, syscall time, and contention across
|
|
151
|
+
the whole node.
|
|
152
|
+
|
|
153
|
+
[systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler. With
|
|
63
154
|
`--collect-pystacks` it walks CPython interpreter frames and blends them with
|
|
64
155
|
the native stack, so profiles show Python functions alongside the C and kernel
|
|
65
156
|
frames beneath them. It needs root (BPF) and a kernel with BTF
|