feat(telemetry): implement custom serialization for telemetry ids

Add custom `Display`, `FromStr`, `Serialize`, and `Deserialize`
implementations for `ProcessId`, `ThreadId`, `ExecutionId`, and
`SpanContext` types.

These provide a consistent hex-encoded string format with colon
separators for composite IDs (`process:thread` for `ExecutionId`,
`process:span` for `SpanContext`). This makes telemetry ids more
readable and provides a unified format for logging and serialization.

Signed-off-by: Wim Looman <[email protected]>

Author: Nemo157

CHANGELOG.md

@@ -8,6 +8,7 @@
 * **breaking** Removed `Span::root` method and `root_span!` macro; root spans should use `Span::new` and `span!` instead.
 * **breaking** Replaced `SpanContext::from_span` with `Span::context` method.
 * **breaking** Telemetry execution id is replaced by separate thread and process ids to uniquely identify thread/task combinations.
+* Added custom serialization for telemetry ids with hex-encoded string format.
 * Added `ThreadAbstraction` trait to OSAL for querying current thread id.
 * Updated MSRV to 1.91.
 * Fixed `veecle_os::telemetry::instrument` macro to automatically resolve correct crate paths for the facade.

veecle-telemetry/src/id.rs

@@ -16,8 +16,6 @@
 use core::fmt;
 use core::str::FromStr;
 
-use serde::{Deserialize, Serialize};
-
 /// A globally-unique id identifying a process.
 ///
 /// The primary purpose of this id is to provide a globally-unique context within which
@@ -26,9 +24,7 @@ use serde::{Deserialize, Serialize};
 /// most embedded setups it should be unique for each time the system is restarted.
 ///
 /// [`ThreadId`]: crate::protocol::ThreadId
-#[derive(
-    Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Default, Serialize, Deserialize,
-)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Default)]
 pub struct ProcessId(u128);
 
 impl ProcessId {
@@ -52,6 +48,43 @@ impl ProcessId {
     }
 }
 
+impl fmt::Display for ProcessId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:032x}", self.0)
+    }
+}
+
+impl FromStr for ProcessId {
+    type Err = core::num::ParseIntError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        u128::from_str_radix(s, 16).map(ProcessId)
+    }
+}
+
+impl serde::Serialize for ProcessId {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let mut hex_bytes = [0u8; size_of::<u128>() * 2];
+        hex::encode_to_slice(self.0.to_le_bytes(), &mut hex_bytes).unwrap();
+
+        serializer.serialize_str(str::from_utf8(&hex_bytes).unwrap())
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for ProcessId {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let bytes: [u8; size_of::<u128>()] = hex::serde::deserialize(deserializer)?;
+
+        Ok(ProcessId(u128::from_le_bytes(bytes)))
+    }
+}
+
 /// A process-unique id for a span.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct SpanId(pub u64);
@@ -106,7 +139,7 @@ impl<'de> serde::Deserialize<'de> for SpanId {
 }
 
 /// A struct representing the context of a span, including its [`ProcessId`] and [`SpanId`].
-#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct SpanContext {
     /// The id of the process this span belongs to.
     pub process_id: ProcessId,
@@ -160,6 +193,119 @@ impl SpanContext {
     }
 }
 
+impl fmt::Display for SpanContext {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let Self {
+            process_id,
+            span_id,
+        } = self;
+        write!(f, "{process_id}:{span_id}")
+    }
+}
+
+/// Errors that can occur while parsing [`SpanContext`] from a string.
+#[derive(Clone, Debug)]
+pub enum ParseSpanContextError {
+    /// The string is missing a `:` separator.
+    MissingSeparator,
+
+    /// The embedded [`ProcessId`] failed to parse.
+    InvalidProcessId(core::num::ParseIntError),
+
+    /// The embedded [`SpanId`] failed to parse.
+    InvalidSpanId(core::num::ParseIntError),
+}
+
+impl fmt::Display for ParseSpanContextError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::MissingSeparator => f.write_str("missing ':' separator"),
+            Self::InvalidProcessId(_) => f.write_str("failed to parse process id"),
+            Self::InvalidSpanId(_) => f.write_str("failed to parse span id"),
+        }
+    }
+}
+
+impl core::error::Error for ParseSpanContextError {
+    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
+        match self {
+            Self::MissingSeparator => None,
+            Self::InvalidProcessId(error) => Some(error),
+            Self::InvalidSpanId(error) => Some(error),
+        }
+    }
+}
+
+impl FromStr for SpanContext {
+    type Err = ParseSpanContextError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let Some((process_id, span_id)) = s.split_once(":") else {
+            return Err(ParseSpanContextError::MissingSeparator);
+        };
+        let process_id =
+            ProcessId::from_str(process_id).map_err(ParseSpanContextError::InvalidProcessId)?;
+        let span_id = SpanId::from_str(span_id).map_err(ParseSpanContextError::InvalidSpanId)?;
+        Ok(Self {
+            process_id,
+            span_id,
+        })
+    }
+}
+
+impl serde::Serialize for SpanContext {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let mut bytes = [0u8; 49];
+
+        hex::encode_to_slice(self.process_id.to_raw().to_le_bytes(), &mut bytes[..32]).unwrap();
+        bytes[32] = b':';
+        hex::encode_to_slice(self.span_id.0.to_le_bytes(), &mut bytes[33..]).unwrap();
+
+        serializer.serialize_str(str::from_utf8(&bytes).unwrap())
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for SpanContext {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        use serde::de::Error;
+
+        let string = <&str>::deserialize(deserializer)?;
+
+        if string.len() != 49 {
+            return Err(D::Error::invalid_length(
+                string.len(),
+                &"expected 49 byte string",
+            ));
+        }
+
+        let bytes = string.as_bytes();
+
+        if bytes[32] != b':' {
+            return Err(D::Error::invalid_value(
+                serde::de::Unexpected::Str(string),
+                &"expected : separator at byte 32",
+            ));
+        }
+
+        let mut process = [0; 16];
+        hex::decode_to_slice(&bytes[..32], &mut process).map_err(D::Error::custom)?;
+
+        let mut span = [0; 8];
+        hex::decode_to_slice(&bytes[33..], &mut span).map_err(D::Error::custom)?;
+
+        Ok(Self {
+            process_id: ProcessId::from_raw(u128::from_le_bytes(process)),
+            span_id: SpanId(u64::from_le_bytes(span)),
+        })
+    }
+}
+
 #[cfg(all(test, feature = "std"))]
 mod tests {
     use std::collections::HashSet;
@@ -308,6 +454,75 @@ mod tests {
         assert_eq!(context.span_id, span_id);
     }
 
+    #[test]
+    fn process_id_format_from_str_roundtrip() {
+        let test_cases = [
+            0u128,
+            1,
+            0x123,
+            0xFEDCBA9876543210,
+            0x123456789ABCDEF0FEDCBA9876543210,
+            u128::MAX,
+            u128::MAX - 1,
+        ];
+
+        for value in test_cases {
+            let process_id = ProcessId::from_raw(value);
+            let formatted = format!("{process_id}");
+            let parsed = formatted.parse::<ProcessId>().unwrap();
+            assert_eq!(process_id, parsed, "Failed roundtrip for value {value:#x}");
+        }
+    }
+
+    #[test]
+    fn process_id_serde_roundtrip() {
+        let test_cases = [
+            ProcessId::from_raw(0),
+            ProcessId::from_raw(1),
+            ProcessId::from_raw(0x123),
+            ProcessId::from_raw(0xFEDCBA9876543210),
+            ProcessId::from_raw(0x123456789ABCDEF0FEDCBA9876543210),
+            ProcessId::from_raw(u128::MAX),
+            ProcessId::from_raw(u128::MAX - 1),
+        ];
+
+        for original in test_cases {
+            let json = serde_json::to_string(&original).unwrap();
+            let deserialized: ProcessId = serde_json::from_str(&json).unwrap();
+            assert_eq!(
+                original,
+                deserialized,
+                "JSON roundtrip failed for {:#x}",
+                original.to_raw()
+            );
+        }
+    }
+
+    #[test]
+    fn span_context_format_from_str_roundtrip() {
+        let test_cases = [
+            SpanContext::new(ProcessId::from_raw(0), SpanId(0)),
+            SpanContext::new(
+                ProcessId::from_raw(0x123456789ABCDEF0FEDCBA9876543210),
+                SpanId(0xFEDCBA9876543210),
+            ),
+            SpanContext::new(ProcessId::from_raw(u128::MAX), SpanId(u64::MAX)),
+            SpanContext::new(ProcessId::from_raw(1), SpanId(1)),
+        ];
+
+        for context in test_cases {
+            let formatted = format!("{context}");
+            let parsed = formatted.parse::<SpanContext>().unwrap();
+            assert_eq!(
+                context,
+                parsed,
+                "Failed roundtrip for {:#x}:{:#x}",
+                context.process_id.to_raw(),
+                context.span_id.0
+            );
+        }
+    }
+
     #[test]
     fn span_id_next_id_produces_non_zero_values() {
         let ids: Vec<SpanId> = (0..100).map(|_| SpanId::next_id()).collect();