profiler-md 0.5.0 → 0.6.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 (166) hide show
  1. package/dist/cli/index.mjs +5789 -5181
  2. package/dist/index.d.mts +478 -137
  3. package/dist/index.js +2 -2
  4. package/docs/formats/jfr.md +1 -1
  5. package/docs/formats/jsc-heap-snapshot.md +1 -1
  6. package/docs/formats/pprof.md +8 -6
  7. package/docs/formats/speedscope.md +5 -4
  8. package/docs/formats/systing.md +25 -0
  9. package/docs/formats/v8-heap-snapshot.md +2 -2
  10. package/docs/languages/c.md +35 -2
  11. package/docs/languages/csharp.md +2 -4
  12. package/docs/languages/elixir.md +4 -5
  13. package/docs/languages/go.md +6 -6
  14. package/docs/languages/java.md +13 -13
  15. package/docs/languages/javascript.md +7 -7
  16. package/docs/languages/julia.md +92 -13
  17. package/docs/languages/php.md +3 -4
  18. package/docs/languages/python.md +28 -13
  19. package/docs/languages/ruby.md +4 -6
  20. package/docs/languages/rust.md +37 -8
  21. package/examples/output/c.gperftools.heap.base.pprof.md +151 -151
  22. package/examples/output/c.gperftools.heap.current.pprof.md +151 -151
  23. package/examples/output/c.gperftools.heap.diff.pprof.md +3 -3
  24. package/examples/output/c.systing.cpu.base.systing.md +824 -0
  25. package/examples/output/c.systing.cpu.current.systing.md +825 -0
  26. package/examples/output/c.systing.cpu.diff.systing.md +238 -0
  27. package/examples/output/cpp.gperftools.heap.base.pprof.md +24 -24
  28. package/examples/output/cpp.gperftools.heap.current.pprof.md +24 -24
  29. package/examples/output/cpp.gperftools.heap.diff.pprof.md +2 -2
  30. package/examples/output/go.pprof.block.base.pprof.md +40 -40
  31. package/examples/output/go.pprof.block.current.pprof.md +37 -37
  32. package/examples/output/go.pprof.block.diff.pprof.md +14 -14
  33. package/examples/output/go.pprof.goroutine.base.pprof.md +16 -16
  34. package/examples/output/go.pprof.goroutine.current.pprof.md +16 -16
  35. package/examples/output/go.pprof.heap-alloc.base.pprof.md +79 -79
  36. package/examples/output/go.pprof.heap-alloc.current.pprof.md +72 -72
  37. package/examples/output/go.pprof.heap-alloc.diff.pprof.md +25 -25
  38. package/examples/output/go.pprof.heap.base.pprof.md +79 -79
  39. package/examples/output/go.pprof.heap.current.pprof.md +72 -72
  40. package/examples/output/go.pprof.heap.diff.pprof.md +25 -25
  41. package/examples/output/go.pprof.mutex.base.pprof.md +26 -26
  42. package/examples/output/go.pprof.mutex.current.pprof.md +15 -15
  43. package/examples/output/go.pprof.mutex.diff.pprof.md +10 -10
  44. package/examples/output/java.async-profiler.all.base.jfr.md +192 -192
  45. package/examples/output/java.async-profiler.all.current.jfr.md +181 -181
  46. package/examples/output/java.async-profiler.all.diff.jfr.md +72 -72
  47. package/examples/output/java.async-profiler.alloc.base.jfr.md +189 -189
  48. package/examples/output/java.async-profiler.alloc.current.jfr.md +183 -183
  49. package/examples/output/java.async-profiler.alloc.diff.jfr.md +70 -70
  50. package/examples/output/java.async-profiler.live.base.jfr.md +303 -303
  51. package/examples/output/java.async-profiler.live.current.jfr.md +313 -313
  52. package/examples/output/java.async-profiler.live.diff.jfr.md +132 -132
  53. package/examples/output/java.async-profiler.nativemem.base.jfr.md +141 -141
  54. package/examples/output/java.async-profiler.nativemem.current.jfr.md +141 -141
  55. package/examples/output/java.async-profiler.nativemem.diff.jfr.md +48 -48
  56. package/examples/output/java.jdk.all.base.jfr.md +281 -281
  57. package/examples/output/java.jdk.all.current.jfr.md +267 -267
  58. package/examples/output/java.jdk.all.diff.jfr.md +103 -103
  59. package/examples/output/java.jdk.alloc.base.jfr.md +254 -254
  60. package/examples/output/java.jdk.alloc.current.jfr.md +293 -293
  61. package/examples/output/java.jdk.alloc.diff.jfr.md +102 -102
  62. package/examples/output/java.jdk.cpu.base.jfr.md +256 -256
  63. package/examples/output/java.jdk.cpu.current.jfr.md +276 -276
  64. package/examples/output/java.jdk.cpu.diff.jfr.md +93 -93
  65. package/examples/output/java.jdk.live.base.jfr.md +256 -256
  66. package/examples/output/java.jdk.live.current.jfr.md +250 -250
  67. package/examples/output/java.jdk.live.diff.jfr.md +78 -78
  68. package/examples/output/java.jdk.lock.base.jfr.md +285 -285
  69. package/examples/output/java.jdk.lock.current.jfr.md +285 -285
  70. package/examples/output/java.jdk.lock.diff.jfr.md +121 -121
  71. package/examples/output/javascript.bun.base.cpuprofile.md +36 -36
  72. package/examples/output/javascript.bun.base.heapsnapshot.md +215 -215
  73. package/examples/output/javascript.bun.base.jsc-heap-snapshot.json.md +218 -218
  74. package/examples/output/javascript.bun.current.cpuprofile.md +34 -34
  75. package/examples/output/javascript.bun.current.heapsnapshot.md +215 -215
  76. package/examples/output/javascript.bun.current.jsc-heap-snapshot.json.md +220 -220
  77. package/examples/output/javascript.bun.diff.cpuprofile.md +19 -19
  78. package/examples/output/javascript.bun.diff.heapsnapshot.md +23 -23
  79. package/examples/output/javascript.bun.diff.jsc-heap-snapshot.json.md +35 -35
  80. package/examples/output/javascript.chrome.base.heapprofile.md +17 -17
  81. package/examples/output/javascript.chrome.base.heapsnapshot.md +202 -202
  82. package/examples/output/javascript.chrome.current.heapprofile.md +17 -17
  83. package/examples/output/javascript.chrome.current.heapsnapshot.md +200 -200
  84. package/examples/output/javascript.chrome.diff.heapprofile.md +21 -21
  85. package/examples/output/javascript.chrome.diff.heapsnapshot.md +27 -27
  86. package/examples/output/javascript.deno.base.cpuprofile.md +63 -63
  87. package/examples/output/javascript.deno.current.cpuprofile.md +56 -56
  88. package/examples/output/javascript.deno.diff.cpuprofile.md +28 -28
  89. package/examples/output/javascript.node.base.cpuprofile.md +73 -73
  90. package/examples/output/javascript.node.base.heapprofile.md +32 -32
  91. package/examples/output/javascript.node.base.heapsnapshot.md +269 -269
  92. package/examples/output/javascript.node.current.cpuprofile.md +61 -61
  93. package/examples/output/javascript.node.current.heapprofile.md +28 -28
  94. package/examples/output/javascript.node.current.heapsnapshot.md +269 -269
  95. package/examples/output/javascript.node.diff.cpuprofile.md +32 -32
  96. package/examples/output/javascript.node.diff.heapprofile.md +17 -17
  97. package/examples/output/javascript.node.diff.heapsnapshot.md +19 -19
  98. package/examples/output/javascript.pprof.cpu.base.pprof.md +50 -50
  99. package/examples/output/javascript.pprof.cpu.current.pprof.md +66 -66
  100. package/examples/output/javascript.pprof.cpu.diff.pprof.md +28 -28
  101. package/examples/output/javascript.pprof.heap.base.pprof.md +46 -46
  102. package/examples/output/javascript.pprof.heap.current.pprof.md +34 -34
  103. package/examples/output/javascript.pprof.heap.diff.pprof.md +18 -18
  104. package/examples/output/javascript.safari.base.webkit-timeline-recording.json.md +1 -1
  105. package/examples/output/julia.pprof-jl.alloc.base.pprof.md +83 -83
  106. package/examples/output/julia.pprof-jl.alloc.current.pprof.md +85 -85
  107. package/examples/output/julia.pprof-jl.alloc.diff.pprof.md +18 -18
  108. package/examples/output/julia.pprof-jl.cpu.base.pprof.md +107 -107
  109. package/examples/output/julia.pprof-jl.cpu.current.pprof.md +109 -109
  110. package/examples/output/julia.pprof-jl.cpu.diff.pprof.md +29 -29
  111. package/examples/output/julia.pprof-jl.wall.base.pprof.md +181 -0
  112. package/examples/output/julia.pprof-jl.wall.current.pprof.md +193 -0
  113. package/examples/output/julia.pprof-jl.wall.diff.pprof.md +64 -0
  114. package/examples/output/julia.profile.base.heapsnapshot.md +590 -0
  115. package/examples/output/julia.profile.current.heapsnapshot.md +590 -0
  116. package/examples/output/julia.profile.diff.heapsnapshot.md +288 -0
  117. package/examples/output/kotlin.async-profiler.all.base.jfr.md +193 -193
  118. package/examples/output/kotlin.async-profiler.all.current.jfr.md +218 -218
  119. package/examples/output/kotlin.async-profiler.all.diff.jfr.md +93 -93
  120. package/examples/output/kotlin.async-profiler.alloc.base.jfr.md +212 -212
  121. package/examples/output/kotlin.async-profiler.alloc.current.jfr.md +183 -183
  122. package/examples/output/kotlin.async-profiler.alloc.diff.jfr.md +93 -93
  123. package/examples/output/kotlin.async-profiler.live.base.jfr.md +343 -343
  124. package/examples/output/kotlin.async-profiler.live.current.jfr.md +336 -336
  125. package/examples/output/kotlin.async-profiler.live.diff.jfr.md +186 -186
  126. package/examples/output/kotlin.async-profiler.nativemem.base.jfr.md +150 -150
  127. package/examples/output/kotlin.async-profiler.nativemem.current.jfr.md +150 -150
  128. package/examples/output/kotlin.async-profiler.nativemem.diff.jfr.md +48 -48
  129. package/examples/output/kotlin.jdk.all.base.jfr.md +402 -402
  130. package/examples/output/kotlin.jdk.all.current.jfr.md +413 -413
  131. package/examples/output/kotlin.jdk.all.diff.jfr.md +169 -169
  132. package/examples/output/kotlin.jdk.alloc.base.jfr.md +418 -418
  133. package/examples/output/kotlin.jdk.alloc.current.jfr.md +405 -405
  134. package/examples/output/kotlin.jdk.alloc.diff.jfr.md +160 -160
  135. package/examples/output/kotlin.jdk.cpu.base.jfr.md +418 -418
  136. package/examples/output/kotlin.jdk.cpu.current.jfr.md +413 -413
  137. package/examples/output/kotlin.jdk.cpu.diff.jfr.md +148 -148
  138. package/examples/output/kotlin.jdk.live.base.jfr.md +420 -420
  139. package/examples/output/kotlin.jdk.live.current.jfr.md +411 -411
  140. package/examples/output/kotlin.jdk.live.diff.jfr.md +148 -148
  141. package/examples/output/kotlin.jdk.lock.base.jfr.md +417 -417
  142. package/examples/output/kotlin.jdk.lock.current.jfr.md +398 -398
  143. package/examples/output/kotlin.jdk.lock.diff.jfr.md +156 -156
  144. package/examples/output/php.excimer.wall.base.speedscope.json.md +6 -6
  145. package/examples/output/php.excimer.wall.current.speedscope.json.md +6 -6
  146. package/examples/output/php.excimer.wall.diff.speedscope.json.md +6 -6
  147. package/examples/output/ruby.rbspy.cpu.base.collapsed.md +14 -14
  148. package/examples/output/ruby.rbspy.cpu.base.pprof.md +14 -14
  149. package/examples/output/ruby.rbspy.cpu.base.speedscope.json.md +14 -14
  150. package/examples/output/ruby.rbspy.cpu.current.collapsed.md +12 -12
  151. package/examples/output/ruby.rbspy.cpu.current.pprof.md +21 -21
  152. package/examples/output/ruby.rbspy.cpu.current.speedscope.json.md +21 -21
  153. package/examples/output/ruby.rbspy.cpu.diff.collapsed.md +5 -5
  154. package/examples/output/ruby.rbspy.cpu.diff.pprof.md +12 -12
  155. package/examples/output/ruby.rbspy.cpu.diff.speedscope.json.md +12 -12
  156. package/examples/output/rust.pprof-rs.cpu.base.pprof.md +32 -32
  157. package/examples/output/rust.pprof-rs.cpu.current.pprof.md +32 -32
  158. package/examples/output/rust.pprof-rs.cpu.diff.pprof.md +7 -7
  159. package/package.json +11 -10
  160. package/readme.md +53 -31
  161. package/skills/profile-optimize/SKILL.md +160 -0
  162. package/docs/languages/cpp.md +0 -160
  163. package/docs/languages/erlang.md +0 -46
  164. package/docs/languages/fsharp.md +0 -52
  165. package/docs/languages/kotlin.md +0 -170
  166. package/docs/languages/typescript.md +0 -276
@@ -11,6 +11,6 @@ CPU/wall sampling measured by sample count, heap and native memory allocation
11
11
  sampling measured by allocated bytes, and lock contention measured by blocked
12
12
  time.
13
13
 
14
- It supports one metric per profile and multiple profiles per file.
14
+ It supports a single metric per profile and multiple profiles per file.
15
15
 
16
16
  Files use the `.jfr` extension.
@@ -2,7 +2,7 @@
2
2
 
3
3
  The
4
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
5
+ is a JSON format produced by JavaScriptCore, the JavaScript engine of Safari and
6
6
  WebKit, that captures the full live object graph at a point in time.
7
7
 
8
8
  Unlike heap profiles, which sample allocations, snapshots show what objects
@@ -1,12 +1,14 @@
1
1
  # pprof
2
2
 
3
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.
4
+ ([protobuf](https://github.com/protocolbuffers/protobuf)) sample-based profiling
5
+ format originally from Google. It is the de facto standard cross-language
6
+ profiling format.
7
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.
8
+ Locations support inlined call frames, meaning a single instruction address can
9
+ correspond to multiple logical stack frames.
10
+
11
+ It supports arbitrary metric units, multiple metrics per profile, and a single
12
+ profile per file.
11
13
 
12
14
  Files are commonly gzip-compressed (extension `.pb.gz`).
@@ -1,11 +1,12 @@
1
1
  # Speedscope
2
2
 
3
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).
4
+ [speedscope.app](https://www.speedscope.app), a flame graph visualizer.
5
+
6
+ Each profile within a file has a type: `sampled` (call stacks at points in time)
7
+ or `evented` (frame open/close timestamps).
7
8
 
8
9
  It supports arbitrary metric units, a single metric per profile, and multiple
9
- profiles in a single file.
10
+ profiles per file.
10
11
 
11
12
  Files use the `.speedscope.json` extension.
@@ -0,0 +1,25 @@
1
+ # systing profile export
2
+
3
+ The line-oriented profile export written by
4
+ [systing](https://github.com/josefbacik/systing), a Linux eBPF system profiler:
5
+ a JSON header line describing the recording (sampling event and period,
6
+ event-type legend, system info), then one JSON array per record: interned
7
+ frames, interned leaf-first stacks, and per-thread sample counts. systing's
8
+ [`docs/PROFILE_EXPORT_FORMAT.md`](https://github.com/josefbacik/systing/blob/main/docs/PROFILE_EXPORT_FORMAT.md)
9
+ specifies the format.
10
+
11
+ A recording samples on-CPU execution and takes a stack each time a thread
12
+ sleeps, so it converts to up to three profiles: CPU (measured in time for
13
+ `cpu-clock` sampling, cycles for `cpu-cycles`), uninterruptible sleep, and
14
+ interruptible sleep (both measured in sleep occurrences). Stacks mix kernel,
15
+ native user, and Python frames; systing's frame markers (`[kernel]`,
16
+ `[gvisor:*]`, `[jit:*]` label modules) determine categorization. Sleep stacks
17
+ are taken at the context switch, so they always end in the kernel's scheduler
18
+ internals: self costs accumulate on scheduler frames, and the total costs show
19
+ which callers slept.
20
+
21
+ Produce it with `systing --output profile.systing -- <command>`, or from an
22
+ existing trace database with
23
+ `systing-util convert trace.duckdb --output profile.systing`.
24
+
25
+ Files use the `.systing` extension, optionally gzipped as `.systing.gz`.
@@ -1,7 +1,7 @@
1
1
  # V8 heap snapshot
2
2
 
3
- The V8 heap snapshot is a JSON format that captures the full live object graph
4
- at a point in time.
3
+ The V8 heap snapshot is a JSON format produced by the V8 JavaScript engine's
4
+ heap profiler that captures the full live object graph at a point in time.
5
5
 
6
6
  Unlike heap profiles, which sample allocations, snapshots show what objects
7
7
  currently exist in memory. This is useful for diagnosing memory leaks rather
@@ -1,6 +1,7 @@
1
1
  # C/C++
2
2
 
3
- C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools).
3
+ C and C++ profiling uses [gperftools](https://github.com/gperftools/gperftools),
4
+ or [systing](https://github.com/josefbacik/systing).
4
5
 
5
6
  ## CPU profiling
6
7
 
@@ -132,9 +133,41 @@ HeapLeakChecker checker("my_check");
132
133
 
133
134
  // Code to check...
134
135
 
135
- if (!checker.NoLeaks()) abort(); // fails if any net allocations were not freed
136
+ if (!checker.NoLeaks()) abort(); // fails if any net allocation leaked
136
137
  ```
137
138
 
139
+ ## System profiling
140
+
141
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler that
142
+ samples on-CPU stacks and records a stack each time a thread sleeps, across user
143
+ and kernel code. It needs root (BPF) and a kernel with BTF
144
+ (`/sys/kernel/btf/vmlinux`).
145
+
146
+ ```sh
147
+ # Record a command (and its children) for 30 seconds
148
+ sudo systing --duration 30 --output profile.systing -- ./program args
149
+
150
+ # Or attach to a running process
151
+ sudo systing --duration 30 --output profile.systing --pid <pid>
152
+ ```
153
+
154
+ Build what you profile with frame pointers so systing's unwinder can walk the
155
+ stack, and with symbols for readable frames:
156
+
157
+ ```sh
158
+ gcc -O2 -g -fno-omit-frame-pointer -o program program.c
159
+ ```
160
+
161
+ ### CLI flags
162
+
163
+ | Flag | Default | Description |
164
+ | --------------------------------- | ---------- | ------------------------------------------------------------------ |
165
+ | `--duration` | — | Recording duration in seconds |
166
+ | `--output` | `trace.pb` | Output path; `.systing` selects the profile export this tool reads |
167
+ | `--sample-freq` | `1000` | CPU stack-sampling rate in Hz |
168
+ | `--no-sleep-stack-traces` | off | Skip uninterruptible-sleep stacks |
169
+ | `--no-interruptible-stack-traces` | off | Skip interruptible-sleep stacks |
170
+
138
171
  ## Tips
139
172
 
140
173
  ### Symbols
@@ -1,9 +1,7 @@
1
1
  # C#/F#
2
2
 
3
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.
4
+ [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace).
7
5
 
8
6
  Install it as a global tool:
9
7
 
@@ -11,7 +9,7 @@ Install it as a global tool:
11
9
  dotnet tool install --global dotnet-trace
12
10
  ```
13
11
 
14
- The latest `dotnet-trace` needs a matching .NET runtime. If yours is older, then
12
+ The latest `dotnet-trace` needs a matching .NET runtime. If yours is older,
15
13
  install a compatible version with `--version`.
16
14
 
17
15
  ## CPU profiling
@@ -1,8 +1,7 @@
1
1
  # Elixir/Erlang
2
2
 
3
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.
4
+ [eflambe](https://github.com/Stratus3D/eflambe).
6
5
 
7
6
  ## CPU profiling
8
7
 
@@ -19,7 +18,7 @@ large input can produce hundreds of MB.
19
18
  ### Elixir
20
19
 
21
20
  ```elixir
22
- # Profile a function as it runs during normal execution (capture 1 call)
21
+ # Profile a function during normal execution (capture 1 call)
23
22
  :eflambe.capture({MyModule, :my_function, 1}, 1, output_format: :brendan_gregg)
24
23
 
25
24
  # Directly invoke and profile a function
@@ -29,7 +28,7 @@ large input can produce hundreds of MB.
29
28
  ### Erlang
30
29
 
31
30
  ```erlang
32
- %% Profile a function as it runs during normal execution (capture 1 call)
31
+ %% Profile a function during normal execution (capture 1 call)
33
32
  eflambe:capture({my_module, my_function, 1}, 1, [{output_format, brendan_gregg}]).
34
33
 
35
34
  %% Directly invoke and profile a function
@@ -41,6 +40,6 @@ eflambe:apply({my_module, my_function, [Arg1, Arg2]}, [{output_format, brendan_g
41
40
  | Option | Default | Description |
42
41
  | ------------------ | --------------- | --------------------------------------------------- |
43
42
  | `output_format` | `brendan_gregg` | Output format: `brendan_gregg` (collapsed) or `svg` |
44
- | `output_directory` | project root | Directory to write the output file to |
43
+ | `output_directory` | project root | Directory for the output file |
45
44
  | `open` | — | Auto-open the result in `speedscope` or `hotspot` |
46
45
  | `return` | `filename` | Return value: `value`, `flamegraph`, or `filename` |
@@ -114,9 +114,9 @@ Captures stack traces that led to blocking on synchronization primitives
114
114
  diagnosing synchronization bottlenecks.
115
115
 
116
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.
117
+ before the code to profile. This applies whether you collect via HTTP or the
118
+ programmatic API. Rate is in nanoseconds: `1` captures every blocking event;
119
+ higher values sample less.
120
120
 
121
121
  ```go
122
122
  runtime.SetBlockProfileRate(1)
@@ -145,9 +145,9 @@ Captures stack traces of goroutines holding a contended mutex when another
145
145
  goroutine tries to acquire it. Useful for finding lock contention hot spots.
146
146
 
147
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.
148
+ program before the code to profile. This applies whether you collect via HTTP or
149
+ the programmatic API. `1` captures every contended event; `n` samples roughly
150
+ `1/n` events.
151
151
 
152
152
  ```go
153
153
  runtime.SetMutexProfileFraction(1)
@@ -1,21 +1,21 @@
1
1
  # Java/Kotlin
2
2
 
3
- Java and Kotlin profiling works with any JVM language, using either
3
+ Java and Kotlin profiling works with any JVM language, using
4
4
  [Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfapi/) (JFR),
5
5
  built into the JDK since JDK 11, or
6
- [async-profiler](https://github.com/async-profiler/async-profiler), a low
7
- overhead sampling profiler that additionally resolves native frames and works on
8
- older JDKs.
6
+ [async-profiler](https://github.com/async-profiler/async-profiler), which also
7
+ resolves native frames and works on older JDKs.
9
8
 
10
9
  ## CPU profiling
11
10
 
12
11
  Periodically samples the call stack while on CPU. Useful for finding CPU hot
13
- spots. Recorded as `jdk.ExecutionSample` events.
12
+ spots. Recorded as `jdk.ExecutionSample` events, plus `jdk.NativeMethodSample`
13
+ events for threads running native methods.
14
14
 
15
15
  ### Java Flight Recorder
16
16
 
17
17
  ```sh
18
- java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms -jar app.jar
18
+ java -XX:StartFlightRecording=filename=cpu.jfr,settings=none,+jdk.ExecutionSample#enabled=true,+jdk.ExecutionSample#period=10ms,+jdk.NativeMethodSample#enabled=true,+jdk.NativeMethodSample#period=10ms -jar app.jar
19
19
  jfr summary cpu.jfr
20
20
  ```
21
21
 
@@ -56,8 +56,8 @@ waiting. Useful for I/O-bound or latency-sensitive code.
56
56
  ### Java Flight Recorder
57
57
 
58
58
  JFR has no wall-clock sampler, so this metric is async-profiler only. (JFR does
59
- record specific waiting events, such as `jdk.ThreadPark` and
60
- `jdk.JavaMonitorWait`, via the lock recipe below.)
59
+ record specific waiting events, such as `jdk.ThreadPark`, via the lock recipe
60
+ below.)
61
61
 
62
62
  ### async-profiler
63
63
 
@@ -136,8 +136,8 @@ Recorded as `profiler.NativeLock` events.
136
136
  ### Java Flight Recorder
137
137
 
138
138
  The `profile` template records execution samples, allocations, locks, GC, and
139
- many other JVM events at once. JFR rotates the recording into multiple chunks as
140
- it grows (`-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold).
139
+ many other JVM events at once. JFR rotates the recording into chunks as it grows
140
+ (`-XX:FlightRecorderOptions=maxchunksize=…` controls the threshold).
141
141
 
142
142
  ```sh
143
143
  java -XX:StartFlightRecording=filename=all.jfr,settings=profile -jar app.jar
@@ -146,9 +146,9 @@ jfr summary all.jfr
146
146
 
147
147
  ### async-profiler
148
148
 
149
- `--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock`
150
- simultaneously. Add `--nofree` to suppress the high-volume native `free` events,
151
- which otherwise dominate the recording.
149
+ `--all` enables `cpu`, `wall`, `alloc`, `live`, `nativemem`, and `lock` at once.
150
+ Add `--nofree` to suppress the high-volume native `free` events, which otherwise
151
+ dominate the recording.
152
152
 
153
153
  ```sh
154
154
  asprof --all --nofree -d 30 -f all.jfr <pid>
@@ -26,12 +26,12 @@ bun --cpu-prof script.ts
26
26
  | -------------------------- | ---------------------------------- | --------------------------------------------- |
27
27
  | `--cpu-prof` | — | Write a CPU profile on exit; enabled when set |
28
28
  | `--cpu-prof-interval=<µs>` | `1000` | Sampling interval in microseconds |
29
- | `--cpu-prof-dir=<dir>` | `.` | Directory to write the profile to |
29
+ | `--cpu-prof-dir=<dir>` | `.` | Directory for the profile |
30
30
  | `--cpu-prof-name=<name>` | `CPU.<timestamp>.<pid>.cpuprofile` | Filename for the profile |
31
31
 
32
32
  ### Programmatic API
33
33
 
34
- Profile a specific section of code rather than the whole process:
34
+ Profile a section of code rather than the whole process:
35
35
 
36
36
  ```js
37
37
  import { writeFileSync } from 'node:fs'
@@ -70,7 +70,7 @@ node --heap-prof script.js
70
70
  | ------------------------------ | -------- | ---------------------------------------------- |
71
71
  | `--heap-prof` | — | Write a heap profile on exit; enabled when set |
72
72
  | `--heap-prof-interval=<bytes>` | `524288` | Sampling interval in bytes (default 512 KB) |
73
- | `--heap-prof-dir=<dir>` | `.` | Directory to write the profile to |
73
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the profile |
74
74
  | `--heap-prof-name=<name>` | — | Filename for the profile |
75
75
 
76
76
  ### Programmatic API
@@ -122,7 +122,7 @@ bun --heap-prof script.ts
122
122
  | Flag | Default | Description |
123
123
  | ------------------------- | ------- | ----------------------------------------------- |
124
124
  | `--heap-prof` | — | Write a heap snapshot on exit; enabled when set |
125
- | `--heap-prof-dir=<dir>` | `.` | Directory to write the snapshot to |
125
+ | `--heap-prof-dir=<dir>` | `.` | Directory for the snapshot |
126
126
  | `--heap-prof-name=<name>` | — | Filename for the snapshot |
127
127
 
128
128
  ### Programmatic API
@@ -254,10 +254,10 @@ Open the Web Inspector with **Develop → Show Web Inspector** (or ⌥⌘I).
254
254
  ### Recording
255
255
 
256
256
  1. Click the **Timelines** tab.
257
- 2. Enable the instruments you want: **JavaScript & Events** (always), and
258
- optionally **Memory** and **JavaScript Allocations**.
257
+ 2. Enable the instruments: **JavaScript & Events** (always), and optionally
258
+ **Memory** and **JavaScript Allocations**.
259
259
  3. Click **Start Recording** (or ⌘R).
260
- 4. Reproduce the scenario you want to profile.
260
+ 4. Reproduce the scenario to profile.
261
261
  5. Click **Stop Recording**.
262
262
  6. Click the **Export** button (arrow icon) and save as a `.json` file.
263
263
 
@@ -3,16 +3,17 @@
3
3
  Julia profiling uses [PProf.jl](https://github.com/JuliaPerf/PProf.jl), which
4
4
  exports profiles collected by Julia's built-in
5
5
  [`Profile`](https://docs.julialang.org/en/v1/manual/profile/) standard library
6
- to the pprof format.
6
+ to the pprof format. `Profile` can also write V8 heap snapshots directly.
7
7
 
8
8
  ## CPU profiling
9
9
 
10
- Periodically samples the call stack. Useful for finding CPU hot spots.
10
+ Periodically samples the call stacks of running tasks. Useful for finding CPU
11
+ hot spots.
11
12
 
12
13
  ```julia
13
14
  using Profile, PProf
14
15
 
15
- # Warm up the JIT so compilation isn't captured as part of the profile.
16
+ # Warm up the JIT so the profile excludes compilation.
16
17
  my_function()
17
18
 
18
19
  Profile.clear()
@@ -23,32 +24,110 @@ Profile.clear()
23
24
  pprof(out = "cpu.pb.gz", web = false, from_c = false)
24
25
  ```
25
26
 
27
+ ### Sampling settings
28
+
29
+ Samples every 1 ms by default (10 ms on Windows). Configure with `Profile.init`
30
+ before profiling; calling it with no arguments returns the current settings.
31
+
32
+ ```julia
33
+ Profile.init(n = 10^7, delay = 0.0005)
34
+ ```
35
+
36
+ | Option | Default | Description |
37
+ | ------- | ------- | --------------------------------------------------- |
38
+ | `n` | `10^6` | Buffer capacity in instruction pointers, per thread |
39
+ | `delay` | `0.001` | Seconds between samples |
40
+
41
+ If profiling warns that the buffer filled up, increase `n` or `delay` and
42
+ re-run.
43
+
44
+ ## Wall-time profiling
45
+
46
+ Periodically samples all live tasks regardless of scheduling state (Julia ≥
47
+ 1.12). Unlike CPU profiling, it samples blocked tasks too, counting time spent
48
+ waiting on IO, locks, channels, and the scheduler. Useful for I/O-bound or
49
+ latency-sensitive code.
50
+
51
+ ```julia
52
+ using Profile, PProf
53
+
54
+ # Warm up the JIT so the profile excludes compilation.
55
+ my_function()
56
+
57
+ Profile.clear()
58
+ Profile.@profile_walltime my_function()
59
+
60
+ # Wall-time samples land in the same buffer as `@profile`, so the same call
61
+ # exports them. Always `Profile.clear()` between runs so CPU and wall-time
62
+ # samples don't mix.
63
+ pprof(out = "wall.pb.gz", web = false, from_c = false)
64
+ ```
65
+
66
+ Samples containing `failed_to_sample_task_fun` or `failed_to_stop_thread_fun`
67
+ indicate many short-lived tasks that completed before their backtraces could be
68
+ collected.
69
+
26
70
  ## Memory profiling
27
71
 
28
- Samples heap allocations. Useful for finding allocation hot spots and reducing
29
- GC pressure.
72
+ Samples heap allocations (Julia ≥ 1.8). Useful for finding allocation hot spots
73
+ and reducing GC pressure.
30
74
 
31
75
  ```julia
32
76
  using Profile, PProf
33
77
 
34
- # Warm up the JIT so compilation isn't captured as part of the profile.
78
+ # Warm up the JIT so the profile excludes compilation.
35
79
  my_function()
36
80
 
37
81
  Profile.Allocs.clear()
38
- Profile.Allocs.@profile my_function()
82
+ Profile.Allocs.@profile sample_rate = 0.01 my_function()
39
83
 
40
84
  PProf.Allocs.pprof(out = "allocs.pb.gz", web = false)
41
85
  ```
42
86
 
87
+ `sample_rate` is the fraction of allocations recorded: `1.0` records every
88
+ allocation, the default `0.1` records ~10%. Allocation-heavy workloads allocate
89
+ millions of times, so lower the rate until the run's overhead and the profile's
90
+ size are reasonable.
91
+
92
+ ## Heap snapshots
93
+
94
+ Captures a snapshot of all live objects on the heap (Julia ≥ 1.9), written
95
+ directly in the V8 heap snapshot format. Useful for diagnosing memory leaks.
96
+
97
+ ```julia
98
+ using Profile
99
+
100
+ # Code to capture...
101
+ Profile.take_heap_snapshot("heap.heapsnapshot")
102
+ ```
103
+
104
+ ### Options
105
+
106
+ | Option | Default | Description |
107
+ | ------------- | ------- | ------------------------------------------------------------------------ |
108
+ | `redact_data` | `true` | Omit the contents of Julia strings |
109
+ | `streaming` | `false` | Stream four intermediate files instead of holding the snapshot in memory |
110
+
111
+ A snapshot spans the entire runtime heap: `Base`, method tables, and every
112
+ loaded package. Expect files of hundreds of megabytes even for small programs.
113
+ They compress well: profiler-md accepts them gzipped as-is. For
114
+ memory-constrained processes, pass `streaming = true` and reassemble afterwards
115
+ with `Profile.HeapSnapshot.assemble_snapshot(prefix, "heap.heapsnapshot")`.
116
+
43
117
  ## `pprof` options
44
118
 
45
- | Option | Default | Description |
46
- | -------- | ----------------- | --------------------------------------------- |
47
- | `out` | `"profile.pb.gz"` | Output file path |
48
- | `web` | `true` | Launch the interactive web UI after exporting |
49
- | `from_c` | `true` | Include C and Julia runtime frames |
119
+ | Option | Default | Description |
120
+ | ----------------- | ----------------- | ------------------------------------------------ |
121
+ | `out` | `"profile.pb.gz"` | Output file path |
122
+ | `web` | `true` | Launch the interactive web UI after exporting |
123
+ | `from_c` | `true` | Include C and Julia runtime frames |
124
+ | `drop_frames` | `""` | Regex of function names to drop from stacks |
125
+ | `keep_frames` | `""` | Regex of function names to keep despite dropping |
126
+ | `full_signatures` | `true` | Use full method signatures as function names |
50
127
 
51
128
  ## Tips
52
129
 
53
130
  Run single-threaded (`julia -t 1 --gcthreads=1`). Otherwise idle GC and
54
- scheduler threads fill the profile with wait frames (`__psynch_cvwait`).
131
+ scheduler threads fill the profile with wait frames (`__psynch_cvwait`); the
132
+ wall-time profiler samples those idle tasks even more eagerly, since it samples
133
+ tasks that aren't running.
@@ -1,9 +1,8 @@
1
1
  # PHP
2
2
 
3
3
  PHP profiling uses the [Excimer](https://github.com/wikimedia/php-excimer)
4
- extension, a low-overhead sampling profiler. Excimer samples from a
5
- PHP-controlled timer, so you start and stop it from within the program or a
6
- prepended bootstrap script.
4
+ extension. Excimer samples from a PHP-controlled timer, so you start and stop it
5
+ within the program or a prepended bootstrap script.
7
6
 
8
7
  ## CPU profiling
9
8
 
@@ -44,7 +43,7 @@ file_put_contents('wall.speedscope.json',
44
43
 
45
44
  ## Profiling an existing program
46
45
 
47
- To profile a program you don't want to edit, point `auto_prepend_file` at a
46
+ To profile a program without editing it, point `auto_prepend_file` at a
48
47
  bootstrap script that starts the profiler and writes the result on shutdown:
49
48
 
50
49
  ```php
@@ -1,7 +1,7 @@
1
1
  # Python
2
2
 
3
- Python profiling uses [py-spy](https://github.com/benfred/py-spy), a sampling
4
- profiler that attaches to a running process or wraps a script.
3
+ Python profiling uses [py-spy](https://github.com/benfred/py-spy) or
4
+ [systing](https://github.com/josefbacik/systing).
5
5
 
6
6
  ## CPU profiling
7
7
 
@@ -17,7 +17,7 @@ py-spy record -f speedscope -o cpu.speedscope.json -- python script.py
17
17
  # Attach to a running process
18
18
  py-spy record -f raw -o cpu.collapsed --pid <pid>
19
19
 
20
- # Include native extensions written in Cython or C
20
+ # Include native Cython or C extensions
21
21
  py-spy record -f raw -o cpu.collapsed --native -- python script.py
22
22
  ```
23
23
 
@@ -45,13 +45,28 @@ py-spy dump --pid <pid> --locals
45
45
 
46
46
  ## CLI flags
47
47
 
48
- | Flag | Default | Description |
49
- | ------------------- | ------------ | ---------------------------------------------------------- |
50
- | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope` |
51
- | `-o` / `--output` | — | Output file path |
52
- | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
53
- | `-r` / `--rate` | `100` | Sampling rate in Hz |
54
- | `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
55
- | `--native` | off | Profile native extensions written in Cython or C |
56
- | `--nonblocking` | off | Don't pause the process to collect samples (less accurate) |
57
- | `--subprocesses` | off | Also profile subprocesses of the target |
48
+ | Flag | Default | Description |
49
+ | ------------------- | ------------ | -------------------------------------------------------- |
50
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope` |
51
+ | `-o` / `--output` | — | Output file path |
52
+ | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
53
+ | `-r` / `--rate` | `100` | Sampling rate in Hz |
54
+ | `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
55
+ | `--native` | off | Profile native Cython or C extensions |
56
+ | `--nonblocking` | off | Sample without pausing the process (less accurate) |
57
+ | `--subprocesses` | off | Also profile subprocesses of the target |
58
+
59
+ ## System profiling
60
+
61
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler that
62
+ samples on-CPU stacks and records a stack each time a thread sleeps. With
63
+ `--collect-pystacks` it walks CPython interpreter frames and blends them with
64
+ the native stack, so profiles show Python functions alongside the C and kernel
65
+ frames beneath them. It needs root (BPF) and a kernel with BTF
66
+ (`/sys/kernel/btf/vmlinux`).
67
+
68
+ ```sh
69
+ # Record a Python program with blended Python + native stacks
70
+ sudo systing --duration 30 --collect-pystacks \
71
+ --output profile.systing -- python3 script.py
72
+ ```
@@ -1,7 +1,6 @@
1
1
  # Ruby
2
2
 
3
- Ruby profiling uses [rbspy](https://rbspy.github.io), a sampling profiler that
4
- attaches to a running Ruby process.
3
+ Ruby profiling uses [rbspy](https://rbspy.github.io).
5
4
 
6
5
  ## CPU profiling
7
6
 
@@ -32,15 +31,14 @@ rbspy record --format speedscope -o profile.speedscope --subprocesses --pid <pid
32
31
  ## Snapshot
33
32
 
34
33
  Captures a single stack trace from a running process. Useful for quickly
35
- checking what a process is currently executing without starting a full
36
- recording.
34
+ checking what a process is executing without a full recording.
37
35
 
38
36
  ### CLI
39
37
 
40
38
  ```sh
41
39
  rbspy snapshot --pid <pid>
42
40
 
43
- # Don't pause the process while reading its stack
41
+ # Read the stack without pausing the process
44
42
  rbspy snapshot --nonblocking --pid <pid>
45
43
  ```
46
44
 
@@ -54,4 +52,4 @@ rbspy snapshot --nonblocking --pid <pid>
54
52
  | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `collapsed`, `pprof`, `speedscope`, `callgrind`, `summary`, `summary_by_line` |
55
53
  | `-o` / `--file` | — | Output file path |
56
54
  | `--subprocesses` | — | Also profile child processes |
57
- | `--nonblocking` | — | Don't pause the process while reading its stack (lower overhead, may miss frames) |
55
+ | `--nonblocking` | — | Read the stack without pausing the process (lower overhead, may miss frames) |
@@ -1,7 +1,7 @@
1
1
  # Rust
2
2
 
3
- Rust CPU profiling uses [pprof-rs](https://github.com/tikv/pprof-rs), a sampling
4
- profiler that integrates directly into your binary.
3
+ Rust CPU profiling uses [pprof-rs](https://github.com/tikv/pprof-rs) or
4
+ [systing](https://github.com/josefbacik/systing).
5
5
 
6
6
  ## CPU profiling
7
7
 
@@ -15,12 +15,7 @@ pprof = { version = "...", features = ["prost-codec", "frame-pointer"] }
15
15
  ```
16
16
 
17
17
  The `frame-pointer` feature is required on macOS (the default stack unwinder
18
- crashes with SIGBUS). Also add the following rustflag to make frame-pointer
19
- unwinding reliable:
20
-
21
- ```sh
22
- RUSTFLAGS="-C force-frame-pointers=yes" cargo build ...
23
- ```
18
+ crashes with SIGBUS).
24
19
 
25
20
  ```rust
26
21
  use pprof::protos::Message;
@@ -42,3 +37,37 @@ std::fs::write("cpu.pprof", &buf)?;
42
37
  | -------------------- | ------- | ---------------------------------------- |
43
38
  | `.frequency(hz)` | `100` | Samples per second |
44
39
  | `.blocklist(frames)` | `[]` | Stack frames to exclude from the profile |
40
+
41
+ ## System profiling
42
+
43
+ [systing](https://github.com/josefbacik/systing) is a Linux eBPF profiler that
44
+ samples on-CPU stacks and records a stack each time a thread sleeps, across user
45
+ and kernel code. Useful when the question spans more than the process (off-CPU
46
+ waits, syscall time, whole-node contention). It needs root (BPF) and a kernel
47
+ with BTF (`/sys/kernel/btf/vmlinux`).
48
+
49
+ ```sh
50
+ # Record a command (and its children) for 30 seconds
51
+ sudo systing --duration 30 --output profile.systing -- ./target/release/program
52
+ ```
53
+
54
+ ## Tips
55
+
56
+ ### Frame pointers
57
+
58
+ Frame-pointer unwinders walk the stack via frame pointers, which Cargo release
59
+ builds omit by default. Force them on:
60
+
61
+ ```sh
62
+ RUSTFLAGS="-C force-frame-pointers=yes" cargo build ...
63
+ ```
64
+
65
+ ### Symbols
66
+
67
+ Keep debug info for release builds so frames resolve to readable names:
68
+
69
+ ```toml
70
+ # Cargo.toml
71
+ [profile.release]
72
+ debug = true
73
+ ```