profiler-md 0.1.3 → 0.2.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,31 @@
1
+ # PHP
2
+
3
+ PHP profiling uses [phpspy](https://github.com/adsr/phpspy), a low overhead
4
+ sampling profiler for PHP processes.
5
+
6
+ ## CPU profiling
7
+
8
+ Periodically samples the call stack. Useful for finding CPU hot spots.
9
+
10
+ ```sh
11
+ # Profile a command (speedscope format)
12
+ phpspy -d 30 --output-format=speedscope -f cpu.speedscope -- php script.php
13
+
14
+ # Attach to a running process (speedscope format)
15
+ phpspy -d 30 --output-format=speedscope --pid <pid> -f cpu.speedscope
16
+
17
+ # Attach to a running process (callgrind format, for KCachegrind)
18
+ phpspy -d 30 --output-format=callgrind --pid <pid> > cpu.callgrind
19
+ ```
20
+
21
+ ### Flags
22
+
23
+ | Flag | Default | Description |
24
+ | -------------------- | ------- | ------------------------------------------------------------------ |
25
+ | `--pid` / `-p` | — | PID of the PHP process to profile |
26
+ | `--duration` / `-d` | — | Duration in seconds; profiles indefinitely when not set |
27
+ | `--sleep-us` / `-s` | `10000` | Sampling interval in microseconds |
28
+ | `--num-samples` | — | Maximum number of samples to collect |
29
+ | `--max-depth` / `-l` | `64` | Maximum stack frames per sample |
30
+ | `--output-format` | `raw` | Output format: `raw`, `callgrind`, `speedscope`, `valgrind`, `rep` |
31
+ | `--output-file` | stdout | Write output to this file instead of stdout |
@@ -0,0 +1,112 @@
1
+ # Python
2
+
3
+ Python profiling uses [py-spy](https://github.com/benford/py-spy), a sampling
4
+ profiler that attaches to a running process or wraps a script, and
5
+ [memray](https://github.com/bloomberg/memray) for memory profiling.
6
+
7
+ ## CPU profiling
8
+
9
+ Periodically samples the call stack. Useful for finding CPU hot spots.
10
+
11
+ ```sh
12
+ # pprof format (wrap a script)
13
+ py-spy record -f pprof -o cpu.pprof -- python script.py
14
+
15
+ # pprof format (attach to a running process)
16
+ py-spy record -f pprof -o cpu.pprof --pid <pid>
17
+
18
+ # Speedscope format
19
+ py-spy record -f speedscope -o profile.speedscope -- python script.py
20
+
21
+ # Include native extensions written in Cython or C
22
+ py-spy record -f pprof -o cpu.pprof --native -- python script.py
23
+ ```
24
+
25
+ ## Wall-clock profiling
26
+
27
+ Samples wall-clock time rather than CPU time. Useful for I/O-bound code where
28
+ threads spend time sleeping or waiting.
29
+
30
+ ```sh
31
+ # Wrap a script
32
+ py-spy record -f pprof -o profile.pprof --idle -- python script.py
33
+
34
+ # Attach to a running process
35
+ py-spy record -f pprof -o profile.pprof --idle --pid <pid>
36
+ ```
37
+
38
+ ## Memory profiling
39
+
40
+ Tracks heap allocations. Useful for finding allocation hot spots and memory
41
+ leaks.
42
+
43
+ ### CLI
44
+
45
+ ```sh
46
+ # Record a memory profile (wrap a script)
47
+ memray run -o mem.bin script.py
48
+
49
+ # Attach to a running process
50
+ memray attach -o mem.bin <pid>
51
+
52
+ # Convert to pprof format
53
+ memray pprof mem.bin
54
+ ```
55
+
56
+ ### Programmatic API
57
+
58
+ ```python
59
+ import memray
60
+
61
+ with memray.Tracker("mem.bin"):
62
+ # Code to profile...
63
+ pass
64
+ ```
65
+
66
+ ## Call stack dump
67
+
68
+ Captures the current call stacks of all threads in a running process. Useful for
69
+ diagnosing hangs, deadlocks, or unexpected blocking.
70
+
71
+ ### CLI
72
+
73
+ ```sh
74
+ # Dump call stacks of a running process (text output)
75
+ py-spy dump --pid <pid>
76
+
77
+ # Include local variables in each frame
78
+ py-spy dump --pid <pid> --locals
79
+ ```
80
+
81
+ ### Programmatic API
82
+
83
+ ```python
84
+ import faulthandler
85
+
86
+ faulthandler.dump_traceback() # all threads to stderr
87
+ ```
88
+
89
+ ## CLI flags
90
+
91
+ ### `py-spy`
92
+
93
+ | Flag | Default | Description |
94
+ | ------------------- | ------------ | ---------------------------------------------------------- |
95
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `raw`, `speedscope`, `pprof` |
96
+ | `-o` / `--output` | — | Output file path |
97
+ | `-d` / `--duration` | — | Duration in seconds (default: until program exits) |
98
+ | `-r` / `--rate` | `100` | Sampling rate in Hz |
99
+ | `--idle` | off | Include stack traces for idle (sleeping/waiting) threads |
100
+ | `--native` | off | Profile native extensions written in Cython or C |
101
+ | `--nonblocking` | off | Don't pause the process to collect samples (less accurate) |
102
+ | `--subprocesses` | off | Also profile subprocesses of the target |
103
+
104
+ ### `memray`
105
+
106
+ | Flag | Default | Description |
107
+ | --------------------------- | ------- | --------------------------------------------------- |
108
+ | `-o` / `--output` | — | Output file path |
109
+ | `--native` | off | Also capture native (C extension) stack frames |
110
+ | `--follow-fork` | off | Also profile child processes after `fork()` |
111
+ | `--aggregate` | off | Aggregate allocations to reduce output file size |
112
+ | `--trace-python-allocators` | off | Trace Python allocator calls for finer-grained data |
@@ -0,0 +1,67 @@
1
+ # Ruby
2
+
3
+ Ruby profiling uses [rbspy](https://rbspy.github.io), a sampling profiler that
4
+ attaches to a running Ruby process.
5
+
6
+ ## CPU profiling
7
+
8
+ Periodically samples the call stack. Useful for finding CPU hot spots.
9
+
10
+ ### CLI
11
+
12
+ ```sh
13
+ # Profile a command (speedscope format)
14
+ rbspy record --format speedscope -o profile.speedscope -- ruby script.rb
15
+
16
+ # Attach to a running process
17
+ rbspy record --format speedscope -o profile.speedscope --pid <pid>
18
+
19
+ # Profile for a fixed duration
20
+ rbspy record --format speedscope -o profile.speedscope --duration 30 --pid <pid>
21
+
22
+ # Profile including child processes
23
+ rbspy record --format speedscope -o profile.speedscope --subprocesses --pid <pid>
24
+ ```
25
+
26
+ ## Memory profiling
27
+
28
+ Records RSS memory alongside call stack samples. Useful for correlating memory
29
+ growth with specific code paths.
30
+
31
+ ### CLI
32
+
33
+ ```sh
34
+ # Record CPU and memory together
35
+ rbspy record --memory --format speedscope -o profile.speedscope --pid <pid>
36
+
37
+ # Profile a command with memory tracking
38
+ rbspy record --memory --format speedscope -o profile.speedscope -- ruby script.rb
39
+ ```
40
+
41
+ ## Snapshot
42
+
43
+ Captures a single stack trace from a running process. Useful for quickly
44
+ checking what a process is currently executing without starting a full
45
+ recording.
46
+
47
+ ### CLI
48
+
49
+ ```sh
50
+ rbspy snapshot --pid <pid>
51
+
52
+ # Don't pause the process while reading its stack
53
+ rbspy snapshot --nonblocking --pid <pid>
54
+ ```
55
+
56
+ ## CLI flags
57
+
58
+ | Flag | Default | Description |
59
+ | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
60
+ | `-p` / `--pid` | — | PID of a running process to attach to |
61
+ | `-d` / `--duration` | — | Duration in seconds; records until Ctrl-C if omitted |
62
+ | `-r` / `--rate` | `100` | Samples per second |
63
+ | `-f` / `--format` | `flamegraph` | Output format: `flamegraph`, `speedscope`, `callgrind`, `summary`, `summary_by_line`, `raw_call_stack` |
64
+ | `-o` / `--file` | — | Output file path |
65
+ | `-m` / `--memory` | — | Also record RSS memory usage alongside stack samples |
66
+ | `--subprocesses` | — | Also profile child processes |
67
+ | `--nonblocking` | — | Don't pause the process while reading its stack (lower overhead, may miss frames) |
@@ -0,0 +1,44 @@
1
+ # Rust
2
+
3
+ Rust CPU profiling uses [pprof-rs](https://github.com/tikv/pprof-rs), a sampling
4
+ profiler that integrates directly into your binary.
5
+
6
+ ## CPU profiling
7
+
8
+ Periodically samples the call stack. Useful for finding CPU hot spots.
9
+
10
+ Add to `Cargo.toml`:
11
+
12
+ ```toml
13
+ [dependencies]
14
+ pprof = { version = "...", features = ["prost-codec", "frame-pointer"] }
15
+ ```
16
+
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
+ ```
24
+
25
+ ```rust
26
+ use pprof::protos::Message;
27
+
28
+ let guard = pprof::ProfilerGuardBuilder::default()
29
+ .frequency(1000)
30
+ .build()?;
31
+
32
+ // Code to profile...
33
+
34
+ let mut buf = Vec::new();
35
+ guard.report().build()?.pprof()?.encode(&mut buf)?;
36
+ std::fs::write("cpu.pprof", &buf)?;
37
+ ```
38
+
39
+ ### `ProfilerGuardBuilder` options
40
+
41
+ | Method | Default | Description |
42
+ | -------------------- | ------- | ---------------------------------------- |
43
+ | `.frequency(hz)` | `100` | Samples per second |
44
+ | `.blocklist(frames)` | `[]` | Stack frames to exclude from the profile |