profiler-md 0.3.0 → 0.5.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 +5331 -2044
- package/dist/index.d.mts +738 -229
- package/dist/index.js +2 -2
- package/docs/formats/collapsed.md +12 -0
- package/docs/formats/jfr.md +16 -0
- package/docs/formats/jsc-heap-snapshot.md +2 -2
- package/docs/languages/c.md +31 -7
- package/docs/languages/cpp.md +160 -0
- package/docs/languages/csharp.md +52 -0
- package/docs/languages/elixir.md +46 -0
- package/docs/languages/erlang.md +46 -0
- package/docs/languages/fsharp.md +52 -0
- package/docs/languages/go.md +11 -6
- package/docs/languages/java.md +110 -57
- package/docs/languages/javascript.md +69 -12
- package/docs/languages/julia.md +54 -0
- package/docs/languages/kotlin.md +170 -0
- package/docs/languages/php.md +64 -20
- package/docs/languages/python.md +13 -68
- package/docs/languages/ruby.md +17 -27
- package/docs/languages/typescript.md +276 -0
- package/examples/output/c.gperftools.cpu.base.pprof.md +324 -0
- package/examples/output/c.gperftools.cpu.current.pprof.md +271 -0
- package/examples/output/c.gperftools.cpu.diff.pprof.md +98 -0
- package/examples/output/c.gperftools.heap.base.pprof.md +362 -0
- package/examples/output/c.gperftools.heap.current.pprof.md +362 -0
- package/examples/output/c.gperftools.heap.diff.pprof.md +28 -0
- package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
- package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
- package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
- package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
- package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
- package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
- package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
- package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
- package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
- package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
- package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
- package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
- package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
- package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
- package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
- package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
- package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
- package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
- package/examples/output/go.pprof.block.base.pprof.md +86 -0
- package/examples/output/go.pprof.block.current.pprof.md +83 -0
- package/examples/output/go.pprof.block.diff.pprof.md +42 -0
- package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
- package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
- package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
- package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
- package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
- package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
- package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
- package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
- package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
- package/examples/output/go.pprof.heap.base.pprof.md +154 -0
- package/examples/output/go.pprof.heap.current.pprof.md +146 -0
- package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
- package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
- package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
- package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
- package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
- package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
- package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
- package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
- package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
- package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
- package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
- package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
- package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
- package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
- package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
- package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
- package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
- package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
- package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
- package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
- package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
- package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
- package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
- package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
- package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
- package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
- package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
- package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
- package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
- package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
- package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
- package/examples/output/java.jdk.all.base.jfr.md +1024 -0
- package/examples/output/java.jdk.all.current.jfr.md +1010 -0
- package/examples/output/java.jdk.all.diff.jfr.md +311 -0
- package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
- package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
- package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
- package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
- package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
- package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
- package/examples/output/java.jdk.live.base.jfr.md +1029 -0
- package/examples/output/java.jdk.live.current.jfr.md +1035 -0
- package/examples/output/java.jdk.live.diff.jfr.md +289 -0
- package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
- package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
- package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
- package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
- package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
- package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
- package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
- package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
- package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
- package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
- package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
- package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
- package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
- package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
- package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
- package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
- package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
- package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
- package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
- package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
- package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
- package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
- package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
- package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
- package/examples/output/javascript.node.base.cpuprofile.md +136 -0
- package/examples/output/javascript.node.base.heapprofile.md +56 -0
- package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
- package/examples/output/javascript.node.current.cpuprofile.md +119 -0
- package/examples/output/javascript.node.current.heapprofile.md +52 -0
- package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
- package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
- package/examples/output/javascript.node.diff.heapprofile.md +34 -0
- package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
- package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
- package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
- package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
- package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
- package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
- package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
- package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
- package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
- package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
- package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
- package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
- package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
- package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
- package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
- package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
- package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
- package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
- package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
- package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
- package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
- package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
- package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
- package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
- package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
- package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
- package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
- package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
- package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
- package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
- package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
- package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
- package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
- package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
- package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
- package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
- package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
- package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
- package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
- package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
- package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
- package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
- package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
- package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
- package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
- package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
- package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
- package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
- package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
- package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
- package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
- package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
- package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
- package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
- package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
- package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
- package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
- package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
- package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
- package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
- package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
- package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
- package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
- package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
- package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
- package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
- package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
- package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
- package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
- package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
- package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
- package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
- package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
- package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
- package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
- package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
- package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
- package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
- package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
- package/package.json +27 -20
- package/readme.md +201 -87
- package/examples/bun.cpuprofile.md +0 -475
- package/examples/deno.cpuprofile.md +0 -481
- package/examples/jsc-heap-snapshot.json.md +0 -509
- package/examples/node.cpuprofile.md +0 -485
- package/examples/node.heapprofile.md +0 -281
- package/examples/node.heapsnapshot.md +0 -694
- package/examples/node.pprof.md +0 -441
- package/examples/node.speedscope.json.md +0 -408
- package/examples/rust.pprof.md +0 -477
- package/examples/webkit-timeline-recording.json.md +0 -434
package/docs/languages/java.md
CHANGED
|
@@ -1,29 +1,41 @@
|
|
|
1
1
|
# Java/Kotlin
|
|
2
2
|
|
|
3
|
-
Java and Kotlin profiling
|
|
3
|
+
Java and Kotlin profiling works with any JVM language, using either
|
|
4
|
+
[Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) (JFR),
|
|
5
|
+
built into the JDK since JDK 11, or
|
|
4
6
|
[async-profiler](https://github.com/async-profiler/async-profiler), a low
|
|
5
|
-
overhead sampling profiler that
|
|
7
|
+
overhead sampling profiler that additionally resolves native frames and works on
|
|
8
|
+
older JDKs.
|
|
6
9
|
|
|
7
10
|
## CPU profiling
|
|
8
11
|
|
|
9
|
-
Periodically samples the call stack. Useful for finding CPU hot
|
|
12
|
+
Periodically samples the call stack while on CPU. Useful for finding CPU hot
|
|
13
|
+
spots. Recorded as `jdk.ExecutionSample` events.
|
|
10
14
|
|
|
11
|
-
###
|
|
15
|
+
### Java Flight Recorder
|
|
12
16
|
|
|
13
17
|
```sh
|
|
14
|
-
#
|
|
15
|
-
|
|
18
|
+
java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms -jar app.jar
|
|
19
|
+
jfr summary cpu.jfr
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### async-profiler
|
|
16
23
|
|
|
17
|
-
|
|
18
|
-
asprof -d 30 -f profile.speedscope -o speedscope <pid>
|
|
24
|
+
#### CLI
|
|
19
25
|
|
|
20
|
-
|
|
21
|
-
|
|
26
|
+
```sh
|
|
27
|
+
# Attach to a running JVM (JFR is the default output format)
|
|
28
|
+
asprof -e cpu -d 30 -f cpu.jfr <pid>
|
|
29
|
+
|
|
30
|
+
# Or write collapsed stacks
|
|
31
|
+
asprof -e cpu -d 30 -o collapsed -f cpu.collapsed <pid>
|
|
22
32
|
```
|
|
23
33
|
|
|
24
|
-
|
|
34
|
+
#### Programmatic API
|
|
25
35
|
|
|
26
|
-
Add `async-profiler` to your dependencies, then
|
|
36
|
+
Add `async-profiler` to your dependencies, then control it in-process. The
|
|
37
|
+
output format follows the file extension (`.jfr` or `.collapsed`), and `event`
|
|
38
|
+
selects the metric:
|
|
27
39
|
|
|
28
40
|
```java
|
|
29
41
|
import one.profiler.AsyncProfiler;
|
|
@@ -38,80 +50,121 @@ profiler.execute("stop");
|
|
|
38
50
|
|
|
39
51
|
## Wall-clock profiling
|
|
40
52
|
|
|
41
|
-
Samples wall-clock time rather than CPU time
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
### CLI
|
|
53
|
+
Samples wall-clock time rather than CPU time, including time threads spend
|
|
54
|
+
waiting. Useful for I/O-bound or latency-sensitive code.
|
|
45
55
|
|
|
46
|
-
|
|
47
|
-
asprof -d 30 -e wall -f profile.pprof <pid>
|
|
48
|
-
```
|
|
56
|
+
### Java Flight Recorder
|
|
49
57
|
|
|
50
|
-
|
|
58
|
+
JFR has no wall-clock sampler, so this metric is async-profiler only. (JFR does
|
|
59
|
+
record specific waiting events, such as `jdk.ThreadPark` and
|
|
60
|
+
`jdk.JavaMonitorWait`, via the lock recipe below.)
|
|
51
61
|
|
|
52
|
-
|
|
53
|
-
AsyncProfiler profiler = AsyncProfiler.getInstance();
|
|
54
|
-
profiler.execute("start,event=wall,file=profile.jfr");
|
|
62
|
+
### async-profiler
|
|
55
63
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
profiler.execute("stop");
|
|
64
|
+
```sh
|
|
65
|
+
asprof -e wall -d 30 -f wall.jfr <pid>
|
|
59
66
|
```
|
|
60
67
|
|
|
68
|
+
Recorded as `profiler.WallClockSample` events. `cpu` and `wall` share the same
|
|
69
|
+
sampling timer, so async-profiler records one or the other within a single
|
|
70
|
+
recording, not both.
|
|
71
|
+
|
|
61
72
|
## Memory profiling
|
|
62
73
|
|
|
63
|
-
Samples
|
|
64
|
-
|
|
74
|
+
Samples memory allocations, in allocated bytes. async-profiler offers three
|
|
75
|
+
variants; JFR offers two:
|
|
76
|
+
|
|
77
|
+
- **heap allocations**: every heap allocation sampled since profiling started;
|
|
78
|
+
useful for finding allocation hot spots and reducing GC pressure
|
|
79
|
+
- **live heap**: only allocations whose objects are still live at the end;
|
|
80
|
+
useful for finding leaks
|
|
81
|
+
- **native memory**: off-heap `malloc`/`free`; useful for finding native leaks
|
|
82
|
+
(async-profiler only)
|
|
65
83
|
|
|
66
|
-
###
|
|
84
|
+
### Java Flight Recorder
|
|
67
85
|
|
|
68
86
|
```sh
|
|
69
|
-
#
|
|
70
|
-
|
|
87
|
+
# Heap allocation hot spots (jdk.ObjectAllocationSample, JDK 16+)
|
|
88
|
+
java -XX:StartFlightRecording=filename=alloc.jfr,settings=none,+jdk.ObjectAllocationSample#enabled=true,+jdk.ObjectAllocationSample#throttle=150/s -jar app.jar
|
|
71
89
|
|
|
72
|
-
#
|
|
73
|
-
|
|
90
|
+
# Live objects, for leak finding (jdk.OldObjectSample)
|
|
91
|
+
java -XX:StartFlightRecording=filename=live.jfr,settings=none,+jdk.OldObjectSample#enabled=true,+jdk.OldObjectSample#stackTrace=true -jar app.jar
|
|
74
92
|
```
|
|
75
93
|
|
|
76
|
-
|
|
94
|
+
JFR's native memory tracking (`-XX:NativeMemoryTracking`) reports usage by
|
|
95
|
+
category rather than call-stack-attributed allocations, so native allocation
|
|
96
|
+
profiling is async-profiler only.
|
|
77
97
|
|
|
78
|
-
|
|
79
|
-
AsyncProfiler profiler = AsyncProfiler.getInstance();
|
|
80
|
-
profiler.execute("start,event=alloc,file=mem.jfr");
|
|
98
|
+
### async-profiler
|
|
81
99
|
|
|
82
|
-
|
|
100
|
+
```sh
|
|
101
|
+
# Heap allocation hot spots (jdk.ObjectAllocationInNewTLAB/OutsideTLAB)
|
|
102
|
+
asprof -e alloc -d 30 -f alloc.jfr <pid>
|
|
83
103
|
|
|
84
|
-
profiler.
|
|
104
|
+
# Live objects only, for leak finding (profiler.LiveObject)
|
|
105
|
+
asprof -e alloc --live -d 30 -f live.jfr <pid>
|
|
106
|
+
|
|
107
|
+
# Off-heap native memory (profiler.Malloc/Free); --nofree skips free events
|
|
108
|
+
asprof -e nativemem -d 30 -f native.jfr <pid>
|
|
85
109
|
```
|
|
86
110
|
|
|
111
|
+
`--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
|
|
112
|
+
heap and native variants.
|
|
113
|
+
|
|
87
114
|
## Lock profiling
|
|
88
115
|
|
|
89
|
-
Samples contended monitor
|
|
90
|
-
|
|
116
|
+
Samples contended monitor and `java.util.concurrent` locks. Useful for finding
|
|
117
|
+
lock contention hot spots. The sampled values are nanoseconds spent blocked.
|
|
118
|
+
Recorded as `jdk.JavaMonitorEnter` and `jdk.ThreadPark` events.
|
|
91
119
|
|
|
92
|
-
###
|
|
120
|
+
### Java Flight Recorder
|
|
93
121
|
|
|
94
122
|
```sh
|
|
95
|
-
|
|
123
|
+
java -XX:StartFlightRecording=filename=lock.jfr,settings=none,+jdk.JavaMonitorEnter#enabled=true,+jdk.JavaMonitorEnter#threshold=10ms,+jdk.ThreadPark#enabled=true,+jdk.ThreadPark#threshold=10ms -jar app.jar
|
|
96
124
|
```
|
|
97
125
|
|
|
98
|
-
###
|
|
126
|
+
### async-profiler
|
|
99
127
|
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
|
|
128
|
+
```sh
|
|
129
|
+
asprof -e lock -d 30 -f lock.jfr <pid>
|
|
130
|
+
```
|
|
103
131
|
|
|
104
|
-
|
|
132
|
+
Recorded as `profiler.NativeLock` events.
|
|
105
133
|
|
|
106
|
-
|
|
134
|
+
## Profiling all events
|
|
135
|
+
|
|
136
|
+
### Java Flight Recorder
|
|
137
|
+
|
|
138
|
+
The `profile` template records execution samples, allocations, locks, GC, and
|
|
139
|
+
many other JVM events at once. JFR rotates the recording into multiple chunks as
|
|
140
|
+
it grows (`-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold).
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
|
|
144
|
+
jfr summary all.jfr
|
|
107
145
|
```
|
|
108
146
|
|
|
109
|
-
|
|
147
|
+
### async-profiler
|
|
148
|
+
|
|
149
|
+
`--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock`
|
|
150
|
+
simultaneously. Add `--nofree` to suppress the high-volume native `free` events,
|
|
151
|
+
which otherwise dominate the recording.
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
asprof --all --nofree -d 30 -f all.jfr <pid>
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## async-profiler flags
|
|
158
|
+
|
|
159
|
+
| Flag | Default | Description |
|
|
160
|
+
| ------------------- | ------- | ------------------------------------------------------------ |
|
|
161
|
+
| `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock`, and others |
|
|
162
|
+
| `-d` / `--duration` | — | Duration in seconds |
|
|
163
|
+
| `-o` / `--output` | `jfr` | Output format (`jfr` or `collapsed`) |
|
|
164
|
+
| `-f` / `--file` | — | Output file path |
|
|
165
|
+
| `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
|
|
166
|
+
| `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
|
|
167
|
+
| `<pid>` | — | Target JVM PID, `jps`, or the application name |
|
|
110
168
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
| `-d` / `--duration` | — | Duration in seconds |
|
|
114
|
-
| `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock` |
|
|
115
|
-
| `-f` / `--file` | — | Output file path |
|
|
116
|
-
| `-o` / `--output` | `jfr` | Output format: `jfr`, `pprof`, `speedscope` |
|
|
117
|
-
| `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
|
|
169
|
+
On macOS the default `cpu` event works (it samples CPU time via a timer), but
|
|
170
|
+
hardware events like `cache-misses` require Linux `perf_events`.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# JavaScript
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
profiles,
|
|
3
|
+
Profile JavaScript across Node.js, Deno, Bun, Chrome, and Safari, capturing CPU
|
|
4
|
+
profiles, heap profiles, and heap snapshots in V8 and JavaScriptCore formats.
|
|
5
5
|
|
|
6
6
|
## CPU profiling
|
|
7
7
|
|
|
@@ -54,7 +54,7 @@ writeFileSync(`cpu.cpuprofile`, JSON.stringify(profile))
|
|
|
54
54
|
Samples heap allocations by stack trace. Useful for finding allocation hot spots
|
|
55
55
|
and reducing GC pressure.
|
|
56
56
|
|
|
57
|
-
`bun --heap-prof` generates a heap _snapshot_ on exit, not a heap _profile_.
|
|
57
|
+
`bun --heap-prof` generates a V8 heap _snapshot_ on exit, not a heap _profile_.
|
|
58
58
|
Deno has no equivalent.
|
|
59
59
|
|
|
60
60
|
### CLI
|
|
@@ -127,6 +127,9 @@ bun --heap-prof script.ts
|
|
|
127
127
|
|
|
128
128
|
### Programmatic API
|
|
129
129
|
|
|
130
|
+
`node:v8`'s `writeHeapSnapshot` writes a V8-format snapshot and works in
|
|
131
|
+
Node.js, Deno, and Bun:
|
|
132
|
+
|
|
130
133
|
```js
|
|
131
134
|
import { writeHeapSnapshot } from 'node:v8'
|
|
132
135
|
|
|
@@ -134,22 +137,68 @@ import { writeHeapSnapshot } from 'node:v8'
|
|
|
134
137
|
writeHeapSnapshot(`heap.heapsnapshot`)
|
|
135
138
|
```
|
|
136
139
|
|
|
140
|
+
Bun also offers
|
|
141
|
+
[`Bun.generateHeapSnapshot()`](https://bun.com/reference/bun/generateHeapSnapshot),
|
|
142
|
+
which emits _both_ heap snapshot formats, selectable by argument:
|
|
143
|
+
|
|
144
|
+
```js
|
|
145
|
+
import { generateHeapSnapshot } from 'bun'
|
|
146
|
+
|
|
147
|
+
const jsc = generateHeapSnapshot() // Or generateHeapSnapshot(`jsc`)
|
|
148
|
+
await Bun.write(`heap.json`, JSON.stringify(jsc))
|
|
149
|
+
|
|
150
|
+
const v8 = generateHeapSnapshot(`v8`)
|
|
151
|
+
await Bun.write(`heap.heapsnapshot`, v8)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## pprof
|
|
155
|
+
|
|
156
|
+
Node.js can also emit [pprof](https://github.com/google/pprof) profiles via the
|
|
157
|
+
[`@datadog/pprof`](https://www.npmjs.com/package/@datadog/pprof) package, which
|
|
158
|
+
profiles a section of code rather than the whole process.
|
|
159
|
+
|
|
160
|
+
### CPU profiling
|
|
161
|
+
|
|
162
|
+
Samples wall-clock time across all threads. Useful for finding CPU hot spots and
|
|
163
|
+
time spent waiting.
|
|
164
|
+
|
|
165
|
+
```js
|
|
166
|
+
import { writeFile } from 'node:fs/promises'
|
|
167
|
+
import { encode, time } from '@datadog/pprof'
|
|
168
|
+
|
|
169
|
+
const profile = await time.profile({ durationMillis: 10_000 })
|
|
170
|
+
await writeFile(`cpu.pb.gz`, await encode(profile))
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Memory profiling
|
|
174
|
+
|
|
175
|
+
Samples heap allocations by stack trace. Useful for finding allocation hot spots
|
|
176
|
+
and reducing GC pressure.
|
|
177
|
+
|
|
178
|
+
```js
|
|
179
|
+
import { writeFile } from 'node:fs/promises'
|
|
180
|
+
import { encode, heap } from '@datadog/pprof'
|
|
181
|
+
|
|
182
|
+
heap.start(512 * 1024, 64) // Sampling interval in bytes, max stack depth
|
|
183
|
+
|
|
184
|
+
// Code to profile...
|
|
185
|
+
|
|
186
|
+
await writeFile(`heap.pb.gz`, await encode(await heap.profile()))
|
|
187
|
+
```
|
|
188
|
+
|
|
137
189
|
## Chrome DevTools
|
|
138
190
|
|
|
139
191
|
Chrome DevTools can profile JavaScript running in the browser or connected to
|
|
140
|
-
Node.js
|
|
141
|
-
both cases.
|
|
192
|
+
Node.js or Deno via `--inspect`. The panels and workflow are identical.
|
|
142
193
|
|
|
143
194
|
### Connecting
|
|
144
195
|
|
|
145
196
|
**In the browser:** open DevTools with ⌥⌘I (macOS) or Ctrl+Shift+I
|
|
146
197
|
(Windows/Linux).
|
|
147
198
|
|
|
148
|
-
**Via `--inspect` (Node.js, Deno
|
|
199
|
+
**Via `--inspect` (Node.js, Deno):** start the process with the inspector
|
|
149
200
|
enabled, then open `chrome://inspect` in Chrome and click **Open dedicated
|
|
150
|
-
DevTools for Node**.
|
|
151
|
-
[debug.bun.sh](https://debug.bun.sh) — Bun uses the WebKit Inspector Protocol
|
|
152
|
-
rather than V8's.
|
|
201
|
+
DevTools for Node**.
|
|
153
202
|
|
|
154
203
|
```sh
|
|
155
204
|
# Node.js (default port 9229)
|
|
@@ -157,9 +206,6 @@ node --inspect script.js
|
|
|
157
206
|
|
|
158
207
|
# Deno (default port 9229)
|
|
159
208
|
deno run --inspect script.ts
|
|
160
|
-
|
|
161
|
-
# Bun (auto-assigned port)
|
|
162
|
-
bun --inspect script.ts
|
|
163
209
|
```
|
|
164
210
|
|
|
165
211
|
#### Flags (all runtimes)
|
|
@@ -184,6 +230,17 @@ Stop when done to see allocation hot spots by call stack.
|
|
|
184
230
|
Open the **Memory** panel, select **Heap snapshot**, and click **Take
|
|
185
231
|
snapshot**.
|
|
186
232
|
|
|
233
|
+
## debug.bun.sh
|
|
234
|
+
|
|
235
|
+
Bun's inspector speaks the WebKit Inspector Protocol rather than V8's, so it
|
|
236
|
+
connects through [debug.bun.sh](https://debug.bun.sh) instead of Chrome
|
|
237
|
+
DevTools. Start the process with `--inspect` and open the URL printed to stderr.
|
|
238
|
+
|
|
239
|
+
```sh
|
|
240
|
+
# Bun (auto-assigned port)
|
|
241
|
+
bun --inspect script.ts
|
|
242
|
+
```
|
|
243
|
+
|
|
187
244
|
## Safari Web Inspector
|
|
188
245
|
|
|
189
246
|
Safari's Web Inspector records a timeline that combines CPU sampling, browser
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Julia
|
|
2
|
+
|
|
3
|
+
Julia profiling uses [PProf.jl](https://github.com/JuliaPerf/PProf.jl), which
|
|
4
|
+
exports profiles collected by Julia's built-in
|
|
5
|
+
[`Profile`](https://docs.julialang.org/en/v1/manual/profile/) standard library
|
|
6
|
+
to the pprof format.
|
|
7
|
+
|
|
8
|
+
## CPU profiling
|
|
9
|
+
|
|
10
|
+
Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
11
|
+
|
|
12
|
+
```julia
|
|
13
|
+
using Profile, PProf
|
|
14
|
+
|
|
15
|
+
# Warm up the JIT so compilation isn't captured as part of the profile.
|
|
16
|
+
my_function()
|
|
17
|
+
|
|
18
|
+
Profile.clear()
|
|
19
|
+
@profile my_function()
|
|
20
|
+
|
|
21
|
+
# `web = false` skips the UI. `from_c = false` drops C/runtime frames, leaving
|
|
22
|
+
# just your Julia code.
|
|
23
|
+
pprof(out = "cpu.pb.gz", web = false, from_c = false)
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Memory profiling
|
|
27
|
+
|
|
28
|
+
Samples heap allocations. Useful for finding allocation hot spots and reducing
|
|
29
|
+
GC pressure.
|
|
30
|
+
|
|
31
|
+
```julia
|
|
32
|
+
using Profile, PProf
|
|
33
|
+
|
|
34
|
+
# Warm up the JIT so compilation isn't captured as part of the profile.
|
|
35
|
+
my_function()
|
|
36
|
+
|
|
37
|
+
Profile.Allocs.clear()
|
|
38
|
+
Profile.Allocs.@profile my_function()
|
|
39
|
+
|
|
40
|
+
PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## `pprof` options
|
|
44
|
+
|
|
45
|
+
| Option | Default | Description |
|
|
46
|
+
| -------- | ----------------- | --------------------------------------------- |
|
|
47
|
+
| `out` | `"profile.pb.gz"` | Output file path |
|
|
48
|
+
| `web` | `true` | Launch the interactive web UI after exporting |
|
|
49
|
+
| `from_c` | `true` | Include C and Julia runtime frames |
|
|
50
|
+
|
|
51
|
+
## Tips
|
|
52
|
+
|
|
53
|
+
Run single-threaded (`julia -t 1 --gcthreads=1`). Otherwise idle GC and
|
|
54
|
+
scheduler threads fill the profile with wait frames (`__psynch_cvwait`).
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# Java/Kotlin
|
|
2
|
+
|
|
3
|
+
Java and Kotlin profiling works with any JVM language, using either
|
|
4
|
+
[Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) (JFR),
|
|
5
|
+
built into the JDK since JDK 11, or
|
|
6
|
+
[async-profiler](https://github.com/async-profiler/async-profiler), a low
|
|
7
|
+
overhead sampling profiler that additionally resolves native frames and works on
|
|
8
|
+
older JDKs.
|
|
9
|
+
|
|
10
|
+
## CPU profiling
|
|
11
|
+
|
|
12
|
+
Periodically samples the call stack while on CPU. Useful for finding CPU hot
|
|
13
|
+
spots. Recorded as `jdk.ExecutionSample` events.
|
|
14
|
+
|
|
15
|
+
### Java Flight Recorder
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms -jar app.jar
|
|
19
|
+
jfr summary cpu.jfr
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### async-profiler
|
|
23
|
+
|
|
24
|
+
#### CLI
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
# Attach to a running JVM (JFR is the default output format)
|
|
28
|
+
asprof -e cpu -d 30 -f cpu.jfr <pid>
|
|
29
|
+
|
|
30
|
+
# Or write collapsed stacks
|
|
31
|
+
asprof -e cpu -d 30 -o collapsed -f cpu.collapsed <pid>
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
#### Programmatic API
|
|
35
|
+
|
|
36
|
+
Add `async-profiler` to your dependencies, then control it in-process. The
|
|
37
|
+
output format follows the file extension (`.jfr` or `.collapsed`), and `event`
|
|
38
|
+
selects the metric:
|
|
39
|
+
|
|
40
|
+
```java
|
|
41
|
+
import one.profiler.AsyncProfiler;
|
|
42
|
+
|
|
43
|
+
AsyncProfiler profiler = AsyncProfiler.getInstance();
|
|
44
|
+
profiler.execute("start,event=cpu,file=cpu.jfr");
|
|
45
|
+
|
|
46
|
+
// Code to profile...
|
|
47
|
+
|
|
48
|
+
profiler.execute("stop");
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Wall-clock profiling
|
|
52
|
+
|
|
53
|
+
Samples wall-clock time rather than CPU time, including time threads spend
|
|
54
|
+
waiting. Useful for I/O-bound or latency-sensitive code.
|
|
55
|
+
|
|
56
|
+
### Java Flight Recorder
|
|
57
|
+
|
|
58
|
+
JFR has no wall-clock sampler, so this metric is async-profiler only. (JFR does
|
|
59
|
+
record specific waiting events, such as `jdk.ThreadPark` and
|
|
60
|
+
`jdk.JavaMonitorWait`, via the lock recipe below.)
|
|
61
|
+
|
|
62
|
+
### async-profiler
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
asprof -e wall -d 30 -f wall.jfr <pid>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Recorded as `profiler.WallClockSample` events. `cpu` and `wall` share the same
|
|
69
|
+
sampling timer, so async-profiler records one or the other within a single
|
|
70
|
+
recording, not both.
|
|
71
|
+
|
|
72
|
+
## Memory profiling
|
|
73
|
+
|
|
74
|
+
Samples memory allocations, in allocated bytes. async-profiler offers three
|
|
75
|
+
variants; JFR offers two:
|
|
76
|
+
|
|
77
|
+
- **heap allocations**: every heap allocation sampled since profiling started;
|
|
78
|
+
useful for finding allocation hot spots and reducing GC pressure
|
|
79
|
+
- **live heap**: only allocations whose objects are still live at the end;
|
|
80
|
+
useful for finding leaks
|
|
81
|
+
- **native memory**: off-heap `malloc`/`free`; useful for finding native leaks
|
|
82
|
+
(async-profiler only)
|
|
83
|
+
|
|
84
|
+
### Java Flight Recorder
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
# Heap allocation hot spots (jdk.ObjectAllocationSample, JDK 16+)
|
|
88
|
+
java -XX:StartFlightRecording=filename=alloc.jfr,settings=none,+jdk.ObjectAllocationSample#enabled=true,+jdk.ObjectAllocationSample#throttle=150/s -jar app.jar
|
|
89
|
+
|
|
90
|
+
# Live objects, for leak finding (jdk.OldObjectSample)
|
|
91
|
+
java -XX:StartFlightRecording=filename=live.jfr,settings=none,+jdk.OldObjectSample#enabled=true,+jdk.OldObjectSample#stackTrace=true -jar app.jar
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
JFR's native memory tracking (`-XX:NativeMemoryTracking`) reports usage by
|
|
95
|
+
category rather than call-stack-attributed allocations, so native allocation
|
|
96
|
+
profiling is async-profiler only.
|
|
97
|
+
|
|
98
|
+
### async-profiler
|
|
99
|
+
|
|
100
|
+
```sh
|
|
101
|
+
# Heap allocation hot spots (jdk.ObjectAllocationInNewTLAB/OutsideTLAB)
|
|
102
|
+
asprof -e alloc -d 30 -f alloc.jfr <pid>
|
|
103
|
+
|
|
104
|
+
# Live objects only, for leak finding (profiler.LiveObject)
|
|
105
|
+
asprof -e alloc --live -d 30 -f live.jfr <pid>
|
|
106
|
+
|
|
107
|
+
# Off-heap native memory (profiler.Malloc/Free); --nofree skips free events
|
|
108
|
+
asprof -e nativemem -d 30 -f native.jfr <pid>
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
|
|
112
|
+
heap and native variants.
|
|
113
|
+
|
|
114
|
+
## Lock profiling
|
|
115
|
+
|
|
116
|
+
Samples contended monitor and `java.util.concurrent` locks. Useful for finding
|
|
117
|
+
lock contention hot spots. The sampled values are nanoseconds spent blocked.
|
|
118
|
+
Recorded as `jdk.JavaMonitorEnter` and `jdk.ThreadPark` events.
|
|
119
|
+
|
|
120
|
+
### Java Flight Recorder
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
java -XX:StartFlightRecording=filename=lock.jfr,settings=none,+jdk.JavaMonitorEnter#enabled=true,+jdk.JavaMonitorEnter#threshold=10ms,+jdk.ThreadPark#enabled=true,+jdk.ThreadPark#threshold=10ms -jar app.jar
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### async-profiler
|
|
127
|
+
|
|
128
|
+
```sh
|
|
129
|
+
asprof -e lock -d 30 -f lock.jfr <pid>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Recorded as `profiler.NativeLock` events.
|
|
133
|
+
|
|
134
|
+
## Profiling all events
|
|
135
|
+
|
|
136
|
+
### Java Flight Recorder
|
|
137
|
+
|
|
138
|
+
The `profile` template records execution samples, allocations, locks, GC, and
|
|
139
|
+
many other JVM events at once. JFR rotates the recording into multiple chunks as
|
|
140
|
+
it grows (`-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold).
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
|
|
144
|
+
jfr summary all.jfr
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### async-profiler
|
|
148
|
+
|
|
149
|
+
`--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock`
|
|
150
|
+
simultaneously. Add `--nofree` to suppress the high-volume native `free` events,
|
|
151
|
+
which otherwise dominate the recording.
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
asprof --all --nofree -d 30 -f all.jfr <pid>
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## async-profiler flags
|
|
158
|
+
|
|
159
|
+
| Flag | Default | Description |
|
|
160
|
+
| ------------------- | ------- | ------------------------------------------------------------ |
|
|
161
|
+
| `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock`, and others |
|
|
162
|
+
| `-d` / `--duration` | — | Duration in seconds |
|
|
163
|
+
| `-o` / `--output` | `jfr` | Output format (`jfr` or `collapsed`) |
|
|
164
|
+
| `-f` / `--file` | — | Output file path |
|
|
165
|
+
| `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
|
|
166
|
+
| `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
|
|
167
|
+
| `<pid>` | — | Target JVM PID, `jps`, or the application name |
|
|
168
|
+
|
|
169
|
+
On macOS the default `cpu` event works (it samples CPU time via a timer), but
|
|
170
|
+
hardware events like `cache-misses` require Linux `perf_events`.
|
package/docs/languages/php.md
CHANGED
|
@@ -1,31 +1,75 @@
|
|
|
1
1
|
# PHP
|
|
2
2
|
|
|
3
|
-
PHP profiling uses [
|
|
4
|
-
sampling profiler
|
|
3
|
+
PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
|
|
4
|
+
extension, a low-overhead sampling profiler. Excimer samples from a
|
|
5
|
+
PHP-controlled timer, so you start and stop it from within the program or a
|
|
6
|
+
prepended bootstrap script.
|
|
5
7
|
|
|
6
8
|
## CPU profiling
|
|
7
9
|
|
|
8
10
|
Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
9
11
|
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
|
|
12
|
+
```php
|
|
13
|
+
<?php
|
|
14
|
+
$prof = new ExcimerProfiler();
|
|
15
|
+
$prof->setEventType(EXCIMER_CPU);
|
|
16
|
+
$prof->setPeriod(0.001); // seconds
|
|
17
|
+
$prof->start();
|
|
18
|
+
|
|
19
|
+
// Code to profile...
|
|
20
|
+
|
|
21
|
+
$prof->stop();
|
|
22
|
+
file_put_contents('cpu.speedscope.json',
|
|
23
|
+
json_encode($prof->getLog()->getSpeedscopeData()));
|
|
24
|
+
```
|
|
13
25
|
|
|
14
|
-
|
|
15
|
-
phpspy -d 30 --output-format=speedscope --pid <pid> -f cpu.speedscope
|
|
26
|
+
## Wall-clock profiling
|
|
16
27
|
|
|
17
|
-
|
|
18
|
-
|
|
28
|
+
Samples wall-clock time rather than CPU time, including time threads spend
|
|
29
|
+
waiting. Useful for I/O-bound or latency-sensitive code.
|
|
30
|
+
|
|
31
|
+
```php
|
|
32
|
+
<?php
|
|
33
|
+
$prof = new ExcimerProfiler();
|
|
34
|
+
$prof->setEventType(EXCIMER_REAL);
|
|
35
|
+
$prof->setPeriod(0.001);
|
|
36
|
+
$prof->start();
|
|
37
|
+
|
|
38
|
+
// Code to profile...
|
|
39
|
+
|
|
40
|
+
$prof->stop();
|
|
41
|
+
file_put_contents('wall.speedscope.json',
|
|
42
|
+
json_encode($prof->getLog()->getSpeedscopeData()));
|
|
19
43
|
```
|
|
20
44
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
45
|
+
## Profiling an existing program
|
|
46
|
+
|
|
47
|
+
To profile a program you don't want to edit, point `auto_prepend_file` at a
|
|
48
|
+
bootstrap script that starts the profiler and writes the result on shutdown:
|
|
49
|
+
|
|
50
|
+
```php
|
|
51
|
+
<?php // prepend.php
|
|
52
|
+
$prof = new ExcimerProfiler();
|
|
53
|
+
$prof->setEventType(EXCIMER_REAL);
|
|
54
|
+
$prof->setPeriod(0.001);
|
|
55
|
+
$prof->start();
|
|
56
|
+
register_shutdown_function(function () use ($prof) {
|
|
57
|
+
$prof->stop();
|
|
58
|
+
file_put_contents('profile.speedscope.json',
|
|
59
|
+
json_encode($prof->getLog()->getSpeedscopeData()));
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
php -d auto_prepend_file=prepend.php existing_program.phar dump-autoload --optimize
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## API
|
|
68
|
+
|
|
69
|
+
| Method | Description |
|
|
70
|
+
| ------------------------------- | ----------------------------------------------------- |
|
|
71
|
+
| `setEventType($type)` | `EXCIMER_REAL` (wall clock) or `EXCIMER_CPU` |
|
|
72
|
+
| `setPeriod($seconds)` | Sampling interval in seconds (e.g. `0.001` = 1000 Hz) |
|
|
73
|
+
| `setMaxDepth($depth)` | Maximum stack frames per sample |
|
|
74
|
+
| `start()` / `stop()` | Begin and end profiling |
|
|
75
|
+
| `getLog()->getSpeedscopeData()` | The collected profile as Speedscope-format data |
|