profiler-md 0.2.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 (41) hide show
  1. package/dist/cli/index.mjs +2787 -1669
  2. package/dist/index.d.mts +249 -78
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/formats/jsc-heap-snapshot.md +13 -0
  6. package/docs/formats/webkit-timeline-recording.md +9 -0
  7. package/docs/languages/c.md +1 -1
  8. package/docs/languages/cpp.md +136 -0
  9. package/docs/languages/csharp.md +49 -0
  10. package/docs/languages/elixir.md +42 -0
  11. package/docs/languages/erlang.md +42 -0
  12. package/docs/languages/fsharp.md +49 -0
  13. package/docs/languages/go.md +2 -2
  14. package/docs/languages/java.md +10 -7
  15. package/docs/languages/javascript.md +69 -0
  16. package/docs/languages/julia.md +42 -0
  17. package/docs/languages/kotlin.md +120 -0
  18. package/docs/languages/python.md +10 -4
  19. package/docs/languages/typescript.md +254 -0
  20. package/examples/bun.cpuprofile.md +94 -116
  21. package/examples/deno.cpuprofile.md +11 -18
  22. package/examples/jsc-heap-snapshot.base.json.md +507 -0
  23. package/examples/jsc-heap-snapshot.current.json.md +504 -0
  24. package/examples/jsc-heap-snapshot.diff.json.md +119 -0
  25. package/examples/node.base.cpuprofile.md +451 -0
  26. package/examples/node.current.cpuprofile.md +449 -0
  27. package/examples/node.diff.cpuprofile.md +82 -0
  28. package/examples/node.heapprofile.md +178 -223
  29. package/examples/node.heapsnapshot.md +268 -266
  30. package/examples/node.pprof.md +36 -45
  31. package/examples/python.base.collapsed.md +116 -0
  32. package/examples/python.current.collapsed.md +125 -0
  33. package/examples/python.diff.collapsed.md +51 -0
  34. package/examples/{rust1.pprof.md → rust.base.pprof.md} +223 -226
  35. package/examples/{rust2.pprof.md → rust.current.pprof.md} +199 -199
  36. package/examples/rust.diff.pprof.md +117 -0
  37. package/examples/webkit-timeline-recording.json.md +434 -0
  38. package/package.json +30 -18
  39. package/readme.md +173 -85
  40. package/examples/node.cpuprofile.md +0 -499
  41. package/examples/node.speedscope.json.md +0 -416
@@ -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,13 @@
1
+ # JSC heap snapshot
2
+
3
+ The
4
+ [JSC heap snapshot](https://webkit.org/blog/6425/memory-debugging-with-web-inspector)
5
+ is a JSON format produced by JavaScriptCore, the engine powering Safari and
6
+ WebKit, that captures the full live object graph at a point in time.
7
+
8
+ Unlike heap profiles, which sample allocations, snapshots show what objects
9
+ currently exist in memory. This is useful for diagnosing memory leaks rather
10
+ than allocation hotspots.
11
+
12
+ Files use the `.json` extension and contain `"type": "Inspector"` and
13
+ `"version": 2` fields.
@@ -0,0 +1,9 @@
1
+ # WebKit timeline recording
2
+
3
+ The [WebKit timeline recording](https://webkit.org/web-inspector/timelines-tab)
4
+ is a JSON format captured by Safari's Web Inspector. It combines a CPU profile
5
+ from sampling, a browser activity breakdown (layout, rendering, script
6
+ execution, network requests), and optionally in-use memory readings and heap
7
+ allocation snapshots when those instruments are enabled.
8
+
9
+ Files use the `.json` extension.
@@ -88,7 +88,7 @@ HeapProfilerStart("heap.prof");
88
88
 
89
89
  // Code to profile...
90
90
 
91
- HeapProfilerDump("checkpoint"); // optional mid-run snapshot
91
+ HeapProfilerDump("checkpoint"); // optional mid-run profile dump
92
92
  HeapProfilerStop();
93
93
  ```
94
94
 
@@ -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 |
@@ -41,7 +41,7 @@ defer pprof.StopCPUProfile()
41
41
  Heap profiles come in two variants:
42
42
 
43
43
  - **heap** (`inuse_space` / `inuse_objects`): live allocations at the time of
44
- the snapshot; useful for finding memory leaks
44
+ the time of each sample; useful for finding memory leaks
45
45
  - **allocs** (`alloc_space` / `alloc_objects`): all allocations since program
46
46
  start; useful for finding allocation hot spots
47
47
 
@@ -74,7 +74,7 @@ import (
74
74
  "runtime/pprof"
75
75
  )
76
76
 
77
- runtime.GC() // Flush pending samples before snapshotting
77
+ runtime.GC() // Flush pending samples before writing the profile
78
78
 
79
79
  // Live heap
80
80
  f, _ := os.Create("heap.pprof")
@@ -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
@@ -183,3 +218,37 @@ Stop when done to see allocation hot spots by call stack.
183
218
 
184
219
  Open the **Memory** panel, select **Heap snapshot**, and click **Take
185
220
  snapshot**.
221
+
222
+ ## Safari Web Inspector
223
+
224
+ Safari's Web Inspector records a timeline that combines CPU sampling, browser
225
+ activity, and optionally memory readings and heap allocations, all exported as a
226
+ single file.
227
+
228
+ ### Connecting
229
+
230
+ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
231
+
232
+ ### Recording
233
+
234
+ 1. Click the **Timelines** tab.
235
+ 2. Enable the instruments you want: **JavaScript & Events** (always), and
236
+ optionally **Memory** and **JavaScript Allocations**.
237
+ 3. Click **Start Recording** (or ⌘R).
238
+ 4. Reproduce the scenario you want to profile.
239
+ 5. Click **Stop Recording**.
240
+ 6. Click the **Export** button (arrow icon) and save as a `.json` file.
241
+
242
+ ### Heap snapshots
243
+
244
+ Open the **Memory** panel, select **Heap Snapshot**, and click **Take
245
+ Snapshot**.
246
+
247
+ #### Programmatic API
248
+
249
+ `console.takeHeapSnapshot()` is a non-standard WebKit extension that takes a
250
+ heap snapshot from JavaScript and adds it to the **Memory** panel:
251
+
252
+ ```js
253
+ console.takeHeapSnapshot()
254
+ ```
@@ -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