scuffle_pprof/
lib.rs

1//! A crate designed to provide a more ergonomic interface to the `pprof` crate.
2//!
3//! Only supports Unix-like systems. This crate will be empty on Windows.
4#![cfg_attr(
5    all(feature = "docs", unix),
6    doc = "\n\nSee the [changelog][changelog] for a full release history."
7)]
8#![cfg_attr(feature = "docs", doc = "## Feature flags")]
9#![cfg_attr(feature = "docs", doc = document_features::document_features!())]
10//! ## Example
11//!
12//! ```rust,no_run
13//! # #[cfg(unix)]
14//! # {
15//! // Create a new CPU profiler with a sampling frequency of 1000 Hz and an empty ignore list.
16//! let cpu = scuffle_pprof::Cpu::new::<String>(1000, &[]);
17//!
18//! // Capture a pprof profile for 10 seconds.
19//! // This call is blocking. It is recommended to run it in a separate thread.
20//! let capture = cpu.capture(std::time::Duration::from_secs(10)).unwrap();
21//!
22//! // Write the profile to a file.
23//! std::fs::write("capture.pprof", capture).unwrap();
24//! # }
25//! ```
26//!
27//! ## Analyzing the profile
28//!
29//! The resulting profile can be analyzed using the [`pprof`](https://github.com/google/pprof) tool.
30//!
31//! For example, to generate a flamegraph:
32//! ```sh
33//! pprof -svg capture.pprof
34//! ```
35//!
36//! ## License
37//!
38//! This project is licensed under the MIT or Apache-2.0 license.
39//! You can choose between one of them if you use this work.
40//!
41//! `SPDX-License-Identifier: MIT OR Apache-2.0`
42#![cfg_attr(all(coverage_nightly, test), feature(coverage_attribute))]
43#![cfg_attr(docsrs, feature(doc_auto_cfg))]
44#![cfg(unix)]
45#![deny(missing_docs)]
46#![deny(unsafe_code)]
47#![deny(unreachable_pub)]
48
49mod cpu;
50
51pub use cpu::Cpu;
52
53/// An error that can occur while profiling.
54#[derive(Debug, thiserror::Error)]
55pub enum PprofError {
56    /// An I/O error.
57    #[error(transparent)]
58    Io(#[from] std::io::Error),
59    /// A pprof error.
60    #[error(transparent)]
61    Pprof(#[from] pprof::Error),
62}
63
64/// Changelogs generated by [scuffle_changelog]
65#[cfg(feature = "docs")]
66#[scuffle_changelog::changelog]
67pub mod changelog {}
68
69#[cfg(test)]
70#[cfg_attr(all(coverage_nightly, test), coverage(off))]
71mod tests {
72    use std::io::Read;
73    use std::time::SystemTime;
74
75    use flate2::read::GzDecoder;
76    use pprof::protos::Message;
77
78    use crate::Cpu;
79
80    #[test]
81    fn empty_profile() {
82        let before_nanos = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_nanos() as i64;
83
84        let cpu = Cpu::new::<String>(1000, &[]);
85        let profile = cpu.capture(std::time::Duration::from_secs(1)).unwrap();
86
87        // Decode the profile
88        let mut reader = GzDecoder::new(profile.as_slice());
89        let mut buf = Vec::new();
90        reader.read_to_end(&mut buf).unwrap();
91        let profile = pprof::protos::Profile::decode(buf.as_slice()).unwrap();
92
93        assert!(profile.duration_nanos > 1_000_000_000);
94        assert!(profile.time_nanos > before_nanos);
95        let now_nanos = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_nanos() as i64;
96        assert!(profile.time_nanos < now_nanos);
97
98        assert_eq!(profile.string_table[profile.drop_frames as usize], "");
99        assert_eq!(profile.string_table[profile.keep_frames as usize], "");
100
101        let Some(period_type) = profile.period_type else {
102            panic!("missing period type");
103        };
104        assert_eq!(profile.string_table[period_type.ty as usize], "cpu");
105        assert_eq!(profile.string_table[period_type.unit as usize], "nanoseconds");
106
107        assert_eq!(profile.period, 1_000_000);
108    }
109}
scuffle_pprof/lib.rs

scuffle_pprof/
lib.rs
