profiler-md 0.3.0 → 0.4.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.
Files changed (38) hide show
  1. package/dist/cli/index.mjs +2607 -1927
  2. package/dist/index.d.mts +157 -219
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/languages/cpp.md +136 -0
  6. package/docs/languages/csharp.md +49 -0
  7. package/docs/languages/elixir.md +42 -0
  8. package/docs/languages/erlang.md +42 -0
  9. package/docs/languages/fsharp.md +49 -0
  10. package/docs/languages/java.md +10 -7
  11. package/docs/languages/javascript.md +35 -0
  12. package/docs/languages/julia.md +42 -0
  13. package/docs/languages/kotlin.md +120 -0
  14. package/docs/languages/python.md +10 -4
  15. package/docs/languages/typescript.md +254 -0
  16. package/examples/bun.cpuprofile.md +33 -33
  17. package/examples/deno.cpuprofile.md +9 -9
  18. package/examples/jsc-heap-snapshot.base.json.md +507 -0
  19. package/examples/jsc-heap-snapshot.current.json.md +504 -0
  20. package/examples/jsc-heap-snapshot.diff.json.md +119 -0
  21. package/examples/node.base.cpuprofile.md +451 -0
  22. package/examples/node.current.cpuprofile.md +449 -0
  23. package/examples/node.diff.cpuprofile.md +82 -0
  24. package/examples/node.heapprofile.md +33 -33
  25. package/examples/node.heapsnapshot.md +46 -46
  26. package/examples/node.pprof.md +3 -3
  27. package/examples/python.base.collapsed.md +116 -0
  28. package/examples/python.current.collapsed.md +125 -0
  29. package/examples/python.diff.collapsed.md +51 -0
  30. package/examples/{rust.pprof.md → rust.base.pprof.md} +199 -199
  31. package/examples/rust.current.pprof.md +480 -0
  32. package/examples/rust.diff.pprof.md +117 -0
  33. package/examples/webkit-timeline-recording.json.md +296 -296
  34. package/package.json +21 -18
  35. package/readme.md +106 -80
  36. package/examples/jsc-heap-snapshot.json.md +0 -509
  37. package/examples/node.cpuprofile.md +0 -485
  38. package/examples/node.speedscope.json.md +0 -408
@@ -0,0 +1,12 @@
1
+ # Collapsed stacks
2
+
3
+ Collapsed stacks is the plain-text interchange format from Brendan Gregg's
4
+ [FlameGraph](https://github.com/brendangregg/FlameGraph) tooling. It is emitted
5
+ by many profilers.
6
+
7
+ Each line is one call stack, written root-to-leaf and joined by `;`, followed by
8
+ a space and an integer sample count. Frames are opaque strings and carry no
9
+ units.
10
+
11
+ Files have no standard extension; `.collapsed`, `.folded`, and `.txt` are all
12
+ common.
@@ -0,0 +1,136 @@
1
+ # C/C++
2
+
3
+ C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools).
4
+
5
+ ## CPU profiling
6
+
7
+ Periodically samples the call stack. Useful for finding CPU hot spots.
8
+
9
+ Link with `-lprofiler`:
10
+
11
+ ```sh
12
+ gcc -O2 -lprofiler -o program program.c # C
13
+ g++ -O2 -lprofiler -o program program.cpp # C++
14
+ ```
15
+
16
+ ### CLI
17
+
18
+ ```sh
19
+ # Generate a CPU profile
20
+ CPUPROFILE=cpu.prof ./program
21
+
22
+ # Convert to pprof protobuf format
23
+ pprof --proto ./program cpu.prof > cpu.pprof
24
+ ```
25
+
26
+ #### Environment variables
27
+
28
+ | Variable | Default | Description |
29
+ | ---------------------- | ------- | -------------------------------------------------------------------------------- |
30
+ | `CPUPROFILE` | — | Output filename; profiling is enabled when set |
31
+ | `CPUPROFILE_FREQUENCY` | `100` | Samples per second |
32
+ | `CPUPROFILE_REALTIME` | — | Use wall-clock time (`ITIMER_REAL`) instead of CPU time (`ITIMER_PROF`) when set |
33
+ | `CPUPROFILESIGNAL` | — | Signal number to toggle profiling on/off at runtime |
34
+
35
+ ### Programmatic API
36
+
37
+ ```c
38
+ #include <gperftools/profiler.h>
39
+
40
+ ProfilerStart("cpu.prof");
41
+
42
+ // Code to profile...
43
+
44
+ ProfilerFlush(); // optional: flush buffered samples mid-run
45
+ ProfilerStop();
46
+ ```
47
+
48
+ ## Memory profiling
49
+
50
+ Periodically dumps the live heap, capturing allocation stack traces. Useful for
51
+ finding memory leaks and allocation hot spots.
52
+
53
+ Link with `-ltcmalloc`:
54
+
55
+ ```sh
56
+ gcc -O2 -ltcmalloc -o program program.c # C
57
+ g++ -O2 -ltcmalloc -o program program.cpp # C++
58
+ ```
59
+
60
+ ### CLI
61
+
62
+ ```sh
63
+ # Generate heap profiles (written as <prefix>.0000.heap, .0001.heap, …)
64
+ HEAPPROFILE=heap.prof ./program
65
+
66
+ # Convert a heap profile to pprof protobuf format
67
+ pprof --proto ./program heap.prof.0001.heap > heap.pprof
68
+ ```
69
+
70
+ #### Environment variables
71
+
72
+ | Variable | Default | Description |
73
+ | ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
74
+ | `HEAPPROFILE` | — | Output filename prefix; heap profiling is enabled when set |
75
+ | `HEAP_PROFILE_ALLOCATION_INTERVAL` | `1073741824` | Dump a profile after every this many bytes allocated (default 1 GB) |
76
+ | `HEAP_PROFILE_INUSE_INTERVAL` | `104857600` | Dump a profile each time the in-use high-water mark grows by this many bytes (default 100 MB) |
77
+ | `HEAP_PROFILE_TIME_INTERVAL` | `0` | Dump a profile every this many seconds (disabled by default) |
78
+ | `HEAPPROFILESIGNAL` | — | Signal number to dump a profile on demand |
79
+ | `HEAP_PROFILE_MMAP` | `false` | Also profile `mmap`/`mremap`/`sbrk` calls |
80
+ | `HEAP_PROFILE_ONLY_MMAP` | `false` | Profile only `mmap`/`mremap`/`sbrk`; skip `malloc`/`new` |
81
+
82
+ ### Programmatic API
83
+
84
+ ```c
85
+ #include <gperftools/heap-profiler.h>
86
+
87
+ HeapProfilerStart("heap.prof");
88
+
89
+ // Code to profile...
90
+
91
+ HeapProfilerDump("checkpoint"); // optional mid-run profile dump
92
+ HeapProfilerStop();
93
+ ```
94
+
95
+ ## Heap checking
96
+
97
+ Compares the heap state before and after a region of code to detect memory
98
+ leaks. Useful for confirming that a code path frees everything it allocates.
99
+
100
+ Link with `-ltcmalloc`:
101
+
102
+ ```sh
103
+ gcc -O2 -ltcmalloc -o program program.c # C
104
+ g++ -O2 -ltcmalloc -o program program.cpp # C++
105
+ ```
106
+
107
+ ### CLI
108
+
109
+ ```sh
110
+ # Report leaks at program exit
111
+ HEAPCHECK=normal ./program
112
+
113
+ # Also report still-reachable allocations at exit
114
+ HEAPCHECK=strict ./program
115
+
116
+ # Most aggressive: report all live allocations at exit
117
+ HEAPCHECK=draconian ./program
118
+ ```
119
+
120
+ #### Environment variables
121
+
122
+ | Variable | Default | Description |
123
+ | ----------- | ------- | ------------------------------------------------------------------------------------ |
124
+ | `HEAPCHECK` | — | Leak-checking mode (`minimal`, `normal`, `strict`, or `draconian`); enabled when set |
125
+
126
+ ### Programmatic API
127
+
128
+ ```c
129
+ #include <gperftools/heap-checker.h>
130
+
131
+ HeapLeakChecker checker("my_check");
132
+
133
+ // Code to check...
134
+
135
+ if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
136
+ ```
@@ -0,0 +1,49 @@
1
+ # C#/F#
2
+
3
+ .NET profiling (C#, F#, and other CLR languages) uses
4
+ [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace),
5
+ a cross-platform diagnostics tool that collects traces through the runtime's
6
+ EventPipe without a native profiler.
7
+
8
+ Install it as a global tool:
9
+
10
+ ```sh
11
+ dotnet tool install --global dotnet-trace
12
+ ```
13
+
14
+ ## CPU profiling
15
+
16
+ Periodically samples the call stack. Useful for finding CPU hot spots.
17
+
18
+ With no `--profile` or `--providers`, `dotnet-trace collect` enables the
19
+ `dotnet-common` and `dotnet-sampled-thread-time` profiles, sampling thread
20
+ stacks at roughly 100 Hz.
21
+
22
+ ### CLI
23
+
24
+ ```sh
25
+ # Attach to a running process, written directly as speedscope
26
+ dotnet-trace collect --process-id <pid> --format speedscope
27
+
28
+ # Launch and trace a command from startup (use `dotnet exec` so the dotnet CLI's
29
+ # own child processes aren't traced instead of your app)
30
+ dotnet-trace collect --format speedscope -- dotnet exec app.dll
31
+
32
+ # Attach for a fixed duration (dd:hh:mm:ss)
33
+ dotnet-trace collect --process-id <pid> --duration 00:00:00:30 --format speedscope
34
+
35
+ # Convert an existing .nettrace to speedscope
36
+ dotnet-trace convert trace.nettrace --format speedscope
37
+ ```
38
+
39
+ #### Flags
40
+
41
+ | Flag | Default | Description |
42
+ | --------------------- | ---------- | --------------------------------------------------- |
43
+ | `-p` / `--process-id` | — | PID of the process to trace |
44
+ | `-n` / `--name` | — | Name of the process to trace |
45
+ | `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
46
+ | `-o` / `--output` | `nettrace` | Output file path |
47
+ | `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
48
+ | `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
49
+ | `--providers` | — | Comma-separated EventPipe providers to enable |
@@ -0,0 +1,42 @@
1
+ # Elixir/Erlang
2
+
3
+ Elixir and Erlang profiling uses
4
+ [eflambe](https://github.com/Stratus3D/eflambe), a profiler for the BEAM that
5
+ wraps the runtime's built-in tracing and writes flame graph output.
6
+
7
+ ## CPU profiling
8
+
9
+ Traces function calls and writes them as collapsed stacks. Useful for finding
10
+ CPU hot spots.
11
+
12
+ eflambe's default `brendan_gregg` output format is collapsed stacks. Add
13
+ `eflambe` to your dependencies, then profile a specific function.
14
+
15
+ ### Elixir
16
+
17
+ ```elixir
18
+ # Profile a function as it runs during normal execution (capture 1 call)
19
+ :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
20
+
21
+ # Directly invoke and profile a function
22
+ :eflambe.apply({MyModule, :my_function, [arg1, arg2]}, output_format: :brendan_gregg)
23
+ ```
24
+
25
+ ### Erlang
26
+
27
+ ```erlang
28
+ %% Profile a function as it runs during normal execution (capture 1 call)
29
+ eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
30
+
31
+ %% Directly invoke and profile a function
32
+ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_gregg}]).
33
+ ```
34
+
35
+ ### Options
36
+
37
+ | Option | Default | Description |
38
+ | ------------------ | --------------- | --------------------------------------------------- |
39
+ | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
40
+ | `output_directory` | project root | Directory to write the output file to |
41
+ | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
42
+ | `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
@@ -0,0 +1,42 @@
1
+ # Elixir/Erlang
2
+
3
+ Elixir and Erlang profiling uses
4
+ [eflambe](https://github.com/Stratus3D/eflambe), a profiler for the BEAM that
5
+ wraps the runtime's built-in tracing and writes flame graph output.
6
+
7
+ ## CPU profiling
8
+
9
+ Traces function calls and writes them as collapsed stacks. Useful for finding
10
+ CPU hot spots.
11
+
12
+ eflambe's default `brendan_gregg` output format is collapsed stacks. Add
13
+ `eflambe` to your dependencies, then profile a specific function.
14
+
15
+ ### Elixir
16
+
17
+ ```elixir
18
+ # Profile a function as it runs during normal execution (capture 1 call)
19
+ :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
20
+
21
+ # Directly invoke and profile a function
22
+ :eflambe.apply({MyModule, :my_function, [arg1, arg2]}, output_format: :brendan_gregg)
23
+ ```
24
+
25
+ ### Erlang
26
+
27
+ ```erlang
28
+ %% Profile a function as it runs during normal execution (capture 1 call)
29
+ eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
30
+
31
+ %% Directly invoke and profile a function
32
+ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_gregg}]).
33
+ ```
34
+
35
+ ### Options
36
+
37
+ | Option | Default | Description |
38
+ | ------------------ | --------------- | --------------------------------------------------- |
39
+ | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
40
+ | `output_directory` | project root | Directory to write the output file to |
41
+ | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
42
+ | `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
@@ -0,0 +1,49 @@
1
+ # C#/F#
2
+
3
+ .NET profiling (C#, F#, and other CLR languages) uses
4
+ [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace),
5
+ a cross-platform diagnostics tool that collects traces through the runtime's
6
+ EventPipe without a native profiler.
7
+
8
+ Install it as a global tool:
9
+
10
+ ```sh
11
+ dotnet tool install --global dotnet-trace
12
+ ```
13
+
14
+ ## CPU profiling
15
+
16
+ Periodically samples the call stack. Useful for finding CPU hot spots.
17
+
18
+ With no `--profile` or `--providers`, `dotnet-trace collect` enables the
19
+ `dotnet-common` and `dotnet-sampled-thread-time` profiles, sampling thread
20
+ stacks at roughly 100 Hz.
21
+
22
+ ### CLI
23
+
24
+ ```sh
25
+ # Attach to a running process, written directly as speedscope
26
+ dotnet-trace collect --process-id <pid> --format speedscope
27
+
28
+ # Launch and trace a command from startup (use `dotnet exec` so the dotnet CLI's
29
+ # own child processes aren't traced instead of your app)
30
+ dotnet-trace collect --format speedscope -- dotnet exec app.dll
31
+
32
+ # Attach for a fixed duration (dd:hh:mm:ss)
33
+ dotnet-trace collect --process-id <pid> --duration 00:00:00:30 --format speedscope
34
+
35
+ # Convert an existing .nettrace to speedscope
36
+ dotnet-trace convert trace.nettrace --format speedscope
37
+ ```
38
+
39
+ #### Flags
40
+
41
+ | Flag | Default | Description |
42
+ | --------------------- | ---------- | --------------------------------------------------- |
43
+ | `-p` / `--process-id` | — | PID of the process to trace |
44
+ | `-n` / `--name` | — | Name of the process to trace |
45
+ | `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
46
+ | `-o` / `--output` | `nettrace` | Output file path |
47
+ | `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
48
+ | `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
49
+ | `--providers` | — | Comma-separated EventPipe providers to enable |
@@ -11,6 +11,9 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
11
11
  ### CLI
12
12
 
13
13
  ```sh
14
+ # Attach to a running process (collapsed format)
15
+ asprof -d 30 -f cpu.collapsed -o collapsed <pid>
16
+
14
17
  # Attach to a running process (pprof format)
15
18
  asprof -d 30 -f cpu.pprof <pid>
16
19
 
@@ -108,10 +111,10 @@ profiler.execute("stop");
108
111
 
109
112
  ## CLI flags
110
113
 
111
- | Flag | Default | Description |
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) |
114
+ | Flag | Default | Description |
115
+ | ------------------- | ------- | -------------------------------------------------------- |
116
+ | `-d` / `--duration` | — | Duration in seconds |
117
+ | `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock` |
118
+ | `-f` / `--file` | — | Output file path |
119
+ | `-o` / `--output` | `jfr` | Output format: `collapsed`, `jfr`, `pprof`, `speedscope` |
120
+ | `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
@@ -134,6 +134,41 @@ import { writeHeapSnapshot } from 'node:v8'
134
134
  writeHeapSnapshot(`heap.heapsnapshot`)
135
135
  ```
136
136
 
137
+ ## pprof
138
+
139
+ Node.js can also emit [pprof](https://github.com/google/pprof) profiles via the
140
+ [`@datadog/pprof`](https://www.npmjs.com/package/@datadog/pprof) package, which
141
+ profiles a section of code rather than the whole process.
142
+
143
+ ### CPU profiling
144
+
145
+ Samples wall-clock time across all threads. Useful for finding CPU hot spots and
146
+ time spent waiting.
147
+
148
+ ```js
149
+ import { writeFile } from 'node:fs/promises'
150
+ import { encode, time } from '@datadog/pprof'
151
+
152
+ const profile = await time.profile({ durationMillis: 10_000 })
153
+ await writeFile(`cpu.pb.gz`, await encode(profile))
154
+ ```
155
+
156
+ ### Memory profiling
157
+
158
+ Samples heap allocations by stack trace. Useful for finding allocation hot spots
159
+ and reducing GC pressure.
160
+
161
+ ```js
162
+ import { writeFile } from 'node:fs/promises'
163
+ import { encode, heap } from '@datadog/pprof'
164
+
165
+ heap.start(512 * 1024, 64) // Sampling interval in bytes, max stack depth
166
+
167
+ // Code to profile...
168
+
169
+ await writeFile(`heap.pb.gz`, await encode(await heap.profile()))
170
+ ```
171
+
137
172
  ## Chrome DevTools
138
173
 
139
174
  Chrome DevTools can profile JavaScript running in the browser or connected to
@@ -0,0 +1,42 @@
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
+ Profile.clear()
16
+ @profile my_function()
17
+
18
+ # Write profile.pb.gz without launching the web UI
19
+ pprof(out = "cpu.pb.gz", web = false)
20
+ ```
21
+
22
+ ## Memory profiling
23
+
24
+ Samples heap allocations. Useful for finding allocation hot spots and reducing
25
+ GC pressure.
26
+
27
+ ```julia
28
+ using Profile, PProf
29
+
30
+ Profile.Allocs.clear()
31
+ Profile.Allocs.@profile my_function()
32
+
33
+ PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
34
+ ```
35
+
36
+ ## `pprof` options
37
+
38
+ | Option | Default | Description |
39
+ | -------- | ----------------- | --------------------------------------------- |
40
+ | `out` | `"profile.pb.gz"` | Output file path |
41
+ | `web` | `true` | Launch the interactive web UI after exporting |
42
+ | `from_c` | `true` | Include C and Julia runtime frames |
@@ -0,0 +1,120 @@
1
+ # Java/Kotlin
2
+
3
+ Java and Kotlin profiling uses
4
+ [async-profiler](https://github.com/async-profiler/async-profiler), a low
5
+ overhead sampling profiler that works with any JVM language.
6
+
7
+ ## CPU profiling
8
+
9
+ Periodically samples the call stack. Useful for finding CPU hot spots.
10
+
11
+ ### CLI
12
+
13
+ ```sh
14
+ # Attach to a running process (collapsed format)
15
+ asprof -d 30 -f cpu.collapsed -o collapsed <pid>
16
+
17
+ # Attach to a running process (pprof format)
18
+ asprof -d 30 -f cpu.pprof <pid>
19
+
20
+ # Attach to a running process (speedscope format)
21
+ asprof -d 30 -f profile.speedscope -o speedscope <pid>
22
+
23
+ # Profile a command directly
24
+ asprof -d 30 -f cpu.pprof -- java -jar app.jar
25
+ ```
26
+
27
+ ### Programmatic API
28
+
29
+ Add `async-profiler` to your dependencies, then:
30
+
31
+ ```java
32
+ import one.profiler.AsyncProfiler;
33
+
34
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
35
+ profiler.execute("start,event=cpu,file=cpu.jfr");
36
+
37
+ // Code to profile...
38
+
39
+ profiler.execute("stop");
40
+ ```
41
+
42
+ ## Wall-clock profiling
43
+
44
+ Samples wall-clock time rather than CPU time. Useful for I/O-bound or
45
+ latency-sensitive code where threads spend time waiting.
46
+
47
+ ### CLI
48
+
49
+ ```sh
50
+ asprof -d 30 -e wall -f profile.pprof <pid>
51
+ ```
52
+
53
+ ### Programmatic API
54
+
55
+ ```java
56
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
57
+ profiler.execute("start,event=wall,file=profile.jfr");
58
+
59
+ // Code to profile...
60
+
61
+ profiler.execute("stop");
62
+ ```
63
+
64
+ ## Memory profiling
65
+
66
+ Samples heap allocations. Useful for finding allocation hot spots and reducing
67
+ GC pressure.
68
+
69
+ ### CLI
70
+
71
+ ```sh
72
+ # Attach to a running process (pprof format)
73
+ asprof -d 30 -e alloc -f mem.pprof <pid>
74
+
75
+ # Profile a command directly
76
+ asprof -d 30 -e alloc -f mem.pprof -- java -jar app.jar
77
+ ```
78
+
79
+ ### Programmatic API
80
+
81
+ ```java
82
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
83
+ profiler.execute("start,event=alloc,file=mem.jfr");
84
+
85
+ // Code to profile...
86
+
87
+ profiler.execute("stop");
88
+ ```
89
+
90
+ ## Lock profiling
91
+
92
+ Samples contended monitor locks (`synchronized`, `ReentrantLock`, and other
93
+ `java.util.concurrent` locks). Useful for finding lock contention hot spots.
94
+
95
+ ### CLI
96
+
97
+ ```sh
98
+ asprof -d 30 -e lock -f lock.pprof <pid>
99
+ ```
100
+
101
+ ### Programmatic API
102
+
103
+ ```java
104
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
105
+ profiler.execute("start,event=lock,file=lock.jfr");
106
+
107
+ // Code to profile...
108
+
109
+ profiler.execute("stop");
110
+ ```
111
+
112
+ ## CLI flags
113
+
114
+ | Flag | Default | Description |
115
+ | ------------------- | ------- | -------------------------------------------------------- |
116
+ | `-d` / `--duration` | — | Duration in seconds |
117
+ | `-e` / `--event` | `cpu` | Event to profile: `cpu`, `wall`, `alloc`, `lock` |
118
+ | `-f` / `--file` | — | Output file path |
119
+ | `-o` / `--output` | `jfr` | Output format: `collapsed`, `jfr`, `pprof`, `speedscope` |
120
+ | `-i` / `--interval` | `10ms` | Sampling interval (e.g. `-i 1ms` for 1000 Hz) |
@@ -9,11 +9,17 @@ profiler that attaches to a running process or wraps a script, and
9
9
  Periodically samples the call stack. Useful for finding CPU hot spots.
10
10
 
11
11
  ```sh
12
- # pprof format (wrap a script)
13
- py-spy record -f pprof -o cpu.pprof -- python script.py
12
+ # Collapsed format (python 3.15+)
13
+ python -m profiling.sampling run --collapsed -o cpu.collapsed script.py
14
+
15
+ # Collapsed format (wrap a script)
16
+ py-spy record -f raw -o cpu.collapsed -- python script.py
14
17
 
15
- # pprof format (attach to a running process)
16
- py-spy record -f pprof -o cpu.pprof --pid <pid>
18
+ # Collapsed format (attach to a running process)
19
+ py-spy record -f raw -o cpu.collapsed --pid <pid>
20
+
21
+ # pprof format
22
+ py-spy record -f pprof -o cpu.pprof -- python script.py
17
23
 
18
24
  # Speedscope format
19
25
  py-spy record -f speedscope -o profile.speedscope -- python script.py