pamoja_telemetry/
event.rs

1//! Telemetry events: a severity level, a stable code, and an optional value.
2
3/// The severity of a telemetry event, ordered from most verbose to most urgent.
4///
5/// [`Trace`](Level::Trace) is the least urgent and [`Error`](Level::Error) the most,
6/// so a [`Reporter`](crate::Reporter) ships an event when its level is at or above the
7/// current threshold and drops it otherwise.
8#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
9pub enum Level {
10    /// Fine-grained detail, useful only when chasing a specific problem.
11    Trace,
12    /// Diagnostic detail for development.
13    Debug,
14    /// A normal, noteworthy event.
15    Info,
16    /// Something unexpected that the node recovered from.
17    Warn,
18    /// A failure that needs attention.
19    Error,
20}
21
22/// A structured telemetry event.
23///
24/// An event pairs a [`Level`] with a stable, short `code` - a label such as
25/// `"battery.low"` or `"link.lost"` rather than a free-form message - so events stay
26/// tiny, group cleanly into counts, and need no allocation. An optional `value`
27/// carries an associated measurement, such as the battery level that triggered it.
28#[derive(Clone, Copy, Debug, PartialEq)]
29pub struct Event {
30    /// The event's severity.
31    pub level: Level,
32    /// A stable, short identifier for what happened.
33    pub code: &'static str,
34    /// An optional measurement associated with the event.
35    pub value: Option<f32>,
36}
37
38impl Event {
39    /// Creates an event at `level` with the given code and no value.
40    ///
41    /// # Arguments
42    ///
43    /// * `level` - the event's severity.
44    /// * `code` - a stable, short identifier for the event.
45    ///
46    /// # Returns
47    ///
48    /// The event.
49    pub fn new(level: Level, code: &'static str) -> Self {
50        Self {
51            level,
52            code,
53            value: None,
54        }
55    }
56
57    /// Creates a [`Level::Trace`] event.
58    ///
59    /// # Arguments
60    ///
61    /// * `code` - a stable, short identifier for the event.
62    ///
63    /// # Returns
64    ///
65    /// The event.
66    pub fn trace(code: &'static str) -> Self {
67        Self::new(Level::Trace, code)
68    }
69
70    /// Creates a [`Level::Debug`] event.
71    ///
72    /// # Arguments
73    ///
74    /// * `code` - a stable, short identifier for the event.
75    ///
76    /// # Returns
77    ///
78    /// The event.
79    pub fn debug(code: &'static str) -> Self {
80        Self::new(Level::Debug, code)
81    }
82
83    /// Creates a [`Level::Info`] event.
84    ///
85    /// # Arguments
86    ///
87    /// * `code` - a stable, short identifier for the event.
88    ///
89    /// # Returns
90    ///
91    /// The event.
92    pub fn info(code: &'static str) -> Self {
93        Self::new(Level::Info, code)
94    }
95
96    /// Creates a [`Level::Warn`] event.
97    ///
98    /// # Arguments
99    ///
100    /// * `code` - a stable, short identifier for the event.
101    ///
102    /// # Returns
103    ///
104    /// The event.
105    pub fn warn(code: &'static str) -> Self {
106        Self::new(Level::Warn, code)
107    }
108
109    /// Creates a [`Level::Error`] event.
110    ///
111    /// # Arguments
112    ///
113    /// * `code` - a stable, short identifier for the event.
114    ///
115    /// # Returns
116    ///
117    /// The event.
118    pub fn error(code: &'static str) -> Self {
119        Self::new(Level::Error, code)
120    }
121
122    /// Attaches a measurement to the event.
123    ///
124    /// # Arguments
125    ///
126    /// * `value` - the measurement to associate with the event.
127    ///
128    /// # Returns
129    ///
130    /// The event, for chaining.
131    pub fn with_value(mut self, value: f32) -> Self {
132        self.value = Some(value);
133        self
134    }
135}
pamoja_telemetry/event.rs

pamoja_telemetry/
event.rs
