profiler-md 0.8.1 → 0.9.1
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 +22342 -14056
- package/dist/index.d.mts +2696 -787
- package/dist/index.js +2 -2
- package/dist/man/profiler-md.1 +150 -0
- package/dist/node/index.mjs +2 -0
- package/docs/api.md +51 -11
- package/docs/formats/ghc-eventlog.md +6 -4
- package/docs/formats/ghc-json-profile.md +1 -1
- package/docs/formats/hprof.md +1 -2
- package/docs/formats/jfr.md +1 -1
- package/docs/formats/jsc-heap-snapshot.md +9 -8
- package/docs/formats/memray.md +9 -14
- package/docs/formats/perf.md +24 -34
- package/docs/formats/pprof.md +6 -4
- package/docs/formats/speedscope.md +3 -3
- package/docs/formats/systing.md +1 -1
- package/docs/formats/trace-event.md +20 -0
- package/docs/formats/v8-cpu-profile.md +1 -1
- package/docs/formats/v8-heap-profile.md +6 -6
- package/docs/formats/v8-heap-snapshot.md +10 -9
- package/docs/formats/webkit-timeline-recording.md +2 -3
- package/docs/languages/c.md +99 -45
- package/docs/languages/elixir.md +4 -3
- package/docs/languages/fortran.md +10 -9
- package/docs/languages/haskell.md +1 -1
- package/docs/languages/java.md +43 -6
- package/docs/languages/javascript.md +107 -3
- package/docs/languages/nix.md +56 -0
- package/docs/languages/python.md +87 -30
- package/docs/languages/swift.md +11 -10
- package/docs/languages/zig.md +45 -47
- package/package.json +54 -34
- package/readme.md +368 -174
- package/skills/profile-optimize/SKILL.md +259 -133
package/docs/languages/c.md
CHANGED
|
@@ -2,13 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools),
|
|
4
4
|
[Valgrind's Callgrind](https://valgrind.org/docs/manual/cl-manual.html),
|
|
5
|
-
[Linux `perf`](https://perfwiki.github.io/main/),
|
|
6
|
-
[
|
|
5
|
+
[Linux `perf`](https://perfwiki.github.io/main/),
|
|
6
|
+
[simpleperf](https://android.googlesource.com/platform/system/extras/+/refs/heads/main/simpleperf/doc/README.md),
|
|
7
|
+
or [systing](https://github.com/josefbacik/systing).
|
|
8
|
+
[Clang](https://clang.llvm.org) also traces its own compilation of a file.
|
|
7
9
|
|
|
8
10
|
## CPU profiling
|
|
9
11
|
|
|
10
12
|
Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
11
13
|
|
|
14
|
+
### gperftools
|
|
15
|
+
|
|
12
16
|
Link with `-lprofiler`:
|
|
13
17
|
|
|
14
18
|
```sh
|
|
@@ -16,7 +20,7 @@ gcc -O2 -Wl,--no-as-needed -lprofiler -o program program.c # C
|
|
|
16
20
|
g++ -O2 -Wl,--no-as-needed -lprofiler -o program program.cpp # C++
|
|
17
21
|
```
|
|
18
22
|
|
|
19
|
-
|
|
23
|
+
#### CLI
|
|
20
24
|
|
|
21
25
|
```sh
|
|
22
26
|
# Generate a CPU profile
|
|
@@ -35,7 +39,7 @@ pprof --proto ./program cpu.prof > cpu.pprof
|
|
|
35
39
|
| `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
|
|
36
40
|
| `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
|
|
37
41
|
|
|
38
|
-
|
|
42
|
+
#### Programmatic API
|
|
39
43
|
|
|
40
44
|
```c
|
|
41
45
|
#include <gperftools/profiler.h>
|
|
@@ -48,6 +52,74 @@ ProfilerFlush(); // optional: flush buffered samples mid-run
|
|
|
48
52
|
ProfilerStop();
|
|
49
53
|
```
|
|
50
54
|
|
|
55
|
+
### Linux perf
|
|
56
|
+
|
|
57
|
+
[Linux `perf`](https://perfwiki.github.io/main/) samples any native program
|
|
58
|
+
through the kernel's `perf_event` counters, across user and kernel code, and
|
|
59
|
+
writes `perf.data`. It needs a Linux kernel and a
|
|
60
|
+
`/proc/sys/kernel/perf_event_paranoid` low enough to permit sampling (`1` or
|
|
61
|
+
below for kernel stacks).
|
|
62
|
+
|
|
63
|
+
Build with frame pointers so perf's unwinder can walk the stack:
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
gcc -O2 -g -fno-omit-frame-pointer -o program program.c # C
|
|
67
|
+
g++ -O2 -g -fno-omit-frame-pointer -o program program.cpp # C++
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
# Sample a command at 999 Hz, recording call chains
|
|
72
|
+
perf record -F 999 -g -o perf.data -- ./program args
|
|
73
|
+
|
|
74
|
+
# Or sample a running process for 30 seconds
|
|
75
|
+
perf record -F 999 -g -o perf.data --pid <pid> -- sleep 30
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### simpleperf
|
|
79
|
+
|
|
80
|
+
[simpleperf](https://android.googlesource.com/platform/system/extras/+/refs/heads/main/simpleperf/doc/README.md)
|
|
81
|
+
samples a native Android program, or any program on an aarch64 Linux kernel,
|
|
82
|
+
through the same `perf_event` counters as `perf` and writes the same `perf.data`
|
|
83
|
+
layout. The Android NDK includes it (`simpleperf/bin/android/<abi>/simpleperf`)
|
|
84
|
+
as a static executable. Build with frame pointers as for `perf`.
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
# On the device, sample a command at 999 Hz, recording call chains
|
|
88
|
+
simpleperf record -f 999 --call-graph fp -o perf.data -- ./program args
|
|
89
|
+
|
|
90
|
+
# Or sample an app by package name for 30 seconds
|
|
91
|
+
simpleperf record -f 999 --call-graph fp -o perf.data --app com.example.app --duration 30
|
|
92
|
+
|
|
93
|
+
# From a host, through adb
|
|
94
|
+
app_profiler.py -p com.example.app -r "-f 999 --call-graph fp" -o perf.data
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Both write a `perf.data` that contains addresses rather than function names. See
|
|
98
|
+
`profiler-md --help perf` for how frames are named and how to symbolize them.
|
|
99
|
+
|
|
100
|
+
## Linux perf CLI flags
|
|
101
|
+
|
|
102
|
+
| Flag | Default | Description |
|
|
103
|
+
| -------------- | ----------- | -------------------------------------------------------------------- |
|
|
104
|
+
| `-F` | `4000` | Samples per second |
|
|
105
|
+
| `-e` | `cycles` | Event to sample (`cpu-clock` where no hardware counter is available) |
|
|
106
|
+
| `-g` | off | Record call chains |
|
|
107
|
+
| `--call-graph` | `fp` | How to unwind: `fp`, `dwarf` (larger files), or `lbr` |
|
|
108
|
+
| `-o` | `perf.data` | Output path |
|
|
109
|
+
| `-a` | off | Sample every CPU on the system rather than one command |
|
|
110
|
+
|
|
111
|
+
## simpleperf CLI flags
|
|
112
|
+
|
|
113
|
+
| Flag | Default | Description |
|
|
114
|
+
| -------------- | ------------ | -------------------------------------------------------------------- |
|
|
115
|
+
| `-f` | `4000` | Samples per second |
|
|
116
|
+
| `-e` | `cpu-cycles` | Event to sample (`cpu-clock` where no hardware counter is available) |
|
|
117
|
+
| `-g` | off | Record call chains, unwinding with DWARF while recording |
|
|
118
|
+
| `--call-graph` | — | How to unwind: `fp` or `dwarf` |
|
|
119
|
+
| `-o` | `perf.data` | Output path |
|
|
120
|
+
| `--app` | — | Sample an app by package name |
|
|
121
|
+
| `--duration` | — | Seconds to record |
|
|
122
|
+
|
|
51
123
|
## Memory profiling
|
|
52
124
|
|
|
53
125
|
Periodically dumps the live heap, capturing allocation stack traces. Useful for
|
|
@@ -64,7 +136,7 @@ g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
|
|
|
64
136
|
|
|
65
137
|
```sh
|
|
66
138
|
# Generate heap profiles (written as <prefix>.0001.heap, .0002.heap, …)
|
|
67
|
-
HEAPPROFILE=heap.prof ./program
|
|
139
|
+
TCMALLOC_STACKTRACE_METHOD=libgcc HEAPPROFILE=heap.prof ./program
|
|
68
140
|
|
|
69
141
|
# Convert a heap profile to pprof protobuf format
|
|
70
142
|
pprof --proto ./program heap.prof.0001.heap > heap.pprof
|
|
@@ -72,15 +144,16 @@ pprof --proto ./program heap.prof.0001.heap > heap.pprof
|
|
|
72
144
|
|
|
73
145
|
#### Environment variables
|
|
74
146
|
|
|
75
|
-
| Variable | Default | Description
|
|
76
|
-
| ---------------------------------- | ------------ |
|
|
77
|
-
| `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
147
|
+
| Variable | Default | Description |
|
|
148
|
+
| ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
149
|
+
| `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set |
|
|
150
|
+
| `TCMALLOC_STACKTRACE_METHOD` | — | Stack unwinder. `libgcc` reads unwind tables, so it walks through libraries built without frame pointers, such as libc, where the frame-pointer walk ends in invalid frames |
|
|
151
|
+
| `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
|
|
152
|
+
| `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
|
|
153
|
+
| `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
|
|
154
|
+
| `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
|
|
155
|
+
| `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
|
|
156
|
+
| `HEAP_PROFILE_ONLY_MMAP` | `false` | Profile only `mmap`/`mremap`/`sbrk`, skipping `malloc`/`new` |
|
|
84
157
|
|
|
85
158
|
### Programmatic API
|
|
86
159
|
|
|
@@ -213,47 +286,28 @@ sudo systing --duration 30 --output profile.systing --pid <pid>
|
|
|
213
286
|
| `--no-sleep-stack-traces` | off | Skip uninterruptible-sleep stacks |
|
|
214
287
|
| `--no-interruptible-stack-traces` | off | Skip interruptible-sleep stacks |
|
|
215
288
|
|
|
216
|
-
##
|
|
289
|
+
## Compilation tracing
|
|
217
290
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
the
|
|
221
|
-
|
|
222
|
-
[Linux `perf`](https://perfwiki.github.io/main/) samples any native program and
|
|
223
|
-
writes `perf.data` itself. It needs a Linux kernel and a
|
|
224
|
-
`/proc/sys/kernel/perf_event_paranoid` low enough to permit sampling (`1` or
|
|
225
|
-
below for kernel stacks).
|
|
226
|
-
|
|
227
|
-
Build with frame pointers so perf's unwinder can walk the stack:
|
|
228
|
-
|
|
229
|
-
```sh
|
|
230
|
-
gcc -O2 -g -fno-omit-frame-pointer -o program program.c # C
|
|
231
|
-
g++ -O2 -g -fno-omit-frame-pointer -o program program.cpp # C++
|
|
232
|
-
```
|
|
291
|
+
Traces Clang compiling one file: each header it reads, each template it
|
|
292
|
+
instantiates, and each optimization pass it runs on each function. Useful for
|
|
293
|
+
finding the headers and templates that slow a build.
|
|
233
294
|
|
|
234
295
|
### CLI
|
|
235
296
|
|
|
236
297
|
```sh
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
# Or sample a running process for 30 seconds
|
|
241
|
-
perf record -F 999 -g -o perf.data --pid <pid> -- sleep 30
|
|
298
|
+
clang -ftime-trace -c program.c # C
|
|
299
|
+
clang++ -ftime-trace -c program.cpp # C++
|
|
242
300
|
```
|
|
243
301
|
|
|
244
302
|
#### Flags
|
|
245
303
|
|
|
246
|
-
| Flag
|
|
247
|
-
|
|
|
248
|
-
| `-
|
|
249
|
-
| `-
|
|
250
|
-
| `-
|
|
251
|
-
| `--call-graph` | `fp` | How to unwind: `fp`, `dwarf` (larger files), or `lbr` |
|
|
252
|
-
| `-o` | `perf.data` | Output path |
|
|
253
|
-
| `-a` | off | Sample every CPU on the system rather than one command |
|
|
304
|
+
| Flag | Default | Description |
|
|
305
|
+
| ------------------------------- | --------- | ----------------------------------------- |
|
|
306
|
+
| `-ftime-trace` | — | Write a trace of the compilation when set |
|
|
307
|
+
| `-ftime-trace=<path>` | see below | File or directory for the trace |
|
|
308
|
+
| `-ftime-trace-granularity=<µs>` | `500` | Shortest event to record, in microseconds |
|
|
254
309
|
|
|
255
|
-
|
|
256
|
-
`profiler-md --help perf` for how frames are named and how to symbolize them.
|
|
310
|
+
Clang writes the trace beside the object file, as `program.json`.
|
|
257
311
|
|
|
258
312
|
## Tips
|
|
259
313
|
|
package/docs/languages/elixir.md
CHANGED
|
@@ -48,6 +48,7 @@ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_g
|
|
|
48
48
|
|
|
49
49
|
### Overhead
|
|
50
50
|
|
|
51
|
-
Keep the call small. eflambe traces every
|
|
52
|
-
|
|
53
|
-
|
|
51
|
+
Keep the profiled call small and its stack shallow. eflambe traces every
|
|
52
|
+
function call and writes each one's full stack, so output and peak memory grow
|
|
53
|
+
with the number of calls times the stack depth. See
|
|
54
|
+
[Stratus3D/eflambe#52](https://github.com/Stratus3D/eflambe/issues/52).
|
|
@@ -74,7 +74,7 @@ automatic arrays go through `malloc`, so tcmalloc records them.
|
|
|
74
74
|
|
|
75
75
|
```sh
|
|
76
76
|
# Generate heap profiles (written as <prefix>.0001.heap, .0002.heap, …)
|
|
77
|
-
HEAPPROFILE=heap.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libtcmalloc.so ./program
|
|
77
|
+
TCMALLOC_STACKTRACE_METHOD=libgcc HEAPPROFILE=heap.prof LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libtcmalloc.so ./program
|
|
78
78
|
|
|
79
79
|
# Convert a heap profile to pprof protobuf format
|
|
80
80
|
pprof --proto ./program heap.prof.0001.heap > heap.pprof
|
|
@@ -82,14 +82,15 @@ pprof --proto ./program heap.prof.0001.heap > heap.pprof
|
|
|
82
82
|
|
|
83
83
|
#### Environment variables
|
|
84
84
|
|
|
85
|
-
| Variable | Default | Description
|
|
86
|
-
| ---------------------------------- | ------------ |
|
|
87
|
-
| `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
85
|
+
| Variable | Default | Description |
|
|
86
|
+
| ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
87
|
+
| `HEAPPROFILE` | — | Output filename prefix that enables heap profiling when set |
|
|
88
|
+
| `TCMALLOC_STACKTRACE_METHOD` | — | Stack unwinder. `libgcc` reads unwind tables, so it walks through libraries built without frame pointers, such as libc, where the frame-pointer walk ends in invalid frames |
|
|
89
|
+
| `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
|
|
90
|
+
| `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
|
|
91
|
+
| `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
|
|
92
|
+
| `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
|
|
93
|
+
| `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
|
|
93
94
|
|
|
94
95
|
### Programmatic API
|
|
95
96
|
|
|
@@ -75,7 +75,7 @@ phases with `Debug.Trace.traceEventIO` to profile a run in parts.
|
|
|
75
75
|
|
|
76
76
|
An eventlog contains cost-centre samples only when the time profiler runs, which
|
|
77
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
|
|
78
|
+
text report, which is for reading by hand.
|
|
79
79
|
|
|
80
80
|
#### RTS options
|
|
81
81
|
|
package/docs/languages/java.md
CHANGED
|
@@ -6,6 +6,10 @@ built into the JDK since JDK 11, or
|
|
|
6
6
|
[async-profiler](https://github.com/async-profiler/async-profiler), which also
|
|
7
7
|
resolves native frames and works on older JDKs.
|
|
8
8
|
|
|
9
|
+
JFR keeps only the innermost 64 frames of each stack trace by default, so a
|
|
10
|
+
deeper stack loses its outermost callers. The JFR commands below raise the depth
|
|
11
|
+
with `-XX:FlightRecorderOptions:stackdepth=2048`, which keeps the stacks whole.
|
|
12
|
+
|
|
9
13
|
## CPU profiling
|
|
10
14
|
|
|
11
15
|
Periodically samples the call stack while on CPU. Useful for finding CPU hot
|
|
@@ -15,7 +19,7 @@ events for threads running native methods.
|
|
|
15
19
|
### Java Flight Recorder
|
|
16
20
|
|
|
17
21
|
```sh
|
|
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
|
|
22
|
+
java -XX:FlightRecorderOptions:stackdepth=2048 -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
23
|
jfr summary cpu.jfr
|
|
20
24
|
```
|
|
21
25
|
|
|
@@ -89,10 +93,10 @@ variants; JFR offers two:
|
|
|
89
93
|
|
|
90
94
|
```sh
|
|
91
95
|
# Heap allocation hot spots (jdk.ObjectAllocationSample, JDK 16+)
|
|
92
|
-
java -XX:StartFlightRecording=filename=alloc.jfr,settings=none,+jdk.ObjectAllocationSample#enabled=true,+jdk.ObjectAllocationSample#throttle=150/s -jar app.jar
|
|
96
|
+
java -XX:FlightRecorderOptions:stackdepth=2048 -XX:StartFlightRecording=filename=alloc.jfr,settings=none,+jdk.ObjectAllocationSample#enabled=true,+jdk.ObjectAllocationSample#throttle=150/s -jar app.jar
|
|
93
97
|
|
|
94
98
|
# Live objects, for leak finding (jdk.OldObjectSample)
|
|
95
|
-
java -XX:StartFlightRecording=filename=live.jfr,settings=none,+jdk.OldObjectSample#enabled=true,+jdk.OldObjectSample#stackTrace=true -jar app.jar
|
|
99
|
+
java -XX:FlightRecorderOptions:stackdepth=2048 -XX:StartFlightRecording=filename=live.jfr,settings=none,+jdk.OldObjectSample#enabled=true,+jdk.OldObjectSample#stackTrace=true -jar app.jar
|
|
96
100
|
```
|
|
97
101
|
|
|
98
102
|
JFR's native memory tracking (`-XX:NativeMemoryTracking`) reports usage by
|
|
@@ -113,7 +117,9 @@ asprof -e nativemem -d 30 -f native.jfr <pid>
|
|
|
113
117
|
```
|
|
114
118
|
|
|
115
119
|
`--alloc <bytes>` and `--nativemem <bytes>` set the sampling interval for the
|
|
116
|
-
heap and native variants.
|
|
120
|
+
heap and native variants. Without `--nativemem`, async-profiler records every
|
|
121
|
+
malloc and free, so a recording of a JVM's startup alone takes tens of
|
|
122
|
+
megabytes.
|
|
117
123
|
|
|
118
124
|
## Heap dumps
|
|
119
125
|
|
|
@@ -168,7 +174,7 @@ Recorded as `jdk.JavaMonitorEnter` and `jdk.ThreadPark` events.
|
|
|
168
174
|
### Java Flight Recorder
|
|
169
175
|
|
|
170
176
|
```sh
|
|
171
|
-
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
|
|
177
|
+
java -XX:FlightRecorderOptions:stackdepth=2048 -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
|
|
172
178
|
```
|
|
173
179
|
|
|
174
180
|
### async-profiler
|
|
@@ -188,7 +194,7 @@ many other JVM events at once. JFR rotates the recording into chunks as it
|
|
|
188
194
|
grows. `-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold.
|
|
189
195
|
|
|
190
196
|
```sh
|
|
191
|
-
java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
|
|
197
|
+
java -XX:FlightRecorderOptions:stackdepth=2048 -XX:StartFlightRecording=filename=all.jfr,settings=profile,+jdk.InitialEnvironmentVariable#enabled=false,+jdk.SystemProcess#enabled=false -jar app.jar
|
|
192
198
|
jfr summary all.jfr
|
|
193
199
|
```
|
|
194
200
|
|
|
@@ -212,6 +218,9 @@ asprof --all --nofree -d 30 -f all.jfr <pid>
|
|
|
212
218
|
| `-f` | — | Output file path |
|
|
213
219
|
| `-i` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
|
|
214
220
|
| `--all` | — | Enable cpu, wall, alloc, live, nativemem, and lock at once |
|
|
221
|
+
| `-t` | off | Root each stack at its thread's name and id |
|
|
222
|
+
| `-a` | off | Annotate Java frames with how they were compiled |
|
|
223
|
+
| `-g` | off | Append method signatures |
|
|
215
224
|
| `<pid>` | — | Target JVM PID, `jps`, or the application name |
|
|
216
225
|
|
|
217
226
|
`-o` overrides the format the `-f` filename's extension selects. A run with
|
|
@@ -223,3 +232,31 @@ neither writes a text summary.
|
|
|
223
232
|
|
|
224
233
|
The default `cpu` event works on macOS, where it samples CPU time through a
|
|
225
234
|
timer. Hardware events such as `cache-misses` require Linux `perf_events`.
|
|
235
|
+
|
|
236
|
+
### Sharing a recording
|
|
237
|
+
|
|
238
|
+
JFR's `profile` and `default` templates record events that describe the machine
|
|
239
|
+
rather than the program:
|
|
240
|
+
|
|
241
|
+
- `jdk.InitialEnvironmentVariable`: the JVM's environment variables
|
|
242
|
+
- `jdk.SystemProcess`: every process running on the machine
|
|
243
|
+
- `jdk.NativeLibrary`: the loaded libraries
|
|
244
|
+
- `jdk.OSInformation`: the kernel
|
|
245
|
+
- `jdk.InitialSystemProperty`: the system properties
|
|
246
|
+
|
|
247
|
+
The all-events recipe above disables the first two. The `settings=none` recipes
|
|
248
|
+
record only the events they list.
|
|
249
|
+
|
|
250
|
+
async-profiler records the last three by default. `--jfropts 7` omits them,
|
|
251
|
+
along with the CPU and JVM information:
|
|
252
|
+
|
|
253
|
+
```sh
|
|
254
|
+
asprof -d 30 --jfropts 7 -f profile.jfr <pid>
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
To remove events from an existing recording, use `jfr scrub`, which JDK 19 and
|
|
258
|
+
later include:
|
|
259
|
+
|
|
260
|
+
```sh
|
|
261
|
+
jfr scrub --exclude-events jdk.NativeLibrary,jdk.OSInformation,jdk.InitialSystemProperty profile.jfr shared.jfr
|
|
262
|
+
```
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
JavaScript profiling uses the profilers built into Node.js, Deno, Bun, Chrome
|
|
4
4
|
DevTools, and Safari's Web Inspector, which capture CPU profiles, heap profiles,
|
|
5
|
-
and heap snapshots in the V8 and JavaScriptCore formats.
|
|
5
|
+
and heap snapshots in the V8 and JavaScriptCore formats. Node.js and the
|
|
6
|
+
TypeScript compiler also write traces in the Trace Event Format.
|
|
6
7
|
|
|
7
8
|
## CPU profiling
|
|
8
9
|
|
|
@@ -169,6 +170,71 @@ const v8 = generateHeapSnapshot(`v8`)
|
|
|
169
170
|
await Bun.write(`heap.heapsnapshot`, v8)
|
|
170
171
|
```
|
|
171
172
|
|
|
173
|
+
## Runtime tracing
|
|
174
|
+
|
|
175
|
+
Records what the runtime did and when: each garbage collection with the heap's
|
|
176
|
+
size before and after it, the collector's phases on every thread, synchronous
|
|
177
|
+
file system calls, and the lifetime of each async resource. Useful for finding
|
|
178
|
+
how much of a run was spent paused in garbage collection, and why.
|
|
179
|
+
|
|
180
|
+
### CLI
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
node --trace-event-categories v8,v8.execute,node.async_hooks,node.fs.sync,devtools.timeline,disabled-by-default-v8.gc script.js
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
#### Flags
|
|
187
|
+
|
|
188
|
+
| Flag | Default | Description |
|
|
189
|
+
| ----------------------------------- | ---------------------------- | ------------------------------------------------------- |
|
|
190
|
+
| `--trace-event-categories=<list>` | — | Comma-separated categories that enable tracing when set |
|
|
191
|
+
| `--trace-event-file-pattern=<path>` | `node_trace.${rotation}.log` | Path for the trace, which may use `${pid}` |
|
|
192
|
+
|
|
193
|
+
The `devtools.timeline` category records each garbage collection, and
|
|
194
|
+
`disabled-by-default-v8.gc` its phases. The `node.environment` category records
|
|
195
|
+
the process's command line, and `node.fs.async` the path of each file opened, so
|
|
196
|
+
leave both out of a trace you share.
|
|
197
|
+
|
|
198
|
+
### Programmatic API
|
|
199
|
+
|
|
200
|
+
Trace a section of code rather than the whole process:
|
|
201
|
+
|
|
202
|
+
```js
|
|
203
|
+
import { createTracing } from 'node:trace_events'
|
|
204
|
+
|
|
205
|
+
const tracing = createTracing({
|
|
206
|
+
categories: [`v8`, `devtools.timeline`, `disabled-by-default-v8.gc`],
|
|
207
|
+
})
|
|
208
|
+
tracing.enable()
|
|
209
|
+
|
|
210
|
+
// Code to trace...
|
|
211
|
+
|
|
212
|
+
tracing.disable()
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
## Type check tracing
|
|
216
|
+
|
|
217
|
+
Traces the TypeScript compiler building a program: each file it parses, binds,
|
|
218
|
+
and checks, and the type comparisons it samples. Useful for finding the files
|
|
219
|
+
and types that slow a type check.
|
|
220
|
+
|
|
221
|
+
### CLI
|
|
222
|
+
|
|
223
|
+
```sh
|
|
224
|
+
tsc --generateTrace trace-directory
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
#### Flags
|
|
228
|
+
|
|
229
|
+
| Flag | Default | Description |
|
|
230
|
+
| ----------------------- | ------- | ---------------------------------------------- |
|
|
231
|
+
| `--generateTrace <dir>` | — | Output directory that enables tracing when set |
|
|
232
|
+
|
|
233
|
+
The compiler writes `trace.json`, which this tool reads, and `types.json` to the
|
|
234
|
+
directory. It records a type comparison only when the comparison is running at
|
|
235
|
+
one of its 10 ms sampling points, so an event's count excludes the comparisons
|
|
236
|
+
that ran between sampling points.
|
|
237
|
+
|
|
172
238
|
## pprof
|
|
173
239
|
|
|
174
240
|
Node.js can also emit [pprof](https://github.com/google/pprof) profiles via the
|
|
@@ -184,10 +250,19 @@ time spent waiting.
|
|
|
184
250
|
import { writeFile } from 'node:fs/promises'
|
|
185
251
|
import { encode, time } from '@datadog/pprof'
|
|
186
252
|
|
|
187
|
-
const profile = await time.profile({
|
|
253
|
+
const profile = await time.profile({
|
|
254
|
+
durationMillis: 10_000,
|
|
255
|
+
lineNumbers: true,
|
|
256
|
+
})
|
|
188
257
|
await writeFile(`cpu.pb.gz`, await encode(profile))
|
|
189
258
|
```
|
|
190
259
|
|
|
260
|
+
Without `lineNumbers: true`, each function's `Lines` section lists its
|
|
261
|
+
definition line as its only row. With either setting, the profile lacks
|
|
262
|
+
definition lines, and same-named functions in one file merge into one function.
|
|
263
|
+
See
|
|
264
|
+
[DataDog/dd-trace-js#10415](https://github.com/DataDog/dd-trace-js/issues/10415).
|
|
265
|
+
|
|
191
266
|
### Memory profiling
|
|
192
267
|
|
|
193
268
|
Samples heap allocations by stack trace. Useful for finding allocation hot spots
|
|
@@ -197,7 +272,9 @@ and reducing GC pressure.
|
|
|
197
272
|
import { writeFile } from 'node:fs/promises'
|
|
198
273
|
import { encode, heap } from '@datadog/pprof'
|
|
199
274
|
|
|
200
|
-
|
|
275
|
+
// Sampling interval in bytes, and max stack depth. A deeper stack loses its
|
|
276
|
+
// outermost callers
|
|
277
|
+
heap.start(512 * 1024, 1024)
|
|
201
278
|
|
|
202
279
|
// Code to profile...
|
|
203
280
|
|
|
@@ -279,6 +356,13 @@ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
|
|
|
279
356
|
5. Click **Stop Recording**.
|
|
280
357
|
6. Click the **Export** button (arrow icon) and save as a `.json` file.
|
|
281
358
|
|
|
359
|
+
With the **Network** instrument enabled, the export embeds every request and
|
|
360
|
+
response of the recording as a HAR entry: URLs, request and response headers,
|
|
361
|
+
cookies, and request bodies. Those can include session cookies, credentials, and
|
|
362
|
+
your location or public IP address, which some sites store in a cookie or echo
|
|
363
|
+
in a response header. Disable the Network instrument before recording, or redact
|
|
364
|
+
the sensitive headers and cookies before sharing the file.
|
|
365
|
+
|
|
282
366
|
### Heap snapshots
|
|
283
367
|
|
|
284
368
|
Open the **Memory** panel, select **Heap Snapshot**, and click **Take
|
|
@@ -292,3 +376,23 @@ heap snapshot from JavaScript and adds it to the **Memory** panel:
|
|
|
292
376
|
```js
|
|
293
377
|
console.takeHeapSnapshot()
|
|
294
378
|
```
|
|
379
|
+
|
|
380
|
+
## Tips
|
|
381
|
+
|
|
382
|
+
### Startup
|
|
383
|
+
|
|
384
|
+
A CPU profile of a Node.js run includes the time spent compiling each module the
|
|
385
|
+
run loads, and stripping types from each TypeScript module. In a short run, this
|
|
386
|
+
time can be a large share of the profile. To exclude it, run the program once
|
|
387
|
+
without profiling to fill the
|
|
388
|
+
[compile cache](https://nodejs.org/api/module.html#module-compile-cache), then
|
|
389
|
+
profile a second run that loads from it:
|
|
390
|
+
|
|
391
|
+
```sh
|
|
392
|
+
export NODE_COMPILE_CACHE=.node-compile-cache
|
|
393
|
+
node script.ts
|
|
394
|
+
node --cpu-prof script.ts
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Give the first run the same arguments as the profiled run, so it loads the same
|
|
398
|
+
modules.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Nix
|
|
2
|
+
|
|
3
|
+
Nix profiling uses the
|
|
4
|
+
[evaluation profiler](https://nix.dev/manual/nix/latest/advanced-topics/eval-profiler)
|
|
5
|
+
built into Nix 2.30 and later.
|
|
6
|
+
|
|
7
|
+
## Evaluation profiling
|
|
8
|
+
|
|
9
|
+
Samples the Nix function call stack at a fixed rate and writes the samples as
|
|
10
|
+
collapsed stacks. Useful for finding the functions a slow evaluation spends its
|
|
11
|
+
time in.
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
# Profile evaluating a package
|
|
15
|
+
nix-instantiate '<nixpkgs>' -A hello --eval-profiler flamegraph --eval-profile-file eval.collapsed
|
|
16
|
+
|
|
17
|
+
# Profile evaluating a NixOS configuration
|
|
18
|
+
nix-instantiate '<nixpkgs/nixos>' -A system --eval-profiler flamegraph --eval-profile-file eval.collapsed
|
|
19
|
+
|
|
20
|
+
# Profile a flake output
|
|
21
|
+
nix eval --no-eval-cache --eval-profiler flamegraph --eval-profile-file eval.collapsed .#packages.x86_64-linux.default
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Every Nix command that evaluates accepts the flags, and each is also a
|
|
25
|
+
`nix.conf` setting.
|
|
26
|
+
|
|
27
|
+
### Settings
|
|
28
|
+
|
|
29
|
+
| Setting | Default | Description |
|
|
30
|
+
| ------------------------- | ------------- | ------------------------------------------------------------------- |
|
|
31
|
+
| `eval-profiler` | `disabled` | Profiler to enable: `flamegraph` writes collapsed stacks |
|
|
32
|
+
| `eval-profile-file` | `nix.profile` | Output file path |
|
|
33
|
+
| `eval-profiler-frequency` | `99` | Samples per second. `0` samples the stack after every function call |
|
|
34
|
+
|
|
35
|
+
## Tips
|
|
36
|
+
|
|
37
|
+
### Locations are call sites
|
|
38
|
+
|
|
39
|
+
The profiler records where each function was called,
|
|
40
|
+
[by design](https://nix.dev/manual/nix/latest/advanced-topics/eval-profiler), so
|
|
41
|
+
a function appears once per call site and its location is the call site rather
|
|
42
|
+
than its definition. An anonymous lambda has no name, so its call site
|
|
43
|
+
identifies it. When the evaluator cannot resolve a lambda's call site, it prints
|
|
44
|
+
the lambda's definition position in the same shape instead.
|
|
45
|
+
|
|
46
|
+
### Builtins
|
|
47
|
+
|
|
48
|
+
A frame named `primop <name>` is a builtin implemented inside the evaluator,
|
|
49
|
+
located at the Nix expression that called it. `primop derivationStrict:<name>`
|
|
50
|
+
is the `derivation` call that produced the named derivation.
|
|
51
|
+
|
|
52
|
+
### Evaluation cache
|
|
53
|
+
|
|
54
|
+
`nix eval`, `nix build`, and the other flake commands skip evaluation when the
|
|
55
|
+
evaluation cache already holds the output. Pass `--no-eval-cache` to profile a
|
|
56
|
+
full evaluation.
|