Expose port dataset for observability.

Author: davidv1992

statime-linux/src/main.rs

@@ -298,6 +298,7 @@ async fn actual_main() {
             parent_ds: instance.parent_ds(),
             time_properties_ds: instance.time_properties_ds(),
             path_trace_ds: instance.path_trace_ds(),
+            port_ds: vec![],
         });
     statime_linux::observer::spawn(&config, instance_state_receiver).await;
 
@@ -505,6 +506,7 @@ async fn run(
             parent_ds: instance.parent_ds(),
             time_properties_ds: instance.time_properties_ds(),
             path_trace_ds: instance.path_trace_ds(),
+            port_ds: mut_bmca_ports.iter().map(|v| v.port_ds()).collect(),
         });
 
         let mut clock_states = vec![ClockSyncMode::FromSystem; internal_sync_senders.len()];

statime-linux/src/metrics/format.rs

@@ -352,6 +352,57 @@ fn format_path_trace_ds(
     Ok(())
 }
 
+fn format_port_ds(
+    w: &mut impl Write,
+    port_ds: &[statime::observability::port::PortDS],
+    labels: Vec<(&'static str, String)>,
+) -> std::fmt::Result {
+    format_metric(
+        w,
+        "port_state",
+        "The current state of the port",
+        MetricType::Gauge,
+        None,
+        port_ds
+            .iter()
+            .map(|port_ds| {
+                let mut labels = labels.clone();
+                labels.push(("port", format!("{}", port_ds.port_identity.port_number)));
+                Measurement {
+                    labels,
+                    value: port_ds.port_state as u8,
+                }
+            })
+            .collect(),
+    )?;
+
+    format_metric(
+        w,
+        "mean_link_delay",
+        "The current mean link delay of the port",
+        MetricType::Gauge,
+        Some(Unit::Nanoseconds),
+        port_ds
+            .iter()
+            .filter_map(|port_ds| match port_ds.delay_mechanism {
+                statime::observability::port::DelayMechanism::P2P {
+                    mean_link_delay, ..
+                } => {
+                    let mut labels = labels.clone();
+                    labels.push(("port", format!("{}", port_ds.port_identity.port_number)));
+                    Some(Measurement {
+                        labels,
+                        value: mean_link_delay.to_nanos(),
+                    })
+                }
+                _ => None,
+            })
+            .collect(),
+    )?;
+
+    Ok(())
+}
+
 pub fn format_state(w: &mut impl std::fmt::Write, state: &ObservableState) -> std::fmt::Result {
     format_metric(
         w,
@@ -379,6 +430,7 @@ pub fn format_state(w: &mut impl std::fmt::Write, state: &ObservableState) -> st
     format_parent_ds(w, &state.instance.parent_ds, labels.clone())?;
     format_time_properties_ds(w, &state.instance.time_properties_ds, labels.clone())?;
     format_path_trace_ds(w, &state.instance.path_trace_ds, labels.clone())?;
+    format_port_ds(w, &state.instance.port_ds, labels.clone())?;
 
     w.write_str("# EOF\n")?;
     Ok(())

statime-linux/src/observer.rs

@@ -2,7 +2,9 @@ use std::{fs::Permissions, os::unix::prelude::PermissionsExt, path::Path, time::
 
 use statime::{
     config::TimePropertiesDS,
-    observability::{current::CurrentDS, default::DefaultDS, parent::ParentDS, PathTraceDS},
+    observability::{
+        current::CurrentDS, default::DefaultDS, parent::ParentDS, port::PortDS, PathTraceDS,
+    },
 };
 use tokio::{io::AsyncWriteExt, net::UnixStream, task::JoinHandle};
 
@@ -29,6 +31,8 @@ pub struct ObservableInstanceState {
     /// A concrete implementation of the PTP Path Trace dataset (IEEE1588-2019
     /// section 16.2.2)
     pub path_trace_ds: PathTraceDS,
+    /// Port datasets for all the ports.
+    pub port_ds: Vec<PortDS>,
 }
 
 pub async fn spawn(

statime/src/datastructures/common/mod.rs

@@ -15,7 +15,7 @@ pub use clock_identity::*;
 pub use clock_quality::*;
 pub use leap_indicator::*;
 pub(crate) use port_identity::*;
-pub(crate) use time_interval::*;
+pub use time_interval::*;
 pub use time_source::*;
 pub use timestamp::*;
 pub use tlv::*;

statime/src/datastructures/common/time_interval.rs

@@ -1,5 +1,6 @@
 use core::ops::{Deref, DerefMut};
 
+use az::Cast;
 use fixed::types::I48F16;
 
 use crate::{
@@ -9,7 +10,29 @@ use crate::{
 
 /// Represents time intervals in nanoseconds
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
-pub(crate) struct TimeInterval(pub I48F16);
+pub struct TimeInterval(pub I48F16);
+
+#[cfg(feature = "serde")]
+impl<'de> serde::Deserialize<'de> for TimeInterval {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        Ok(TimeInterval(I48F16::from_bits(i64::deserialize(
+            deserializer,
+        )?)))
+    }
+}
+
+#[cfg(feature = "serde")]
+impl serde::Serialize for TimeInterval {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_i64(self.0.to_bits())
+    }
+}
 
 impl Deref for TimeInterval {
     type Target = I48F16;
@@ -45,6 +68,12 @@ impl From<Duration> for TimeInterval {
     }
 }
 
+impl TimeInterval {
+    pub fn to_nanos(self) -> f64 {
+        self.0.cast()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

statime/src/observability/mod.rs

@@ -8,5 +8,8 @@ pub mod default;
 /// A concrete implementation of the PTP Parent dataset (IEEE1588-2019 section
 /// 8.2.3)
 pub mod parent;
+/// A concrete implementation of the PTP Port dataset (IEEE1588-2019 section
+/// 8.2.15)
+pub mod port;
 
 pub use crate::datastructures::datasets::PathTraceDS;

statime/src/observability/port.rs

@@ -0,0 +1,72 @@
+use crate::datastructures::common::{PortIdentity, TimeInterval};
+
+/// Type for `[PortDS].port_state`, see also *IEEE1588-2019 section 8.2.15.3.1
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[repr(u8)]
+#[allow(missing_docs)]
+pub enum PortState {
+    Initializing = 1,
+    Faulty = 2,
+    Disabled = 3,
+    Listening = 4,
+    PreMaster = 5,
+    Master = 6,
+    Passive = 7,
+    Uncalibrated = 8,
+    Slave = 9,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[repr(u8)]
+#[allow(missing_docs)]
+pub enum DelayMechanism {
+    E2E {
+        /// See *IEEE1588-2019 section 8.2.15.3.2*
+        log_min_delay_req_interval: i8,
+    } = 1,
+    P2P {
+        /// See *IEEE1588-2019 section 8.2.15.4.5*
+        log_min_p_delay_req_interval: i8,
+        /// See *IEEE1588-2019 section 8.2.15.3.3*
+        mean_link_delay: TimeInterval,
+    } = 2,
+    NoMechanism = 0xfe,
+    CommonP2P {
+        /// See *IEEE1588-2019 section 8.2.15.3.3*
+        mean_link_delay: TimeInterval,
+    } = 3,
+    Special = 4,
+}
+
+/// A concrete implementation of the PTP Port dataset (IEEE1588-2019 section
+/// 8.2.15)
+///
+/// meanLinkDelay, logMinDelayReqInterval and logMinPDelayReqInterval are
+/// exposed through the delay mechanism type when the relevant delay mechanism
+/// is in use.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct PortDS {
+    /// See *IEEE1588-2019 section 8.2.15.2.1*
+    pub port_identity: PortIdentity,
+    /// See *IEEE1588-2019 section 8.2.15.3.1*
+    pub port_state: PortState,
+    /// See *IEEE1588-2019 section 8.2.15.4.1*
+    pub log_announce_interval: i8,
+    /// See *IEEE1588-2019 section 8.2.15.4.2*
+    pub announce_receipt_timeout: u8,
+    /// See *IEEE1588-2019 section 8.2.15.4.3*
+    pub log_sync_interval: i8,
+    /// See *IEEE1588-2019 section 8.2.15.4.4*
+    pub delay_mechanism: DelayMechanism,
+    /// See *IEEE1588-2019 section 8.2.15.4.6*
+    pub version_number: u8,
+    /// See *IEEE1588-2019 section 8.2.15.4.7*
+    pub minor_version_number: u8,
+    /// See *IEEE1588-2019 section 8.2.15.4.8*
+    pub delay_asymmetry: TimeInterval,
+    /// See *IEEE1588-2019 section 8.2.15.5.2*
+    pub master_only: bool,
+}

statime/src/port/mod.rs

@@ -30,6 +30,7 @@ use crate::{
         messages::{Message, MessageBody},
     },
     filters::Filter,
+    observability::{self, port::PortDS},
     ptp_instance::{PtpInstanceState, PtpInstanceStateMutex},
     time::{Duration, Time},
 };
@@ -589,6 +590,40 @@ impl<L, A, R, C, F: Filter, S> Port<'_, L, A, R, C, F, S> {
     pub(crate) fn number(&self) -> u16 {
         self.port_identity.port_number
     }
+
+    /// Get a copy of the port dataset of the port
+    pub fn port_ds(&self) -> PortDS {
+        PortDS {
+            port_identity: self.port_identity,
+            port_state: match self.port_state {
+                PortState::Faulty => observability::port::PortState::Faulty,
+                PortState::Listening => observability::port::PortState::Listening,
+                PortState::Master => observability::port::PortState::Master,
+                PortState::Passive => observability::port::PortState::Passive,
+                PortState::Slave(_) => observability::port::PortState::Slave,
+            },
+            log_announce_interval: self.config.announce_interval.as_log_2(),
+            announce_receipt_timeout: self.config.announce_receipt_timeout,
+            log_sync_interval: self.config.sync_interval.as_log_2(),
+            delay_mechanism: match self.config.delay_mechanism {
+                crate::config::DelayMechanism::E2E { interval } => {
+                    observability::port::DelayMechanism::E2E {
+                        log_min_delay_req_interval: interval.as_log_2(),
+                    }
+                }
+                crate::config::DelayMechanism::P2P { interval } => {
+                    observability::port::DelayMechanism::P2P {
+                        log_min_p_delay_req_interval: interval.as_log_2(),
+                        mean_link_delay: self.mean_delay.map(|v| v.into()).unwrap_or_default(),
+                    }
+                }
+            },
+            version_number: 2,
+            minor_version_number: self.config.minor_ptp_version as u8,
+            delay_asymmetry: self.config.delay_asymmetry.into(),
+            master_only: self.config.master_only,
+        }
+    }
 }
 
 impl<'a, A, C, F: Filter, R: Rng, S: PtpInstanceStateMutex> Port<'a, InBmca, A, R, C, F, S> {