profiler-md 0.1.3 → 0.3.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.
@@ -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,12 @@
1
+ # pprof
2
+
3
+ [pprof](https://github.com/google/pprof) is a binary
4
+ ([protobuf](https://github.com/protocolbuffers/protobuf)) sampled-based
5
+ profiling format originally from Google. It is the de facto standard
6
+ cross-language profiling format.
7
+
8
+ It supports arbitrary metric units, multiple metrics in a single profile, and a
9
+ single profile per file. Locations support inlined call frames, meaning a single
10
+ instruction address can correspond to multiple logical stack frames.
11
+
12
+ Files are commonly gzip-compressed (extension `.pb.gz`).
@@ -0,0 +1,11 @@
1
+ # Speedscope
2
+
3
+ Speedscope is a JSON profiling format used by
4
+ [speedscope.app](https://www.speedscope.app), a flame graph visualizer. Each
5
+ profile within a file has a type: `sampled` (call stacks at points in time) or
6
+ `evented` (frame open/close timestamps).
7
+
8
+ It supports arbitrary metric units, a single metric per profile, and multiple
9
+ profiles in a single file.
10
+
11
+ Files use the `.speedscope.json` extension.
@@ -0,0 +1,13 @@
1
+ # V8 CPU profile
2
+
3
+ The V8 CPU profile is a JSON format produced by the
4
+ [V8 JavaScript engine's sampling profiler](https://v8.dev/docs/profile).
5
+
6
+ It stores both a call tree (nodes) and a sequence of timed samples. The call
7
+ tree enables accurate self-time attribution even from a sparse sample stream,
8
+ unlike formats that store only raw stacks.
9
+
10
+ It supports a single microsecond metric per profile and a single profile per
11
+ file.
12
+
13
+ Files use the `.cpuprofile` extension.
@@ -0,0 +1,13 @@
1
+ # V8 heap profile
2
+
3
+ The V8 heap profile is a JSON format produced by
4
+ [V8's sampling heap profiler](https://v8.dev/docs/profile). It is generated by
5
+ Node.js and Chrome DevTools.
6
+
7
+ Unlike heap snapshots, which capture all live objects at a point in time, heap
8
+ profiles sample allocations. This makes them useful for finding allocation
9
+ hotspots rather than diagnosing what is currently live in memory.
10
+
11
+ It supports a single byte metric per profile and a single profile per file.
12
+
13
+ Files use the `.heapprofile` extension.
@@ -0,0 +1,10 @@
1
+ # V8 heap snapshot
2
+
3
+ The V8 heap snapshot is a JSON format that captures the full live object graph
4
+ at a point in time.
5
+
6
+ Unlike heap profiles, which sample allocations, snapshots show what objects
7
+ currently exist in memory. This is useful for diagnosing memory leaks rather
8
+ than allocation hotspots.
9
+
10
+ Files use the `.heapsnapshot` extension.
@@ -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.
@@ -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,187 @@
1
+ # Go
2
+
3
+ Go supports pprof natively via the
4
+ [`runtime/pprof`](https://pkg.go.dev/runtime/pprof) package and the
5
+ [`net/http/pprof`](https://pkg.go.dev/net/http/pprof) HTTP handler.
6
+
7
+ ## CPU profiling
8
+
9
+ Periodically samples the call stack. Useful for finding CPU hot spots.
10
+
11
+ Samples at 100 Hz by default. Call `runtime.SetCPUProfileRate(hz)` before
12
+ starting a profile to change the rate.
13
+
14
+ ### CLI
15
+
16
+ ```sh
17
+ # Via HTTP endpoint (add `import _ "net/http/pprof"` to your program)
18
+ curl -o cpu.pprof 'http://localhost:6060/debug/pprof/profile?seconds=30'
19
+
20
+ # Via go test
21
+ go test -cpuprofile=cpu.pprof -bench=BenchmarkFoo ./...
22
+ ```
23
+
24
+ ### Programmatic API
25
+
26
+ ```go
27
+ import (
28
+ "os"
29
+ "runtime/pprof"
30
+ )
31
+
32
+ f, _ := os.Create("cpu.pprof")
33
+ pprof.StartCPUProfile(f)
34
+ defer pprof.StopCPUProfile()
35
+
36
+ // Code to profile...
37
+ ```
38
+
39
+ ## Memory profiling
40
+
41
+ Heap profiles come in two variants:
42
+
43
+ - **heap** (`inuse_space` / `inuse_objects`): live allocations at the time of
44
+ the time of each sample; useful for finding memory leaks
45
+ - **allocs** (`alloc_space` / `alloc_objects`): all allocations since program
46
+ start; useful for finding allocation hot spots
47
+
48
+ `runtime.MemProfileRate` controls sampling granularity (default: one sample per
49
+ 512 KB allocated). Set to `1` to capture every allocation (expensive):
50
+
51
+ ```go
52
+ runtime.MemProfileRate = 1
53
+ ```
54
+
55
+ ### CLI
56
+
57
+ ```sh
58
+ # Live heap (inuse)
59
+ curl -o heap.pprof 'http://localhost:6060/debug/pprof/heap'
60
+
61
+ # All allocations since start
62
+ curl -o allocs.pprof 'http://localhost:6060/debug/pprof/allocs'
63
+
64
+ # Via go test (uses alloc_space by default)
65
+ go test -memprofile=mem.pprof -bench=BenchmarkFoo ./...
66
+ ```
67
+
68
+ ### Programmatic API
69
+
70
+ ```go
71
+ import (
72
+ "os"
73
+ "runtime"
74
+ "runtime/pprof"
75
+ )
76
+
77
+ runtime.GC() // Flush pending samples before writing the profile
78
+
79
+ // Live heap
80
+ f, _ := os.Create("heap.pprof")
81
+ pprof.WriteHeapProfile(f)
82
+
83
+ // All allocations
84
+ f, _ := os.Create("allocs.pprof")
85
+ pprof.Lookup("allocs").WriteTo(f, 0)
86
+ ```
87
+
88
+ ## Goroutine profiling
89
+
90
+ Captures the stack traces of all current goroutines. Useful for diagnosing
91
+ goroutine leaks or deadlocks.
92
+
93
+ ### CLI
94
+
95
+ ```sh
96
+ # Full stack traces (debug=2 gives text output, debug=0 gives pprof binary)
97
+ curl -o goroutine.pprof 'http://localhost:6060/debug/pprof/goroutine'
98
+
99
+ # Human-readable text dump
100
+ curl 'http://localhost:6060/debug/pprof/goroutine?debug=2'
101
+ ```
102
+
103
+ ### Programmatic API
104
+
105
+ ```go
106
+ f, _ := os.Create("goroutine.pprof")
107
+ pprof.Lookup("goroutine").WriteTo(f, 0)
108
+ ```
109
+
110
+ ## Block profiling
111
+
112
+ Captures stack traces that led to blocking on synchronization primitives
113
+ (channel ops, `sync.Mutex`, `sync.RWMutex`, `sync.WaitGroup`, etc.). Useful for
114
+ diagnosing synchronization bottlenecks.
115
+
116
+ Disabled by default. Call `runtime.SetBlockProfileRate(rate)` in your program
117
+ before the code you want to profile. This applies whether you collect via HTTP
118
+ or the programmatic API. Rate is in nanoseconds: `1` captures every blocking
119
+ event; higher values sample less.
120
+
121
+ ```go
122
+ runtime.SetBlockProfileRate(1)
123
+ ```
124
+
125
+ ### CLI
126
+
127
+ ```sh
128
+ # Via HTTP endpoint
129
+ curl -o block.pprof 'http://localhost:6060/debug/pprof/block'
130
+
131
+ # Via go test
132
+ go test -blockprofile=block.pprof -bench=BenchmarkFoo ./...
133
+ ```
134
+
135
+ ### Programmatic API
136
+
137
+ ```go
138
+ f, _ := os.Create("block.pprof")
139
+ pprof.Lookup("block").WriteTo(f, 0)
140
+ ```
141
+
142
+ ## Mutex profiling
143
+
144
+ Captures stack traces of goroutines holding a contended mutex when another
145
+ goroutine tries to acquire it. Useful for finding lock contention hot spots.
146
+
147
+ Disabled by default. Call `runtime.SetMutexProfileFraction(rate)` in your
148
+ program before the code you want to profile. This applies whether you collect
149
+ via HTTP or the programmatic API. `1` captures every contended event; `n`
150
+ samples roughly `1/n` events.
151
+
152
+ ```go
153
+ runtime.SetMutexProfileFraction(1)
154
+ ```
155
+
156
+ ### CLI
157
+
158
+ ```sh
159
+ curl -o mutex.pprof 'http://localhost:6060/debug/pprof/mutex'
160
+
161
+ go test -mutexprofile=mutex.pprof -bench=BenchmarkFoo ./...
162
+ ```
163
+
164
+ ### Programmatic API
165
+
166
+ ```go
167
+ f, _ := os.Create("mutex.pprof")
168
+ pprof.Lookup("mutex").WriteTo(f, 0)
169
+ ```
170
+
171
+ ## Thread creation profiling
172
+
173
+ Captures stack traces that led to the creation of new OS threads. Useful for
174
+ diagnosing unexpected thread proliferation.
175
+
176
+ ### CLI
177
+
178
+ ```sh
179
+ curl -o threadcreate.pprof 'http://localhost:6060/debug/pprof/threadcreate'
180
+ ```
181
+
182
+ ### Programmatic API
183
+
184
+ ```go
185
+ f, _ := os.Create("threadcreate.pprof")
186
+ pprof.Lookup("threadcreate").WriteTo(f, 0)
187
+ ```
@@ -0,0 +1,117 @@
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 (pprof format)
15
+ asprof -d 30 -f cpu.pprof <pid>
16
+
17
+ # Attach to a running process (speedscope format)
18
+ asprof -d 30 -f profile.speedscope -o speedscope <pid>
19
+
20
+ # Profile a command directly
21
+ asprof -d 30 -f cpu.pprof -- java -jar app.jar
22
+ ```
23
+
24
+ ### Programmatic API
25
+
26
+ Add `async-profiler` to your dependencies, then:
27
+
28
+ ```java
29
+ import one.profiler.AsyncProfiler;
30
+
31
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
32
+ profiler.execute("start,event=cpu,file=cpu.jfr");
33
+
34
+ // Code to profile...
35
+
36
+ profiler.execute("stop");
37
+ ```
38
+
39
+ ## Wall-clock profiling
40
+
41
+ Samples wall-clock time rather than CPU time. Useful for I/O-bound or
42
+ latency-sensitive code where threads spend time waiting.
43
+
44
+ ### CLI
45
+
46
+ ```sh
47
+ asprof -d 30 -e wall -f profile.pprof <pid>
48
+ ```
49
+
50
+ ### Programmatic API
51
+
52
+ ```java
53
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
54
+ profiler.execute("start,event=wall,file=profile.jfr");
55
+
56
+ // Code to profile...
57
+
58
+ profiler.execute("stop");
59
+ ```
60
+
61
+ ## Memory profiling
62
+
63
+ Samples heap allocations. Useful for finding allocation hot spots and reducing
64
+ GC pressure.
65
+
66
+ ### CLI
67
+
68
+ ```sh
69
+ # Attach to a running process (pprof format)
70
+ asprof -d 30 -e alloc -f mem.pprof <pid>
71
+
72
+ # Profile a command directly
73
+ asprof -d 30 -e alloc -f mem.pprof -- java -jar app.jar
74
+ ```
75
+
76
+ ### Programmatic API
77
+
78
+ ```java
79
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
80
+ profiler.execute("start,event=alloc,file=mem.jfr");
81
+
82
+ // Code to profile...
83
+
84
+ profiler.execute("stop");
85
+ ```
86
+
87
+ ## Lock profiling
88
+
89
+ Samples contended monitor locks (`synchronized`, `ReentrantLock`, and other
90
+ `java.util.concurrent` locks). Useful for finding lock contention hot spots.
91
+
92
+ ### CLI
93
+
94
+ ```sh
95
+ asprof -d 30 -e lock -f lock.pprof <pid>
96
+ ```
97
+
98
+ ### Programmatic API
99
+
100
+ ```java
101
+ AsyncProfiler profiler = AsyncProfiler.getInstance();
102
+ profiler.execute("start,event=lock,file=lock.jfr");
103
+
104
+ // Code to profile...
105
+
106
+ profiler.execute("stop");
107
+ ```
108
+
109
+ ## CLI flags
110
+
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) |