tracing_prof/
reporter.rs

1//! Reporters are used to report profiling data produced by the profile layer.
2
3use tracing::span;
4use tracing_core::callsite;
5
6use crate::config::ProfileConfig;
7
8#[cfg(feature = "pprof")]
9pub mod pprof;
10
11/// A trait that is used for reporting profile samples.
12///
13/// The reporting always happens on a dedicated thread, thus
14/// all operations are allowed to block as long as required.
15pub trait ProfileReporter {
16    /// Called once when the reporter is created.
17    fn init(&mut self, config: &ProfileConfig) {
18        _ = config;
19    }
20
21    /// A span was created, the reporter should keep
22    /// span metadata until the span is destroyed.
23    fn span_created(&mut self, span: &span::Id, metadata: SpanMetadata) {
24        _ = (span, metadata);
25    }
26
27    /// A span was destroyed, any labels and
28    /// other data recorded for it can be discarded.
29    fn span_destroyed(&mut self, span: &span::Id) {
30        _ = span;
31    }
32
33    /// Process CPU time data for a span.
34    ///
35    /// The values are relative to the last call to this function (if any).
36    fn span_cpu(&mut self, span: &span::Id, cpu: SpanCpuTime) {
37        _ = (span, cpu);
38    }
39
40    /// Process wall time data for a span.
41    ///
42    /// The values are relative to the last call to this function (if any).
43    fn span_wall(&mut self, span: &span::Id, wall: SpanWallTime) {
44        _ = (span, wall);
45    }
46
47    /// Process allocations for a span.
48    ///
49    /// The values are relative to the last call to this function (if any).
50    fn span_allocations(&mut self, span: &span::Id, allocs: SpanAllocations) {
51        _ = (span, allocs);
52    }
53
54    /// Process heap statistics for a span.
55    ///
56    /// The values represent the total current heap usage at the time of the call.
57    fn span_heap(&mut self, span: &span::Id, heap: SpanHeap) {
58        _ = (span, heap);
59    }
60
61    /// Flush all accumulated data.
62    ///
63    /// This function is also called when the reporter is shut down,
64    /// so it should never buffer or delay processing of data in any way.
65    fn flush(&mut self) {}
66}
67
68/// Metadata for a span.
69pub struct SpanMetadata {
70    /// The scope of the span.
71    pub scope: Vec<span::Id>,
72    /// The callsite ID of the span.
73    pub callsite: callsite::Identifier,
74    /// The span ID of the span.
75    pub target: &'static str,
76    /// The name of the span.
77    pub span_name: &'static str,
78    /// The file the span was created in.
79    pub file: &'static str,
80    /// The line the span was created on.
81    pub line: u32,
82    /// Labels for the span.
83    pub labels: Vec<(&'static str, String)>,
84}
85
86/// CPU time statistics for a span.
87#[derive(Debug)]
88pub struct SpanCpuTime {
89    /// The elapsed CPU time in nanoseconds in user mode.
90    pub elapsed_user_nanos: u64,
91    /// The elapsed CPU time in nanoseconds in kernel mode.
92    pub elapsed_system_nanos: u64,
93}
94
95/// Wall time statistics for a span.
96#[derive(Debug)]
97pub struct SpanWallTime {
98    /// The elapsed wall time in nanoseconds while
99    /// the span was entered.
100    pub elapsed_busy_nanos: u64,
101    /// The elapsed wall time in nanoseconds while
102    /// the span was idle.
103    pub elapsed_idle_nanos: u64,
104}
105
106/// Allocation statistics for a span.
107#[derive(Debug, Default)]
108pub struct SpanAllocations {
109    /// The number of allocations.
110    pub allocation_count: u64,
111    /// The number of bytes allocated.
112    pub allocated_bytes: u64,
113}
114
115/// Heap statistics for a span.
116#[derive(Debug)]
117pub struct SpanHeap {
118    /// The number of bytes in use.
119    pub in_use_bytes: u64,
120    /// The number of allocations in use.
121    pub in_use_count: u64,
122}
tracing_prof/reporter.rs

tracing_prof/
reporter.rs
