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.
@@ -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/), or
6
- [systing](https://github.com/josefbacik/systing).
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
- ### CLI
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
- ### Programmatic API
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
- | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
79
- | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
80
- | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
81
- | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
82
- | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
83
- | `HEAP_PROFILE_ONLY_MMAP` | `false` | Profile only `mmap`/`mremap`/`sbrk`, skipping `malloc`/`new` |
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
- ## Linux perf profiling
289
+ ## Compilation tracing
217
290
 
218
- Samples the call stack through the kernel's own `perf_event` counters, across
219
- user and kernel code. Useful for finding CPU hot spots, including the ones in
220
- the kernel.
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
- # Sample a command at 999 Hz, recording call chains
238
- perf record -F 999 -g -o perf.data -- ./program args
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 | Default | Description |
247
- | -------------- | ----------- | -------------------------------------------------------------------- |
248
- | `-F` | `4000` | Samples per second |
249
- | `-e` | `cycles` | Event to sample (`cpu-clock` where no hardware counter is available) |
250
- | `-g` | off | Record call chains |
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
- A `perf.data` file holds addresses rather than function names. See
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
 
@@ -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 function call instead of sampling, so
52
- output grows with the number of calls. A single invocation over a large input
53
- can produce hundreds of MB.
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
- | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
89
- | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
90
- | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
91
- | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
92
- | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
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, so profiler-md rejects it.
78
+ text report, which is for reading by hand.
79
79
 
80
80
  #### RTS options
81
81
 
@@ -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({ durationMillis: 10_000 })
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
- heap.start(512 * 1024, 64) // Sampling interval in bytes, max stack depth
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.