profiler-md 0.3.0 → 0.5.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 +5331 -2044
- package/dist/index.d.mts +738 -229
- package/dist/index.js +2 -2
- package/docs/formats/collapsed.md +12 -0
- package/docs/formats/jfr.md +16 -0
- package/docs/formats/jsc-heap-snapshot.md +2 -2
- package/docs/languages/c.md +31 -7
- package/docs/languages/cpp.md +160 -0
- package/docs/languages/csharp.md +52 -0
- package/docs/languages/elixir.md +46 -0
- package/docs/languages/erlang.md +46 -0
- package/docs/languages/fsharp.md +52 -0
- package/docs/languages/go.md +11 -6
- package/docs/languages/java.md +110 -57
- package/docs/languages/javascript.md +69 -12
- package/docs/languages/julia.md +54 -0
- package/docs/languages/kotlin.md +170 -0
- package/docs/languages/php.md +64 -20
- package/docs/languages/python.md +13 -68
- package/docs/languages/ruby.md +17 -27
- package/docs/languages/typescript.md +276 -0
- package/examples/output/c.gperftools.cpu.base.pprof.md +324 -0
- package/examples/output/c.gperftools.cpu.current.pprof.md +271 -0
- package/examples/output/c.gperftools.cpu.diff.pprof.md +98 -0
- package/examples/output/c.gperftools.heap.base.pprof.md +362 -0
- package/examples/output/c.gperftools.heap.current.pprof.md +362 -0
- package/examples/output/c.gperftools.heap.diff.pprof.md +28 -0
- package/examples/output/cpp.gperftools.cpu.base.pprof.md +557 -0
- package/examples/output/cpp.gperftools.cpu.current.pprof.md +573 -0
- package/examples/output/cpp.gperftools.cpu.diff.pprof.md +122 -0
- package/examples/output/cpp.gperftools.heap.base.pprof.md +67 -0
- package/examples/output/cpp.gperftools.heap.current.pprof.md +67 -0
- package/examples/output/cpp.gperftools.heap.diff.pprof.md +19 -0
- package/examples/output/csharp.dotnet-trace.base.speedscope.json.md +411 -0
- package/examples/output/csharp.dotnet-trace.current.speedscope.json.md +412 -0
- package/examples/output/csharp.dotnet-trace.diff.speedscope.json.md +122 -0
- package/examples/output/elixir.eflambe.cpu.base.collapsed.md +399 -0
- package/examples/output/elixir.eflambe.cpu.current.collapsed.md +398 -0
- package/examples/output/elixir.eflambe.cpu.diff.collapsed.md +92 -0
- package/examples/output/erlang.eflambe.cpu.base.collapsed.md +147 -0
- package/examples/output/erlang.eflambe.cpu.current.collapsed.md +147 -0
- package/examples/output/erlang.eflambe.cpu.diff.collapsed.md +18 -0
- package/examples/output/fsharp.dotnet-trace.base.speedscope.json.md +324 -0
- package/examples/output/fsharp.dotnet-trace.current.speedscope.json.md +314 -0
- package/examples/output/fsharp.dotnet-trace.diff.speedscope.json.md +119 -0
- package/examples/output/go.pprof.block.base.pprof.md +86 -0
- package/examples/output/go.pprof.block.current.pprof.md +83 -0
- package/examples/output/go.pprof.block.diff.pprof.md +42 -0
- package/examples/output/go.pprof.cpu.base.pprof.md +81 -0
- package/examples/output/go.pprof.cpu.current.pprof.md +70 -0
- package/examples/output/go.pprof.cpu.diff.pprof.md +52 -0
- package/examples/output/go.pprof.goroutine.base.pprof.md +43 -0
- package/examples/output/go.pprof.goroutine.current.pprof.md +43 -0
- package/examples/output/go.pprof.goroutine.diff.pprof.md +13 -0
- package/examples/output/go.pprof.heap-alloc.base.pprof.md +154 -0
- package/examples/output/go.pprof.heap-alloc.current.pprof.md +146 -0
- package/examples/output/go.pprof.heap-alloc.diff.pprof.md +67 -0
- package/examples/output/go.pprof.heap.base.pprof.md +154 -0
- package/examples/output/go.pprof.heap.current.pprof.md +146 -0
- package/examples/output/go.pprof.heap.diff.pprof.md +67 -0
- package/examples/output/go.pprof.mutex.base.pprof.md +55 -0
- package/examples/output/go.pprof.mutex.current.pprof.md +41 -0
- package/examples/output/go.pprof.mutex.diff.pprof.md +31 -0
- package/examples/output/go.pprof.threadcreate.base.pprof.md +55 -0
- package/examples/output/go.pprof.threadcreate.current.pprof.md +55 -0
- package/examples/output/go.pprof.threadcreate.diff.pprof.md +19 -0
- package/examples/output/java.async-profiler.all.base.jfr.md +1071 -0
- package/examples/output/java.async-profiler.all.current.jfr.md +1007 -0
- package/examples/output/java.async-profiler.all.diff.jfr.md +268 -0
- package/examples/output/java.async-profiler.alloc.base.jfr.md +425 -0
- package/examples/output/java.async-profiler.alloc.current.jfr.md +413 -0
- package/examples/output/java.async-profiler.alloc.diff.jfr.md +99 -0
- package/examples/output/java.async-profiler.cpu.base.collapsed.md +367 -0
- package/examples/output/java.async-profiler.cpu.base.jfr.md +485 -0
- package/examples/output/java.async-profiler.cpu.current.collapsed.md +355 -0
- package/examples/output/java.async-profiler.cpu.current.jfr.md +488 -0
- package/examples/output/java.async-profiler.cpu.diff.collapsed.md +117 -0
- package/examples/output/java.async-profiler.cpu.diff.jfr.md +118 -0
- package/examples/output/java.async-profiler.live.base.jfr.md +697 -0
- package/examples/output/java.async-profiler.live.current.jfr.md +684 -0
- package/examples/output/java.async-profiler.live.diff.jfr.md +191 -0
- package/examples/output/java.async-profiler.lock.base.jfr.md +140 -0
- package/examples/output/java.async-profiler.lock.current.jfr.md +108 -0
- package/examples/output/java.async-profiler.lock.diff.jfr.md +44 -0
- package/examples/output/java.async-profiler.nativemem.base.jfr.md +222 -0
- package/examples/output/java.async-profiler.nativemem.current.jfr.md +222 -0
- package/examples/output/java.async-profiler.nativemem.diff.jfr.md +65 -0
- package/examples/output/java.async-profiler.wall.base.jfr.md +400 -0
- package/examples/output/java.async-profiler.wall.current.jfr.md +420 -0
- package/examples/output/java.async-profiler.wall.diff.jfr.md +94 -0
- package/examples/output/java.jdk.all.base.jfr.md +1024 -0
- package/examples/output/java.jdk.all.current.jfr.md +1010 -0
- package/examples/output/java.jdk.all.diff.jfr.md +311 -0
- package/examples/output/java.jdk.alloc.base.jfr.md +1024 -0
- package/examples/output/java.jdk.alloc.current.jfr.md +1046 -0
- package/examples/output/java.jdk.alloc.diff.jfr.md +312 -0
- package/examples/output/java.jdk.cpu.base.jfr.md +1023 -0
- package/examples/output/java.jdk.cpu.current.jfr.md +1039 -0
- package/examples/output/java.jdk.cpu.diff.jfr.md +285 -0
- package/examples/output/java.jdk.live.base.jfr.md +1029 -0
- package/examples/output/java.jdk.live.current.jfr.md +1035 -0
- package/examples/output/java.jdk.live.diff.jfr.md +289 -0
- package/examples/output/java.jdk.lock.base.jfr.md +1040 -0
- package/examples/output/java.jdk.lock.current.jfr.md +1051 -0
- package/examples/output/java.jdk.lock.diff.jfr.md +339 -0
- package/examples/output/javascript.bun.base.cpuprofile.md +73 -0
- package/examples/output/javascript.bun.base.heapsnapshot.md +608 -0
- package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +480 -0
- package/examples/output/javascript.bun.current.cpuprofile.md +73 -0
- package/examples/output/javascript.bun.current.heapsnapshot.md +608 -0
- package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +480 -0
- package/examples/output/javascript.bun.diff.cpuprofile.md +54 -0
- package/examples/output/javascript.bun.diff.heapsnapshot.md +48 -0
- package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +62 -0
- package/examples/output/javascript.chrome.base.cpuprofile.md +163 -0
- package/examples/output/javascript.chrome.base.heapprofile.md +32 -0
- package/examples/output/javascript.chrome.base.heapsnapshot.md +649 -0
- package/examples/output/javascript.chrome.current.cpuprofile.md +149 -0
- package/examples/output/javascript.chrome.current.heapprofile.md +32 -0
- package/examples/output/javascript.chrome.current.heapsnapshot.md +647 -0
- package/examples/output/javascript.chrome.diff.cpuprofile.md +65 -0
- package/examples/output/javascript.chrome.diff.heapprofile.md +50 -0
- package/examples/output/javascript.chrome.diff.heapsnapshot.md +73 -0
- package/examples/output/javascript.deno.base.cpuprofile.md +122 -0
- package/examples/output/javascript.deno.current.cpuprofile.md +114 -0
- package/examples/output/javascript.deno.diff.cpuprofile.md +66 -0
- package/examples/output/javascript.node.base.cpuprofile.md +136 -0
- package/examples/output/javascript.node.base.heapprofile.md +56 -0
- package/examples/output/javascript.node.base.heapsnapshot.md +660 -0
- package/examples/output/javascript.node.current.cpuprofile.md +119 -0
- package/examples/output/javascript.node.current.heapprofile.md +52 -0
- package/examples/output/javascript.node.current.heapsnapshot.md +660 -0
- package/examples/output/javascript.node.diff.cpuprofile.md +70 -0
- package/examples/output/javascript.node.diff.heapprofile.md +34 -0
- package/examples/output/javascript.node.diff.heapsnapshot.md +39 -0
- package/examples/output/javascript.pprof.cpu.base.pprof.md +104 -0
- package/examples/output/javascript.pprof.cpu.current.pprof.md +120 -0
- package/examples/output/javascript.pprof.cpu.diff.pprof.md +63 -0
- package/examples/output/javascript.pprof.heap.base.pprof.md +86 -0
- package/examples/output/javascript.pprof.heap.current.pprof.md +57 -0
- package/examples/output/javascript.pprof.heap.diff.pprof.md +42 -0
- package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +388 -0
- package/examples/output/javascript.safari.current.webkit-timeline-recording.json.md +378 -0
- package/examples/output/javascript.safari.diff.webkit-timeline-recording.json.md +122 -0
- package/examples/output/julia.pprof-jl.alloc.base.pprof.md +124 -0
- package/examples/output/julia.pprof-jl.alloc.current.pprof.md +126 -0
- package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +30 -0
- package/examples/output/julia.pprof-jl.cpu.base.pprof.md +177 -0
- package/examples/output/julia.pprof-jl.cpu.current.pprof.md +179 -0
- package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +64 -0
- package/examples/output/kotlin.async-profiler.all.base.jfr.md +920 -0
- package/examples/output/kotlin.async-profiler.all.current.jfr.md +925 -0
- package/examples/output/kotlin.async-profiler.all.diff.jfr.md +247 -0
- package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +467 -0
- package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +473 -0
- package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +122 -0
- package/examples/output/kotlin.async-profiler.cpu.base.collapsed.md +371 -0
- package/examples/output/kotlin.async-profiler.cpu.base.jfr.md +472 -0
- package/examples/output/kotlin.async-profiler.cpu.current.collapsed.md +370 -0
- package/examples/output/kotlin.async-profiler.cpu.current.jfr.md +445 -0
- package/examples/output/kotlin.async-profiler.cpu.diff.collapsed.md +124 -0
- package/examples/output/kotlin.async-profiler.cpu.diff.jfr.md +125 -0
- package/examples/output/kotlin.async-profiler.live.base.jfr.md +934 -0
- package/examples/output/kotlin.async-profiler.live.current.jfr.md +917 -0
- package/examples/output/kotlin.async-profiler.live.diff.jfr.md +245 -0
- package/examples/output/kotlin.async-profiler.lock.base.jfr.md +1 -0
- package/examples/output/kotlin.async-profiler.lock.current.jfr.md +1 -0
- package/examples/output/kotlin.async-profiler.lock.diff.jfr.md +1 -0
- package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +234 -0
- package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +234 -0
- package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +65 -0
- package/examples/output/kotlin.async-profiler.wall.base.jfr.md +452 -0
- package/examples/output/kotlin.async-profiler.wall.current.jfr.md +457 -0
- package/examples/output/kotlin.async-profiler.wall.diff.jfr.md +125 -0
- package/examples/output/kotlin.jdk.all.base.jfr.md +1442 -0
- package/examples/output/kotlin.jdk.all.current.jfr.md +1343 -0
- package/examples/output/kotlin.jdk.all.diff.jfr.md +392 -0
- package/examples/output/kotlin.jdk.alloc.base.jfr.md +1418 -0
- package/examples/output/kotlin.jdk.alloc.current.jfr.md +1389 -0
- package/examples/output/kotlin.jdk.alloc.diff.jfr.md +383 -0
- package/examples/output/kotlin.jdk.cpu.base.jfr.md +1406 -0
- package/examples/output/kotlin.jdk.cpu.current.jfr.md +1374 -0
- package/examples/output/kotlin.jdk.cpu.diff.jfr.md +380 -0
- package/examples/output/kotlin.jdk.live.base.jfr.md +1378 -0
- package/examples/output/kotlin.jdk.live.current.jfr.md +1311 -0
- package/examples/output/kotlin.jdk.live.diff.jfr.md +381 -0
- package/examples/output/kotlin.jdk.lock.base.jfr.md +1427 -0
- package/examples/output/kotlin.jdk.lock.current.jfr.md +1374 -0
- package/examples/output/kotlin.jdk.lock.diff.jfr.md +386 -0
- package/examples/output/php.excimer.wall.base.speedscope.json.md +25 -0
- package/examples/output/php.excimer.wall.current.speedscope.json.md +25 -0
- package/examples/output/php.excimer.wall.diff.speedscope.json.md +29 -0
- package/examples/output/python.py-spy.cpu.base.collapsed.md +526 -0
- package/examples/output/python.py-spy.cpu.base.speedscope.json.md +37 -0
- package/examples/output/python.py-spy.cpu.current.collapsed.md +514 -0
- package/examples/output/python.py-spy.cpu.current.speedscope.json.md +37 -0
- package/examples/output/python.py-spy.cpu.diff.collapsed.md +122 -0
- package/examples/output/python.py-spy.cpu.diff.speedscope.json.md +31 -0
- package/examples/output/python.py-spy.wall.base.collapsed.md +527 -0
- package/examples/output/python.py-spy.wall.current.collapsed.md +518 -0
- package/examples/output/python.py-spy.wall.diff.collapsed.md +122 -0
- package/examples/output/ruby.rbspy.cpu.base.collapsed.md +90 -0
- package/examples/output/ruby.rbspy.cpu.base.pprof.md +105 -0
- package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +105 -0
- package/examples/output/ruby.rbspy.cpu.current.collapsed.md +90 -0
- package/examples/output/ruby.rbspy.cpu.current.pprof.md +115 -0
- package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +115 -0
- package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +32 -0
- package/examples/output/ruby.rbspy.cpu.diff.pprof.md +44 -0
- package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +44 -0
- package/examples/output/rust.pprof-rs.cpu.base.pprof.md +60 -0
- package/examples/output/rust.pprof-rs.cpu.current.pprof.md +60 -0
- package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +24 -0
- package/package.json +27 -20
- package/readme.md +201 -87
- package/examples/bun.cpuprofile.md +0 -475
- package/examples/deno.cpuprofile.md +0 -481
- package/examples/jsc-heap-snapshot.json.md +0 -509
- package/examples/node.cpuprofile.md +0 -485
- package/examples/node.heapprofile.md +0 -281
- package/examples/node.heapsnapshot.md +0 -694
- package/examples/node.pprof.md +0 -441
- package/examples/node.speedscope.json.md +0 -408
- package/examples/rust.pprof.md +0 -477
- package/examples/webkit-timeline-recording.json.md +0 -434
|
@@ -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,16 @@
|
|
|
1
|
+
# JFR
|
|
2
|
+
|
|
3
|
+
[JFR](https://openjdk.org/jeps/328) (Java Flight Recorder) is the JVM's native
|
|
4
|
+
binary profiling format, written by the JDK's built-in
|
|
5
|
+
[Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) and
|
|
6
|
+
[async-profiler](https://github.com/async-profiler/async-profiler).
|
|
7
|
+
|
|
8
|
+
A recording splits into self-contained chunks of LEB128 varint-encoded events.
|
|
9
|
+
One recording can mix event kinds, so it converts to one profile per kind:
|
|
10
|
+
CPU/wall sampling measured by sample count, heap and native memory allocation
|
|
11
|
+
sampling measured by allocated bytes, and lock contention measured by blocked
|
|
12
|
+
time.
|
|
13
|
+
|
|
14
|
+
It supports one metric per profile and multiple profiles per file.
|
|
15
|
+
|
|
16
|
+
Files use the `.jfr` extension.
|
|
@@ -9,5 +9,5 @@ Unlike heap profiles, which sample allocations, snapshots show what objects
|
|
|
9
9
|
currently exist in memory. This is useful for diagnosing memory leaks rather
|
|
10
10
|
than allocation hotspots.
|
|
11
11
|
|
|
12
|
-
Files use the `.json` extension and contain `"type": "Inspector"` and
|
|
13
|
-
`"version"
|
|
12
|
+
Files use the `.json` extension and contain `"type": "Inspector"` and a
|
|
13
|
+
`"version"` of `2` (Safari/JSC) or `3` (Bun's `generateHeapSnapshot("jsc")`).
|
package/docs/languages/c.md
CHANGED
|
@@ -9,8 +9,8 @@ Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
|
9
9
|
Link with `-lprofiler`:
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
|
-
gcc -O2 -lprofiler -o program program.c # C
|
|
13
|
-
g++ -O2 -lprofiler -o program program.cpp # C++
|
|
12
|
+
gcc -O2 -Wl,--no-as-needed -lprofiler -o program program.c # C
|
|
13
|
+
g++ -O2 -Wl,--no-as-needed -lprofiler -o program program.cpp # C++
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
### CLI
|
|
@@ -53,8 +53,8 @@ finding memory leaks and allocation hot spots.
|
|
|
53
53
|
Link with `-ltcmalloc`:
|
|
54
54
|
|
|
55
55
|
```sh
|
|
56
|
-
gcc -O2 -ltcmalloc -o program program.c # C
|
|
57
|
-
g++ -O2 -ltcmalloc -o program program.cpp # C++
|
|
56
|
+
gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
|
|
57
|
+
g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
|
|
58
58
|
```
|
|
59
59
|
|
|
60
60
|
### CLI
|
|
@@ -95,13 +95,13 @@ HeapProfilerStop();
|
|
|
95
95
|
## Heap checking
|
|
96
96
|
|
|
97
97
|
Compares the heap state before and after a region of code to detect memory
|
|
98
|
-
leaks. Useful for confirming
|
|
98
|
+
leaks. Useful for confirming a code path frees everything it allocates.
|
|
99
99
|
|
|
100
100
|
Link with `-ltcmalloc`:
|
|
101
101
|
|
|
102
102
|
```sh
|
|
103
|
-
gcc -O2 -ltcmalloc -o program program.c # C
|
|
104
|
-
g++ -O2 -ltcmalloc -o program program.cpp # C++
|
|
103
|
+
gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
|
|
104
|
+
g++ -O2 -Wl,--no-as-needed -ltcmalloc -o program program.cpp # C++
|
|
105
105
|
```
|
|
106
106
|
|
|
107
107
|
### CLI
|
|
@@ -134,3 +134,27 @@ HeapLeakChecker checker("my_check");
|
|
|
134
134
|
|
|
135
135
|
if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
|
|
136
136
|
```
|
|
137
|
+
|
|
138
|
+
## Tips
|
|
139
|
+
|
|
140
|
+
### Symbols
|
|
141
|
+
|
|
142
|
+
gperftools symbolizes addresses from the binary's and its shared libraries'
|
|
143
|
+
symbol tables, so build and link what you profile with symbols (`-g`, not
|
|
144
|
+
stripped). If the hot code lives in a stripped shared library, statically link
|
|
145
|
+
an unstripped build instead.
|
|
146
|
+
|
|
147
|
+
### Linking
|
|
148
|
+
|
|
149
|
+
Modern toolchains link with `--as-needed` by default, which drops
|
|
150
|
+
`-lprofiler`/`-ltcmalloc` when your program references no symbol from them,
|
|
151
|
+
exactly the case when you enable profiling through the environment variables
|
|
152
|
+
instead of the programmatic API. Force the link with `-Wl,--no-as-needed`, or
|
|
153
|
+
preload the library at runtime with `LD_PRELOAD`. The programmatic API
|
|
154
|
+
(`ProfilerStart`, etc.) references the symbols, so plain
|
|
155
|
+
`-lprofiler`/`-ltcmalloc` works there.
|
|
156
|
+
|
|
157
|
+
### Converting
|
|
158
|
+
|
|
159
|
+
`pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
|
|
160
|
+
`pprof`/`google-pprof` has no protobuf output.
|
|
@@ -0,0 +1,160 @@
|
|
|
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 -Wl,--no-as-needed -lprofiler -o program program.c # C
|
|
13
|
+
g++ -O2 -Wl,--no-as-needed -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 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
|
|
57
|
+
g++ -O2 -Wl,--no-as-needed -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 a code path frees everything it allocates.
|
|
99
|
+
|
|
100
|
+
Link with `-ltcmalloc`:
|
|
101
|
+
|
|
102
|
+
```sh
|
|
103
|
+
gcc -O2 -Wl,--no-as-needed -ltcmalloc -o program program.c # C
|
|
104
|
+
g++ -O2 -Wl,--no-as-needed -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
|
+
```
|
|
137
|
+
|
|
138
|
+
## Tips
|
|
139
|
+
|
|
140
|
+
### Symbols
|
|
141
|
+
|
|
142
|
+
gperftools symbolizes addresses from the binary's and its shared libraries'
|
|
143
|
+
symbol tables, so build and link what you profile with symbols (`-g`, not
|
|
144
|
+
stripped). If the hot code lives in a stripped shared library, statically link
|
|
145
|
+
an unstripped build instead.
|
|
146
|
+
|
|
147
|
+
### Linking
|
|
148
|
+
|
|
149
|
+
Modern toolchains link with `--as-needed` by default, which drops
|
|
150
|
+
`-lprofiler`/`-ltcmalloc` when your program references no symbol from them,
|
|
151
|
+
exactly the case when you enable profiling through the environment variables
|
|
152
|
+
instead of the programmatic API. Force the link with `-Wl,--no-as-needed`, or
|
|
153
|
+
preload the library at runtime with `LD_PRELOAD`. The programmatic API
|
|
154
|
+
(`ProfilerStart`, etc.) references the symbols, so plain
|
|
155
|
+
`-lprofiler`/`-ltcmalloc` works there.
|
|
156
|
+
|
|
157
|
+
### Converting
|
|
158
|
+
|
|
159
|
+
`pprof --proto` requires the Go `pprof`. gperftools's bundled Perl
|
|
160
|
+
`pprof`/`google-pprof` has no protobuf output.
|
|
@@ -0,0 +1,52 @@
|
|
|
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
|
+
The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
|
|
15
|
+
install a compatible version with `--version`.
|
|
16
|
+
|
|
17
|
+
## CPU profiling
|
|
18
|
+
|
|
19
|
+
Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
20
|
+
|
|
21
|
+
With no `--profile` or `--providers`, `dotnet-trace collect` enables the
|
|
22
|
+
`dotnet-common` and `dotnet-sampled-thread-time` profiles, sampling thread
|
|
23
|
+
stacks at roughly 100 Hz.
|
|
24
|
+
|
|
25
|
+
### CLI
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
# Attach to a running process, written directly as speedscope
|
|
29
|
+
dotnet-trace collect --process-id <pid> --format speedscope
|
|
30
|
+
|
|
31
|
+
# Launch and trace a command from startup (use `dotnet exec` so the dotnet CLI's
|
|
32
|
+
# own child processes aren't traced instead of your app)
|
|
33
|
+
dotnet-trace collect --format speedscope -- dotnet exec app.dll
|
|
34
|
+
|
|
35
|
+
# Attach for a fixed duration (dd:hh:mm:ss)
|
|
36
|
+
dotnet-trace collect --process-id <pid> --duration 00:00:00:30 --format speedscope
|
|
37
|
+
|
|
38
|
+
# Convert an existing .nettrace to speedscope
|
|
39
|
+
dotnet-trace convert trace.nettrace --format speedscope
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
#### Flags
|
|
43
|
+
|
|
44
|
+
| Flag | Default | Description |
|
|
45
|
+
| --------------------- | ---------- | --------------------------------------------------- |
|
|
46
|
+
| `-p` / `--process-id` | — | PID of the process to trace |
|
|
47
|
+
| `-n` / `--name` | — | Name of the process to trace |
|
|
48
|
+
| `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
|
|
49
|
+
| `-o` / `--output` | `nettrace` | Output file path |
|
|
50
|
+
| `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
|
|
51
|
+
| `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
|
|
52
|
+
| `--providers` | — | Comma-separated EventPipe providers to enable |
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Elixir/Erlang
|
|
2
|
+
|
|
3
|
+
Elixir and Erlang profiling uses
|
|
4
|
+
[eflambe](https://github.com/Stratus3D/eflambe), a BEAM profiler that wraps the
|
|
5
|
+
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` format is collapsed stacks. Add `eflambe` to
|
|
13
|
+
your dependencies, then profile a specific function.
|
|
14
|
+
|
|
15
|
+
**Keep the call small.** eflambe traces _every_ function call. It doesn't
|
|
16
|
+
sample, so output grows with the number of calls. A single invocation over a
|
|
17
|
+
large input can produce hundreds of MB.
|
|
18
|
+
|
|
19
|
+
### Elixir
|
|
20
|
+
|
|
21
|
+
```elixir
|
|
22
|
+
# Profile a function as it runs during normal execution (capture 1 call)
|
|
23
|
+
:eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
|
|
24
|
+
|
|
25
|
+
# Directly invoke and profile a function
|
|
26
|
+
:eflambe.apply({MyModule, :my_function, [arg1, arg2]}, output_format: :brendan_gregg)
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Erlang
|
|
30
|
+
|
|
31
|
+
```erlang
|
|
32
|
+
%% Profile a function as it runs during normal execution (capture 1 call)
|
|
33
|
+
eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
|
|
34
|
+
|
|
35
|
+
%% Directly invoke and profile a function
|
|
36
|
+
eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_gregg}]).
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Options
|
|
40
|
+
|
|
41
|
+
| Option | Default | Description |
|
|
42
|
+
| ------------------ | --------------- | --------------------------------------------------- |
|
|
43
|
+
| `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
|
|
44
|
+
| `output_directory` | project root | Directory to write the output file to |
|
|
45
|
+
| `open` | — | Auto-open the result in `speedscope` or `hotspot` |
|
|
46
|
+
| `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Elixir/Erlang
|
|
2
|
+
|
|
3
|
+
Elixir and Erlang profiling uses
|
|
4
|
+
[eflambe](https://github.com/Stratus3D/eflambe), a BEAM profiler that wraps the
|
|
5
|
+
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` format is collapsed stacks. Add `eflambe` to
|
|
13
|
+
your dependencies, then profile a specific function.
|
|
14
|
+
|
|
15
|
+
**Keep the call small.** eflambe traces _every_ function call. It doesn't
|
|
16
|
+
sample, so output grows with the number of calls. A single invocation over a
|
|
17
|
+
large input can produce hundreds of MB.
|
|
18
|
+
|
|
19
|
+
### Elixir
|
|
20
|
+
|
|
21
|
+
```elixir
|
|
22
|
+
# Profile a function as it runs during normal execution (capture 1 call)
|
|
23
|
+
:eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
|
|
24
|
+
|
|
25
|
+
# Directly invoke and profile a function
|
|
26
|
+
:eflambe.apply({MyModule, :my_function, [arg1, arg2]}, output_format: :brendan_gregg)
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Erlang
|
|
30
|
+
|
|
31
|
+
```erlang
|
|
32
|
+
%% Profile a function as it runs during normal execution (capture 1 call)
|
|
33
|
+
eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
|
|
34
|
+
|
|
35
|
+
%% Directly invoke and profile a function
|
|
36
|
+
eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_gregg}]).
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Options
|
|
40
|
+
|
|
41
|
+
| Option | Default | Description |
|
|
42
|
+
| ------------------ | --------------- | --------------------------------------------------- |
|
|
43
|
+
| `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
|
|
44
|
+
| `output_directory` | project root | Directory to write the output file to |
|
|
45
|
+
| `open` | — | Auto-open the result in `speedscope` or `hotspot` |
|
|
46
|
+
| `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
|
|
@@ -0,0 +1,52 @@
|
|
|
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
|
+
The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
|
|
15
|
+
install a compatible version with `--version`.
|
|
16
|
+
|
|
17
|
+
## CPU profiling
|
|
18
|
+
|
|
19
|
+
Periodically samples the call stack. Useful for finding CPU hot spots.
|
|
20
|
+
|
|
21
|
+
With no `--profile` or `--providers`, `dotnet-trace collect` enables the
|
|
22
|
+
`dotnet-common` and `dotnet-sampled-thread-time` profiles, sampling thread
|
|
23
|
+
stacks at roughly 100 Hz.
|
|
24
|
+
|
|
25
|
+
### CLI
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
# Attach to a running process, written directly as speedscope
|
|
29
|
+
dotnet-trace collect --process-id <pid> --format speedscope
|
|
30
|
+
|
|
31
|
+
# Launch and trace a command from startup (use `dotnet exec` so the dotnet CLI's
|
|
32
|
+
# own child processes aren't traced instead of your app)
|
|
33
|
+
dotnet-trace collect --format speedscope -- dotnet exec app.dll
|
|
34
|
+
|
|
35
|
+
# Attach for a fixed duration (dd:hh:mm:ss)
|
|
36
|
+
dotnet-trace collect --process-id <pid> --duration 00:00:00:30 --format speedscope
|
|
37
|
+
|
|
38
|
+
# Convert an existing .nettrace to speedscope
|
|
39
|
+
dotnet-trace convert trace.nettrace --format speedscope
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
#### Flags
|
|
43
|
+
|
|
44
|
+
| Flag | Default | Description |
|
|
45
|
+
| --------------------- | ---------- | --------------------------------------------------- |
|
|
46
|
+
| `-p` / `--process-id` | — | PID of the process to trace |
|
|
47
|
+
| `-n` / `--name` | — | Name of the process to trace |
|
|
48
|
+
| `--duration` | — | Duration to run, in `dd:hh:mm:ss` format |
|
|
49
|
+
| `-o` / `--output` | `nettrace` | Output file path |
|
|
50
|
+
| `--format` | `nettrace` | Output format: `nettrace`, `speedscope`, `chromium` |
|
|
51
|
+
| `--profile` | — | Preset provider configuration (e.g. `gc-verbose`) |
|
|
52
|
+
| `--providers` | — | Comma-separated EventPipe providers to enable |
|
package/docs/languages/go.md
CHANGED
|
@@ -40,8 +40,8 @@ defer pprof.StopCPUProfile()
|
|
|
40
40
|
|
|
41
41
|
Heap profiles come in two variants:
|
|
42
42
|
|
|
43
|
-
- **heap** (`inuse_space` / `inuse_objects`): live allocations at
|
|
44
|
-
|
|
43
|
+
- **heap** (`inuse_space` / `inuse_objects`): live allocations at each sample;
|
|
44
|
+
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
|
|
|
@@ -87,8 +87,8 @@ pprof.Lookup("allocs").WriteTo(f, 0)
|
|
|
87
87
|
|
|
88
88
|
## Goroutine profiling
|
|
89
89
|
|
|
90
|
-
Captures
|
|
91
|
-
|
|
90
|
+
Captures stack traces of all current goroutines. Useful for diagnosing goroutine
|
|
91
|
+
leaks or deadlocks.
|
|
92
92
|
|
|
93
93
|
### CLI
|
|
94
94
|
|
|
@@ -170,8 +170,8 @@ pprof.Lookup("mutex").WriteTo(f, 0)
|
|
|
170
170
|
|
|
171
171
|
## Thread creation profiling
|
|
172
172
|
|
|
173
|
-
Captures stack traces that
|
|
174
|
-
|
|
173
|
+
Captures stack traces that create new OS threads. Useful for diagnosing
|
|
174
|
+
unexpected thread proliferation.
|
|
175
175
|
|
|
176
176
|
### CLI
|
|
177
177
|
|
|
@@ -185,3 +185,8 @@ curl -o threadcreate.pprof 'http://localhost:6060/debug/pprof/threadcreate'
|
|
|
185
185
|
f, _ := os.Create("threadcreate.pprof")
|
|
186
186
|
pprof.Lookup("threadcreate").WriteTo(f, 0)
|
|
187
187
|
```
|
|
188
|
+
|
|
189
|
+
## Tips
|
|
190
|
+
|
|
191
|
+
Build with `-trimpath` (e.g. `go test -trimpath ...`) so locations are
|
|
192
|
+
package-relative (`encoding/json/encode.go`) instead of absolute build paths.
|