profiler-md 0.6.0 → 0.8.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 +12953 -4258
- package/dist/index.d.mts +1182 -435
- 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 +43 -25
- package/docs/languages/julia.md +21 -18
- package/docs/languages/php.md +19 -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 +302 -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
|
|
|
@@ -57,6 +62,14 @@ and reducing GC pressure.
|
|
|
57
62
|
`bun --heap-prof` generates a V8 heap _snapshot_ on exit, not a heap _profile_.
|
|
58
63
|
Deno has no equivalent.
|
|
59
64
|
|
|
65
|
+
The profiler reports only the sampled objects still alive when the profile is
|
|
66
|
+
written, so a workload that frees most of what it allocates leaves few samples.
|
|
67
|
+
`HeapProfiler.startSampling` takes `includeObjectsCollectedByMajorGC` and
|
|
68
|
+
`includeObjectsCollectedByMinorGC`, which keep the objects a major or a minor
|
|
69
|
+
garbage collection freed. Set both to profile allocation hot spots, and leave
|
|
70
|
+
them off to profile what stays in memory. `--heap-prof` sets neither and has no
|
|
71
|
+
flag for them, so use the programmatic API to set them.
|
|
72
|
+
|
|
60
73
|
### CLI
|
|
61
74
|
|
|
62
75
|
```sh
|
|
@@ -66,12 +79,15 @@ node --heap-prof script.js
|
|
|
66
79
|
|
|
67
80
|
#### Flags
|
|
68
81
|
|
|
69
|
-
| Flag | Default
|
|
70
|
-
| ------------------------------ |
|
|
71
|
-
| `--heap-prof` | —
|
|
72
|
-
| `--heap-prof-interval=<bytes>` | `524288`
|
|
73
|
-
| `--heap-prof-dir=<dir>` | `.`
|
|
74
|
-
| `--heap-prof-name=<name>` |
|
|
82
|
+
| Flag | Default | Description |
|
|
83
|
+
| ------------------------------ | --------- | ------------------------------------------- |
|
|
84
|
+
| `--heap-prof` | — | Write a heap profile on exit when set |
|
|
85
|
+
| `--heap-prof-interval=<bytes>` | `524288` | Sampling interval in bytes (default 512 KB) |
|
|
86
|
+
| `--heap-prof-dir=<dir>` | `.` | Directory for the profile |
|
|
87
|
+
| `--heap-prof-name=<name>` | see below | Filename for the profile |
|
|
88
|
+
|
|
89
|
+
Node.js names the profile
|
|
90
|
+
`Heap.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.heapprofile`.
|
|
75
91
|
|
|
76
92
|
### Programmatic API
|
|
77
93
|
|
|
@@ -82,13 +98,15 @@ import { Session } from 'node:inspector/promises'
|
|
|
82
98
|
const session = new Session()
|
|
83
99
|
session.connect()
|
|
84
100
|
await session.post(`HeapProfiler.enable`)
|
|
85
|
-
await session.post(`HeapProfiler.
|
|
101
|
+
await session.post(`HeapProfiler.startSampling`, {
|
|
86
102
|
samplingInterval: 524_288,
|
|
103
|
+
includeObjectsCollectedByMajorGC: true,
|
|
104
|
+
includeObjectsCollectedByMinorGC: true,
|
|
87
105
|
})
|
|
88
106
|
|
|
89
107
|
// Code to profile...
|
|
90
108
|
|
|
91
|
-
const { profile } = await session.post(`HeapProfiler.
|
|
109
|
+
const { profile } = await session.post(`HeapProfiler.stopSampling`)
|
|
92
110
|
writeFileSync(`heap.heapprofile`, JSON.stringify(profile))
|
|
93
111
|
```
|
|
94
112
|
|
|
@@ -104,7 +122,7 @@ memory leaks.
|
|
|
104
122
|
node --heapsnapshot-near-heap-limit=1 script.js
|
|
105
123
|
|
|
106
124
|
# Trigger on signal
|
|
107
|
-
node --heapsnapshot-signal=
|
|
125
|
+
node --heapsnapshot-signal=SIGUSR2 script.js # then: kill -USR2 <pid>
|
|
108
126
|
|
|
109
127
|
# Bun (on exit)
|
|
110
128
|
bun --heap-prof script.ts
|
|
@@ -115,15 +133,15 @@ bun --heap-prof script.ts
|
|
|
115
133
|
| Flag | Default | Description |
|
|
116
134
|
| ------------------------------------ | ------- | ---------------------------------------------------------- |
|
|
117
135
|
| `--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. `
|
|
136
|
+
| `--heapsnapshot-signal=<signal>` | — | Signal that triggers a snapshot on demand (e.g. `SIGUSR2`) |
|
|
119
137
|
|
|
120
138
|
#### Bun flags
|
|
121
139
|
|
|
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
|
|
140
|
+
| Flag | Default | Description |
|
|
141
|
+
| ------------------------- | ------- | -------------------------------------- |
|
|
142
|
+
| `--heap-prof` | — | Write a heap snapshot on exit when set |
|
|
143
|
+
| `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot |
|
|
144
|
+
| `--heap-prof-name=<name>` | — | Filename for the snapshot |
|
|
127
145
|
|
|
128
146
|
### Programmatic API
|
|
129
147
|
|
|
@@ -139,7 +157,7 @@ writeHeapSnapshot(`heap.heapsnapshot`)
|
|
|
139
157
|
|
|
140
158
|
Bun also offers
|
|
141
159
|
[`Bun.generateHeapSnapshot()`](https://bun.com/reference/bun/generateHeapSnapshot),
|
|
142
|
-
which emits
|
|
160
|
+
which emits both heap snapshot formats, selectable by argument:
|
|
143
161
|
|
|
144
162
|
```js
|
|
145
163
|
import { generateHeapSnapshot } from 'bun'
|
|
@@ -212,7 +230,7 @@ deno run --inspect script.ts
|
|
|
212
230
|
|
|
213
231
|
| Flag | Description |
|
|
214
232
|
| ------------------------------ | ----------------------------------------------------------- |
|
|
215
|
-
| `--inspect[=<host:port>]` | Start the inspector
|
|
233
|
+
| `--inspect[=<host:port>]` | Start the inspector and run the code immediately |
|
|
216
234
|
| `--inspect-wait[=<host:port>]` | Wait for a debugger to attach before running |
|
|
217
235
|
| `--inspect-brk[=<host:port>]` | Wait for a debugger to attach, then break on the first line |
|
|
218
236
|
|
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();
|
|
@@ -63,6 +70,17 @@ register_shutdown_function(function () use ($prof) {
|
|
|
63
70
|
php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optimize
|
|
64
71
|
```
|
|
65
72
|
|
|
73
|
+
## Output formats
|
|
74
|
+
|
|
75
|
+
`getSpeedscopeData()` writes the sampled time alongside each frame's file, and
|
|
76
|
+
`formatCollapsed()` writes sample counts with each frame's file packed into its
|
|
77
|
+
name. Prefer speedscope, because a collapsed frame names a method by its
|
|
78
|
+
declaring class rather than its file.
|
|
79
|
+
|
|
80
|
+
```php
|
|
81
|
+
file_put_contents('wall.collapsed', $prof->getLog()->formatCollapsed());
|
|
82
|
+
```
|
|
83
|
+
|
|
66
84
|
## API
|
|
67
85
|
|
|
68
86
|
| Method | Description |
|
|
@@ -72,3 +90,4 @@ php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optim
|
|
|
72
90
|
| `setMaxDepth($depth)` | Maximum stack frames per sample |
|
|
73
91
|
| `start()` / `stop()` | Begin and end profiling |
|
|
74
92
|
| `getLog()->getSpeedscopeData()` | The collected profile as Speedscope-format data |
|
|
93
|
+
| `getLog()->formatCollapsed()` | The collected profile as collapsed stacks |
|