1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
// Copyright 2019 TiKV Project Authors. Licensed under Apache-2.0.
//! `rpprof` is a modern CPU, wall-clock, and heap profiler for Rust programs.
//!
//! It provides low-overhead, async-signal-safe profiling designed for both
//! production services and local benchmarking.
//!
//! # Features & Highlights
//!
//! - **Zero-Configuration Unwinding**: Fast, allocation-free DWARF stack unwinding via
//! `framehop` enabled by default—**no `-Cforce-frame-pointers=yes` or special compiler flags required**.
//! - **CPU & Wall-Clock Profiling**: Choose between CPU time ([`ClockType::Cpu`]) and real
//! wall-clock time ([`ClockType::Wall`]) to capture both compute bottlenecks and off-CPU latency
//! (async I/O, database queries, lock contention).
//! - **Sampled Heap Profiling**: [`alloc::AllocProfiler`] wraps your global allocator to track live
//! in-use memory and cumulative allocation churn with `<1%` overhead.
//! - **Multiple Output Formats**: Export directly to SVG flamegraphs ([`Report::flamegraph`]),
//! [Speedscope](https://www.speedscope.app/) JSON ([`Report::write_speedscope`]), raw folded stacks
//! ([`Report::write_folded`]), and Google pprof protobuf ([`Report::pprof`]).
//!
//! # Quick Start: One-Liner CPU Profiling
//!
//! ```rust,no_run
//! use std::time::Duration;
//! use std::fs::File;
//!
//! // Profile CPU for 10 seconds
//! let report = rpprof::profile(Duration::from_secs(10)).unwrap();
//!
//! // Save an interactive SVG flamegraph
//! let file = File::create("flamegraph.svg").unwrap();
//! report.flamegraph(file).unwrap();
//! ```
//!
//! # Guard-Based Profiling
//!
//! For scoped profiling over specific operations or custom configurations:
//!
//! ```rust
//! let guard = rpprof::ProfilerGuardBuilder::default()
//! .frequency(100)
//! .blocklist(&["libc", "libgcc", "pthread", "vdso"])
//! .build()
//! .unwrap();
//!
//! // Run workload...
//!
//! if let Ok(report) = guard.report().build() {
//! println!("Total samples: {}", report.total_samples());
//! println!("Missed ticks: {}", guard.missed_samples());
//!
//! // Write folded stacks
//! let mut output = Vec::new();
//! report.write_folded(&mut output).unwrap();
//! };
//! ```
//!
//! # Wall-Clock (Off-CPU) Profiling
//!
//! To capture time spent waiting on async tasks, I/O, locks, or network calls:
//!
//! ```rust
//! let guard = rpprof::ProfilerGuardBuilder::default()
//! .frequency(100)
//! .clock_type(rpprof::ClockType::Wall)
//! .build()
//! .unwrap();
//! ```
//!
//! # Sampled Heap / Memory Profiling
//!
//! Configure [`alloc::AllocProfiler`] as your `#[global_allocator]`:
//!
//! ```rust,no_run
//! use std::fs::File;
//!
//! #[global_allocator]
//! static ALLOC: rpprof::alloc::AllocProfiler = rpprof::alloc::AllocProfiler::system();
//!
//! fn main() {
//! rpprof::alloc::start();
//!
//! // Run allocation-heavy workload...
//!
//! let heap = rpprof::alloc::heap_report().unwrap();
//! let inuse_report = heap.to_inuse_report();
//! let mut flame = File::create("heap_inuse.svg").unwrap();
//! inuse_report.flamegraph(&mut flame).unwrap();
//!
//! rpprof::alloc::stop();
//! }
//! ```
/// Define the MAX supported stack depth. TODO: make this variable mutable.
pub const MAX_DEPTH: usize = 1024;
pub const MAX_DEPTH: usize = 512;
pub const MAX_DEPTH: usize = 128;
/// Define the MAX supported thread name length. TODO: make this variable mutable.
pub const MAX_THREAD_NAME: usize = 16;
pub use validate;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ClockType;
pub use flamegraph;
/// Collects a CPU profile at 99Hz for the specified duration and returns the resulting report.
///
/// # Example
///
/// ```rust,no_run
/// use std::time::Duration;
///
/// let report = rpprof::profile(Duration::from_secs(5)).unwrap();
/// let mut file = std::fs::File::create("profile.folded").unwrap();
/// report.write_folded(&mut file).unwrap();
/// ```
/// Collects a CPU profile with a custom frequency in Hz for the specified duration.
/// Collects a real Wall-clock profile at 99Hz for the specified duration.
///
/// Useful for identifying time spent blocked on I/O, database queries, mutexes, or network calls.