Improved metrics semantics. Bug fix

core/common/src/lib.rs

@@ -13,3 +13,4 @@ pub mod map_handlers;
 pub mod otel_metrics;
 #[cfg(feature = "program-handlers")]
 pub mod program_handlers;
+mod semantic;

core/common/src/otel_metrics.rs

@@ -12,9 +12,10 @@
 //!   telemetry by process.
 
 use crate::buffer_type::{
-    CpuFrequency, CpuIdle, MemAlloc, NetworkMetrics, SchedStatRuntime, SchedStatWait,
+    CpuFrequency, CpuIdle, MemAlloc, PacketLossMetrics, SchedStatRuntime, SchedStatWait,
     TimeStampMetrics,
 };
+use crate::semantic::Semantic;
 use opentelemetry::KeyValue;
 use opentelemetry::metrics::{Counter, Gauge, Histogram, Meter};
 pub struct Metrics {
@@ -23,7 +24,7 @@ pub struct Metrics {
 
     /// Total number of network-related events produced by the `net_metrics`
     /// eBPF map.
-    pub packets_total: Counter<u64>,
+    pub socket_events_total: Counter<u64>,
 
     /// Observed socket drop count (`sk_drops`) from the kernel sock struct.
     pub sk_drops: Gauge<i64>,
@@ -33,11 +34,7 @@ pub struct Metrics {
 
     /// Histogram of `delta_us` values supplied by the `time_stamp_events`
     /// perf buffer.
-    pub delta_us: Histogram<u64>,
-
-    /// Histogram of `ts_us` values seen in both `net_metrics` and
-    /// `time_stamp_events`.
-    pub ts_us: Histogram<u64>,
+    pub tcp_latency_us: Histogram<u64>,
 
     /// Cpu bytes alloc total events
     pub cpu_bytes_alloc_events_total: Counter<u64>,
@@ -54,154 +51,179 @@ pub struct Metrics {
     /// Observed scheduler wait time in nanoseconds (sched_stat_wait).
     pub sched_stat_wait: Gauge<i64>,
 
+    /// Distribution of scheduler wait times in nanoseconds (sched_stat_wait).
+    pub sched_stat_wait_distribution: Histogram<u64>,
+
     /// Observed scheduler runtime in nanoseconds (sched_stat_runtime).
     pub sched_stat_runtime: Gauge<i64>,
 
+    /// Distribution of scheduler runtimes in nanoseconds (sched_stat_runtime).
+    pub sched_stat_runtime_distribution: Histogram<u64>,
+
     /// Current CPU idle C-state per cpu_id, updated only on state change.
     pub cpu_idle_state: Gauge<i64>,
 }
 
+// TODO: add identity metrics with TC classifier packet counts
+// TODO: introduce a metric called total_tcp_packets total_udp_packets
 impl Metrics {
     /// Initialise all instruments backed by the supplied [`Meter`].
     pub fn new(meter: &Meter) -> Self {
         // total events
         let events_total = meter
-            .u64_counter("events_total")
-            .with_description("Total number of eBPF events processed")
+            .u64_counter(Semantic::TotalEvents.title())
+            .with_description(Semantic::TotalEvents.description())
+            .with_unit("1")
             .build();
 
-        // total packets
-        let packets_total = meter
-            .u64_counter("packets_total")
-            .with_description("Total number of network events processed")
+        // total socket events
+        let socket_events_total = meter
+            .u64_counter(Semantic::SocketTotalEvents.title())
+            .with_description(Semantic::SocketTotalEvents.description())
+            .with_unit("1")
             .build();
 
         // socket drops
         let sk_drops = meter
-            .i64_gauge("sk_drops")
-            .with_description("Socket drop count per event")
+            .i64_gauge(Semantic::SocketDrops.title())
+            .with_description(Semantic::SocketDrops.description())
+            .with_unit("1")
             .build();
 
         // socket errors
         let sk_err = meter
-            .i64_gauge("sk_err")
-            .with_description("Socket error count per event")
+            .i64_gauge(Semantic::SocketErrorsCount.title())
+            .with_description(Semantic::SocketErrorsCount.description())
+            .with_unit("1")
             .build();
 
-        // delta microseconds
-        let delta_us = meter
-            .u64_histogram("delta_us")
-            .with_description("Distribution of delta_us values from timestamp events")
-            .build();
-
-        // timestamp microseconds grouped
-        let ts_us = meter
-            .u64_histogram("ts_us")
-            .with_description("Distribution of timestamp values from eBPF events")
+        // tcp latency microseconds
+        let tcp_latency_us = meter
+            .u64_histogram(Semantic::Latency.title())
+            .with_description(Semantic::Latency.description())
+            .with_unit("us")
             .build();
 
         // cpu bytes alloc total events
         let cpu_bytes_alloc_events_total = meter
-            .u64_counter("bytes_alloc_events_total")
-            .with_description("Total bytes_alloc events occuring in the CPU")
+            .u64_counter(Semantic::PerCpuTotalEvents.title())
+            .with_description(Semantic::PerCpuTotalEvents.description())
+            .with_unit("1")
             .build();
 
         // cpu bytes allocation
         let cpu_bytes_alloc = meter
-            .i64_gauge("cpu_bytes_alloc")
-            .with_description("Cpu bytes allocation per event")
+            .i64_gauge(Semantic::PerCpuBytesAllocated.title())
+            .with_description(Semantic::PerCpuBytesAllocated.description())
+            .with_unit("bytes")
             .build();
 
         // memory allocation (mmap) events total
         let mem_alloc_events_total = meter
-            .u64_counter("mem_alloc_events_total")
-            .with_description("Total number of memory allocation (mmap) events processed")
+            .u64_counter(Semantic::TotalMemoryAllocationEvents.title())
+            .with_description(Semantic::TotalMemoryAllocationEvents.description())
+            .with_unit("1")
             .build();
 
         // bytes requested via mmap syscalls
         let enter_mem_alloc = meter
-            .i64_gauge("enter_mem_alloc")
-            .with_description("Bytes requested via mmap syscalls")
+            .i64_gauge(Semantic::RequestedMemoryBytes.title())
+            .with_description(Semantic::RequestedMemoryBytes.description())
+            .with_unit("bytes")
             .build();
 
         // scheduler wait time in nanoseconds
         let sched_stat_wait = meter
-            .i64_gauge("sched_stat_wait")
-            .with_description("Scheduler wait time in nanoseconds from sched_stat_wait")
+            .i64_gauge(Semantic::SchedulerWaitTime.title())
+            .with_description(Semantic::SchedulerWaitTime.description())
+            .with_unit("ns")
+            .build();
+
+        // distribution of scheduler wait times
+        let sched_stat_wait_distribution = meter
+            .u64_histogram(Semantic::SchedulerWaitTimeDistribution.title())
+            .with_description(Semantic::SchedulerWaitTimeDistribution.description())
+            .with_unit("ns")
             .build();
 
         // scheduler runtime in nanoseconds
         let sched_stat_runtime = meter
-            .i64_gauge("sched_stat_runtime")
-            .with_description("Scheduler runtime in nanoseconds from sched_stat_runtime")
+            .i64_gauge(Semantic::SchedulerRuntime.title())
+            .with_description(Semantic::SchedulerRuntime.description())
+            .with_unit("ns")
+            .build();
+
+        // distribution of scheduler runtimes
+        let sched_stat_runtime_distribution = meter
+            .u64_histogram(Semantic::SchedulerRuntimeDistribution.title())
+            .with_description(Semantic::SchedulerRuntimeDistribution.description())
+            .with_unit("ns")
             .build();
 
         // current CPU idle C-state per cpu_id
         let cpu_idle_state = meter
-            .i64_gauge("cpu_idle_state")
-            .with_description("Current CPU idle C-state per cpu_id, updated only on state change")
+            .i64_gauge(Semantic::CpuIdleState.title())
+            .with_description(Semantic::CpuIdleState.description())
             .build();
-
         Self {
             events_total,
-            packets_total,
+            socket_events_total,
             sk_drops,
             sk_err,
-            delta_us,
-            ts_us,
+            tcp_latency_us,
             cpu_bytes_alloc,
             cpu_bytes_alloc_events_total,
             mem_alloc_events_total,
             enter_mem_alloc,
             sched_stat_wait,
+            sched_stat_wait_distribution,
             sched_stat_runtime,
+            sched_stat_runtime_distribution,
             cpu_idle_state,
         }
     }
 
-    /// Record a single [`NetworkMetrics`] event.
+    /// Record a single [`PacketLossMetrics`] event.
     ///
-    /// Increments `events_total` and `packets_total`, records `sk_drops` and
-    /// `sk_err` as gauges, and observes `ts_us` in the timestamp histogram.
+    /// Increments `events_total` and `socket_events_total`, records `sk_drops`
+    /// and `sk_err` as gauges.
     ///
     /// Every observation carries:
     ///
-    /// -`tgid` – task group ID.
-    /// - `comm` – command name (null-terminated bytes converted to a UTF-8
+    /// - `tgid` – task group ID.
+    /// - `command` – command name (null-terminated bytes converted to a UTF-8
     ///   string and trimmed).
-    pub fn record_network_metrics(&self, m: &NetworkMetrics) {
+    pub fn record_packet_loss_metrics(&self, m: &PacketLossMetrics) {
         let comm = String::from_utf8_lossy(&m.comm);
         let comm_trimmed = comm.trim_end_matches('\0').to_string();
         let attrs = &[
             KeyValue::new("tgid", m.tgid as i64),
-            KeyValue::new("comm", comm_trimmed),
+            KeyValue::new("command", comm_trimmed),
         ];
 
         self.events_total.add(1, attrs);
-        self.packets_total.add(1, attrs);
+        self.socket_events_total.add(1, attrs);
         self.sk_drops.record(m.sk_drops as i64, attrs);
         self.sk_err.record(m.sk_err as i64, attrs);
-        self.ts_us.record(m.ts_us, attrs);
     }
 
     /// Record a single [`TimeStampMetrics`] event.
     ///
-    /// Increments `events_total`, and records `delta_us` and `ts_us` in their
-    /// respective histograms.
+    /// Increments `events_total`, and records `delta_us` in the latency
+    /// histogram.
     ///
-    /// Every observation carries `tgid` and `comm` (see
-    /// [`record_network_metrics`]).
+    /// Every observation carries `tgid` and `command` (see
+    /// [`record_packet_loss_metrics`]).
     pub fn record_timestamp_metrics(&self, m: &TimeStampMetrics) {
         let comm = String::from_utf8_lossy(&m.comm);
         let comm_trimmed = comm.trim_end_matches('\0').to_string();
         let attrs = &[
             KeyValue::new("tgid", m.tgid as i64),
-            KeyValue::new("comm", comm_trimmed),
+            KeyValue::new("command", comm_trimmed),
         ];
 
         self.events_total.add(1, attrs);
-        self.delta_us.record(m.delta_us, attrs);
-        self.ts_us.record(m.ts_us, attrs);
+        self.tcp_latency_us.record(m.delta_us, attrs);
     }
 
     pub fn record_cpu_bytes_alloc(&self, m: &CpuFrequency) {
@@ -231,14 +253,16 @@ impl Metrics {
             KeyValue::new("command", command),
         ];
 
+        self.events_total.add(1, attrs);
         self.mem_alloc_events_total.add(1, attrs);
         self.enter_mem_alloc.record(m.length as i64, attrs);
     }
 
     /// Record a single [`SchedStatWait`] event.
     ///
-    /// Records `delay` in the `sched_stat_wait` gauge.  No shared or dedicated
-    /// counter is incremented, as requested.
+    /// Increments `events_total`, records `delay` in the `sched_stat_wait`
+    /// gauge, and observes `delay` in the `sched_stat_wait_distribution`
+    /// histogram.
     pub fn record_sched_stat_wait(&self, m: &SchedStatWait) {
         let comm = String::from_utf8_lossy(&m.command);
         let command = comm.trim_end_matches('\0').to_string();
@@ -247,13 +271,16 @@ impl Metrics {
             KeyValue::new("command", command),
         ];
 
+        self.events_total.add(1, attrs);
         self.sched_stat_wait.record(m.delay as i64, attrs);
+        self.sched_stat_wait_distribution.record(m.delay, attrs);
     }
 
     /// Record a single [`SchedStatRuntime`] event.
     ///
-    /// Records `runtime` in the `sched_stat_runtime` gauge.  No shared or
-    /// dedicated counter is incremented, as requested.
+    /// Increments `events_total`, records `runtime` in the `sched_stat_runtime`
+    /// gauge, and observes `runtime` in the `sched_stat_runtime_distribution`
+    /// histogram.
     pub fn record_sched_stat_runtime(&self, m: &SchedStatRuntime) {
         let comm = String::from_utf8_lossy(&m.command);
         let command = comm.trim_end_matches('\0').to_string();
@@ -262,7 +289,9 @@ impl Metrics {
             KeyValue::new("command", command),
         ];
 
+        self.events_total.add(1, attrs);
         self.sched_stat_runtime.record(m.runtime as i64, attrs);
+        self.sched_stat_runtime_distribution.record(m.runtime, attrs);
     }
 
     /// Record a single [`CpuIdle`] event.
@@ -272,6 +301,7 @@ impl Metrics {
     pub fn record_cpu_idle(&self, m: &CpuIdle) {
         let attrs = &[KeyValue::new("cpu_id", m.cpu_id as i64)];
 
+        self.events_total.add(1, attrs);
         self.cpu_idle_state.record(m.state as i64, attrs);
     }
 }