profiler-md 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/index.mjs +14155 -5081
- package/dist/index.d.mts +1312 -263
- 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 +3 -3
- package/docs/formats/jsc-heap-snapshot.md +11 -5
- package/docs/formats/memray.md +30 -0
- package/docs/formats/perf.md +74 -0
- package/docs/formats/pprof.md +10 -6
- package/docs/formats/speedscope.md +7 -5
- package/docs/formats/systing.md +27 -0
- 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 +10 -5
- package/docs/formats/webkit-timeline-recording.md +6 -0
- package/docs/languages/c.md +138 -18
- package/docs/languages/csharp.md +7 -7
- package/docs/languages/elixir.md +22 -15
- package/docs/languages/fortran.md +141 -0
- package/docs/languages/go.md +36 -13
- package/docs/languages/haskell.md +134 -0
- package/docs/languages/java.md +89 -34
- package/docs/languages/javascript.md +37 -31
- package/docs/languages/julia.md +96 -14
- package/docs/languages/php.md +10 -4
- package/docs/languages/python.md +121 -15
- package/docs/languages/ruby.md +19 -22
- package/docs/languages/rust.md +40 -10
- package/docs/languages/swift.md +135 -0
- package/docs/languages/zig.md +155 -0
- package/package.json +47 -46
- package/readme.md +306 -242
- package/skills/profile-optimize/SKILL.md +162 -0
- package/docs/languages/cpp.md +0 -160
- package/docs/languages/erlang.md +0 -46
- package/docs/languages/fsharp.md +0 -52
- package/docs/languages/kotlin.md +0 -170
- package/docs/languages/typescript.md +0 -276
- 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/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/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,21 +1,21 @@
|
|
|
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
|
-
[async-profiler](https://github.com/async-profiler/async-profiler),
|
|
7
|
-
|
|
8
|
-
older JDKs.
|
|
6
|
+
[async-profiler](https://github.com/async-profiler/async-profiler), which also
|
|
7
|
+
resolves native frames and works on older JDKs.
|
|
9
8
|
|
|
10
9
|
## CPU profiling
|
|
11
10
|
|
|
12
11
|
Periodically samples the call stack while on CPU. Useful for finding CPU hot
|
|
13
|
-
spots. Recorded as `jdk.ExecutionSample` events.
|
|
12
|
+
spots. Recorded as `jdk.ExecutionSample` events, plus `jdk.NativeMethodSample`
|
|
13
|
+
events for threads running native methods.
|
|
14
14
|
|
|
15
15
|
### Java Flight Recorder
|
|
16
16
|
|
|
17
17
|
```sh
|
|
18
|
-
java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms -jar app.jar
|
|
18
|
+
java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms,+jdk.NativeMethodSample#enabled=true,+jdk.NativeMethodSample#period=10ms -jar app.jar
|
|
19
19
|
jfr summary cpu.jfr
|
|
20
20
|
```
|
|
21
21
|
|
|
@@ -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
|
-
|
|
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 @@ record specific waiting events, such as `jdk.ThreadPark` and
|
|
|
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
|
|
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
|
|
@@ -146,25 +194,32 @@ jfr summary all.jfr
|
|
|
146
194
|
|
|
147
195
|
### async-profiler
|
|
148
196
|
|
|
149
|
-
`--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock`
|
|
150
|
-
|
|
151
|
-
|
|
197
|
+
`--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock` at once.
|
|
198
|
+
Add `--nofree` to suppress the high-volume native `free` events, which otherwise
|
|
199
|
+
dominate the recording.
|
|
152
200
|
|
|
153
201
|
```sh
|
|
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,16 +23,20 @@ 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
|
|
|
34
|
-
Profile a
|
|
39
|
+
Profile a section of code rather than the whole process:
|
|
35
40
|
|
|
36
41
|
```js
|
|
37
42
|
import { writeFileSync } from 'node:fs'
|
|
@@ -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
|
|
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
|
|
|
@@ -254,10 +260,10 @@ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
|
|
|
254
260
|
### Recording
|
|
255
261
|
|
|
256
262
|
1. Click the **Timelines** tab.
|
|
257
|
-
2. Enable the instruments
|
|
258
|
-
|
|
263
|
+
2. Enable the instruments: **JavaScript & Events** (always), and optionally
|
|
264
|
+
**Memory** and **JavaScript Allocations**.
|
|
259
265
|
3. Click **Start Recording** (or ⌘R).
|
|
260
|
-
4. Reproduce the scenario
|
|
266
|
+
4. Reproduce the scenario to profile.
|
|
261
267
|
5. Click **Stop Recording**.
|
|
262
268
|
6. Click the **Export** button (arrow icon) and save as a `.json` file.
|
|
263
269
|
|
package/docs/languages/julia.md
CHANGED
|
@@ -3,52 +3,134 @@
|
|
|
3
3
|
Julia profiling uses [PProf.jl](https://github.com/JuliaPerf/PProf.jl), which
|
|
4
4
|
exports profiles collected by Julia's built-in
|
|
5
5
|
[`Profile`](https://docs.julialang.org/en/v1/manual/profile/) standard library
|
|
6
|
-
to the pprof format.
|
|
6
|
+
to the pprof format. `Profile` can also write V8 heap snapshots directly.
|
|
7
7
|
|
|
8
8
|
## CPU profiling
|
|
9
9
|
|
|
10
|
-
Periodically samples the call
|
|
10
|
+
Periodically samples the call stacks of running tasks. Useful for finding CPU
|
|
11
|
+
hot spots.
|
|
11
12
|
|
|
12
13
|
```julia
|
|
13
14
|
using Profile, PProf
|
|
14
15
|
|
|
15
|
-
# Warm up the JIT so
|
|
16
|
+
# Warm up the JIT so the profile excludes compilation.
|
|
16
17
|
my_function()
|
|
17
18
|
|
|
18
19
|
Profile.clear()
|
|
19
20
|
@profile my_function()
|
|
20
21
|
|
|
21
22
|
# `web = false` skips the UI. `from_c = false` drops C/runtime frames, leaving
|
|
22
|
-
#
|
|
23
|
+
# your Julia code.
|
|
23
24
|
pprof(out = "cpu.pb.gz", web = false, from_c = false)
|
|
24
25
|
```
|
|
25
26
|
|
|
27
|
+
### `Profile.init` options
|
|
28
|
+
|
|
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.
|
|
32
|
+
|
|
33
|
+
```julia
|
|
34
|
+
Profile.init(n = 10^7, delay = 0.0005)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
| Option | Default | Description |
|
|
38
|
+
| ------- | ------- | --------------------------------------------------- |
|
|
39
|
+
| `n` | `10^7` | Buffer capacity in instruction pointers, per thread |
|
|
40
|
+
| `delay` | `0.001` | Seconds between samples |
|
|
41
|
+
|
|
42
|
+
If profiling warns that the buffer filled up, increase `n` or `delay` and
|
|
43
|
+
re-run.
|
|
44
|
+
|
|
45
|
+
## Wall-time profiling
|
|
46
|
+
|
|
47
|
+
Periodically samples all live tasks regardless of scheduling state (Julia ≥
|
|
48
|
+
1.12). Unlike CPU profiling, it samples blocked tasks too, counting time spent
|
|
49
|
+
waiting on IO, locks, channels, and the scheduler. Useful for I/O-bound or
|
|
50
|
+
latency-sensitive code.
|
|
51
|
+
|
|
52
|
+
```julia
|
|
53
|
+
using Profile, PProf
|
|
54
|
+
|
|
55
|
+
# Warm up the JIT so the profile excludes compilation.
|
|
56
|
+
my_function()
|
|
57
|
+
|
|
58
|
+
Profile.clear()
|
|
59
|
+
Profile.@profile_walltime my_function()
|
|
60
|
+
|
|
61
|
+
# Wall-time samples land in the same buffer as `@profile`, so the same call
|
|
62
|
+
# exports them. Always `Profile.clear()` between runs so CPU and wall-time
|
|
63
|
+
# samples don't mix.
|
|
64
|
+
pprof(out = "wall.pb.gz", web = false, from_c = false)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Samples containing `failed_to_sample_task_fun` or `failed_to_stop_thread_fun`
|
|
68
|
+
indicate many short-lived tasks that completed before their backtraces could be
|
|
69
|
+
collected.
|
|
70
|
+
|
|
26
71
|
## Memory profiling
|
|
27
72
|
|
|
28
|
-
Samples heap allocations. Useful for finding allocation hot spots
|
|
29
|
-
GC pressure.
|
|
73
|
+
Samples heap allocations (Julia ≥ 1.8). Useful for finding allocation hot spots
|
|
74
|
+
and reducing GC pressure.
|
|
30
75
|
|
|
31
76
|
```julia
|
|
32
77
|
using Profile, PProf
|
|
33
78
|
|
|
34
|
-
# Warm up the JIT so
|
|
79
|
+
# Warm up the JIT so the profile excludes compilation.
|
|
35
80
|
my_function()
|
|
36
81
|
|
|
37
82
|
Profile.Allocs.clear()
|
|
38
|
-
Profile.Allocs.@profile my_function()
|
|
83
|
+
Profile.Allocs.@profile sample_rate = 0.01 my_function()
|
|
39
84
|
|
|
40
85
|
PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
|
|
41
86
|
```
|
|
42
87
|
|
|
88
|
+
`sample_rate` is the fraction of allocations recorded: `1.0` records every
|
|
89
|
+
allocation, the default `0.1` records ~10%. Allocation-heavy workloads allocate
|
|
90
|
+
millions of times, so lower the rate until the run's overhead and the profile's
|
|
91
|
+
size are reasonable.
|
|
92
|
+
|
|
93
|
+
## Heap snapshots
|
|
94
|
+
|
|
95
|
+
Captures a snapshot of all live objects on the heap (Julia ≥ 1.9), written
|
|
96
|
+
directly in the V8 heap snapshot format. Useful for diagnosing memory leaks.
|
|
97
|
+
|
|
98
|
+
```julia
|
|
99
|
+
using Profile
|
|
100
|
+
|
|
101
|
+
# Code to capture...
|
|
102
|
+
Profile.take_heap_snapshot("heap.heapsnapshot")
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### `take_heap_snapshot` options
|
|
106
|
+
|
|
107
|
+
| Option | Default | Description |
|
|
108
|
+
| ------------- | ------- | ------------------------------------------------------------------------ |
|
|
109
|
+
| `redact_data` | `true` | Omit the contents of Julia strings |
|
|
110
|
+
| `streaming` | `false` | Stream four intermediate files instead of holding the snapshot in memory |
|
|
111
|
+
|
|
112
|
+
A snapshot spans the entire runtime heap: `Base`, method tables, and every
|
|
113
|
+
loaded package. Expect files of hundreds of megabytes even for small programs.
|
|
114
|
+
They compress well, and profiler-md accepts them gzipped as-is. For
|
|
115
|
+
memory-constrained processes, pass `streaming = true` and reassemble afterwards
|
|
116
|
+
with `Profile.HeapSnapshot.assemble_snapshot(prefix, "heap.heapsnapshot")`.
|
|
117
|
+
|
|
43
118
|
## `pprof` options
|
|
44
119
|
|
|
45
|
-
| Option
|
|
46
|
-
|
|
|
47
|
-
| `out`
|
|
48
|
-
| `web`
|
|
49
|
-
| `from_c`
|
|
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 |
|
|
50
128
|
|
|
51
129
|
## Tips
|
|
52
130
|
|
|
131
|
+
### Threads
|
|
132
|
+
|
|
53
133
|
Run single-threaded (`julia -t 1 --gcthreads=1`). Otherwise idle GC and
|
|
54
|
-
scheduler threads fill the profile with wait frames (`__psynch_cvwait`).
|
|
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
|
@@ -1,14 +1,20 @@
|
|
|
1
1
|
# PHP
|
|
2
2
|
|
|
3
3
|
PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
|
|
4
|
-
extension
|
|
5
|
-
|
|
6
|
-
|
|
4
|
+
extension. Excimer samples from a PHP-controlled timer, so you start and stop it
|
|
5
|
+
within the program or a prepended bootstrap script.
|
|
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.
|
|
7
9
|
|
|
8
10
|
## CPU profiling
|
|
9
11
|
|
|
10
12
|
Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
11
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
|
+
|
|
12
18
|
```php
|
|
13
19
|
<?php
|
|
14
20
|
$prof = new ExcimerProfiler();
|
|
@@ -44,7 +50,7 @@ file_put_contents('wall.speedscope.json',
|
|
|
44
50
|
|
|
45
51
|
## Profiling an existing program
|
|
46
52
|
|
|
47
|
-
To profile a program
|
|
53
|
+
To profile a program without editing it, point `auto_prepend_file` at a
|
|
48
54
|
bootstrap script that starts the profiler and writes the result on shutdown:
|
|
49
55
|
|
|
50
56
|
```php
|