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.
- package/dist/cli/index.mjs +2607 -1927
- package/dist/index.d.mts +157 -219
- package/dist/index.js +2 -2
- package/docs/formats/collapsed.md +12 -0
- package/docs/languages/cpp.md +136 -0
- package/docs/languages/csharp.md +49 -0
- package/docs/languages/elixir.md +42 -0
- package/docs/languages/erlang.md +42 -0
- package/docs/languages/fsharp.md +49 -0
- package/docs/languages/java.md +10 -7
- package/docs/languages/javascript.md +35 -0
- package/docs/languages/julia.md +42 -0
- package/docs/languages/kotlin.md +120 -0
- package/docs/languages/python.md +10 -4
- package/docs/languages/typescript.md +254 -0
- package/examples/bun.cpuprofile.md +33 -33
- package/examples/deno.cpuprofile.md +9 -9
- package/examples/jsc-heap-snapshot.base.json.md +507 -0
- package/examples/jsc-heap-snapshot.current.json.md +504 -0
- package/examples/jsc-heap-snapshot.diff.json.md +119 -0
- package/examples/node.base.cpuprofile.md +451 -0
- package/examples/node.current.cpuprofile.md +449 -0
- package/examples/node.diff.cpuprofile.md +82 -0
- package/examples/node.heapprofile.md +33 -33
- package/examples/node.heapsnapshot.md +46 -46
- package/examples/node.pprof.md +3 -3
- package/examples/python.base.collapsed.md +116 -0
- package/examples/python.current.collapsed.md +125 -0
- package/examples/python.diff.collapsed.md +51 -0
- package/examples/{rust.pprof.md → rust.base.pprof.md} +199 -199
- package/examples/rust.current.pprof.md +480 -0
- package/examples/rust.diff.pprof.md +117 -0
- package/examples/webkit-timeline-recording.json.md +296 -296
- package/package.json +21 -18
- package/readme.md +106 -80
- package/examples/jsc-heap-snapshot.json.md +0 -509
- package/examples/node.cpuprofile.md +0 -485
- 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 |
|
package/docs/languages/java.md
CHANGED
|
@@ -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) |
|
package/docs/languages/python.md
CHANGED
|
@@ -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
|
-
#
|
|
13
|
-
|
|
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
|
-
#
|
|
16
|
-
py-spy record -f
|
|
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
|