grafos_profile/lib.rs
1//! Program-level resource profiler for grafOS.
2//!
3//! Answers "where are my leases going?" — the grafOS equivalent of a CPU flame
4//! graph, but for resource consumption. Produces resource flame graphs, lease
5//! timelines, data-flow diagrams, and waste reports from [`grafos_observe::ResourceSpan`]
6//! data.
7//!
8//! # Quick start
9//!
10//! ```rust
11//! use grafos_profile::{ProfileRecording, ProfileSummary, WasteReport};
12//! use grafos_profile::span_json::SpanJson;
13//! use grafos_observe::span::ResourceSpan;
14//! use grafos_observe::trace::TraceContext;
15//! use grafos_observe::event::ResourceType;
16//!
17//! // Build a recording from in-memory spans
18//! let random: [u8; 24] = [0x42; 24];
19//! let ctx = TraceContext::new_root(&random);
20//! let mut span = ResourceSpan::new("my_op", ctx);
21//! span.start_time_unix_us = 1_000_000;
22//! span.end_time_unix_us = 2_000_000;
23//! span.lease_cost_byte_secs = 4096;
24//! span.bytes_read = 1024;
25//! span.record_op(ResourceType::Mem, grafos_observe::event::OpType::Read, 10);
26//! span.add_lease_id(1);
27//!
28//! let recording = ProfileRecording::from_spans(vec![span]);
29//! let summary = ProfileSummary::from_recording(&recording);
30//! assert_eq!(summary.span_count, 1);
31//!
32//! let waste = WasteReport::from_recording(&recording);
33//! assert!(waste.total_waste_byte_secs == 0 || waste.total_waste_byte_secs > 0);
34//! ```
35//!
36//! # Feature flags
37//!
38//! | Feature | Default | Effect |
39//! |---------|---------|--------|
40//! | `std` | Yes | Enables file I/O, serde_json for recording persistence |
41//! | `html` | Yes | Enables HTML report generation (flame graph, timeline, etc.) |
42
43#![cfg_attr(not(feature = "std"), no_std)]
44
45extern crate alloc;
46
47mod data_flow;
48mod flame_graph;
49mod recording;
50mod sensitivity;
51pub mod span_json;
52mod span_tree;
53mod summary;
54mod timeline;
55mod waste;
56
57#[cfg(feature = "std")]
58mod recorder;
59
60pub use data_flow::{DataFlowDiagram, DataFlowEdge, DataFlowNode, DataFlowNodeKind};
61pub use flame_graph::{FlameFrame, FlameGraph};
62pub use recording::ProfileRecording;
63pub use sensitivity::{infer_sensitivity, DimensionScore, SensitivityLevel, WorkloadProfile};
64pub use span_tree::{SpanTree, SpanTreeNode};
65pub use summary::{ProfileSummary, ResourceTypeSummary};
66pub use timeline::{LeaseTimeline, LeaseTimelineEntry};
67pub use waste::{WasteClassification, WasteEntry, WasteReport};
68
69#[cfg(feature = "std")]
70pub use recorder::ProfileRecorder;