From 330cc30ffe5bd8f886e830082ce5aa6f92b37161 Mon Sep 17 00:00:00 2001 From: Eugene Volen Date: Tue, 10 Nov 2026 13:08:56 +0200 Subject: [PATCH] feat(dash): one node-efficiency implementation, with a held flag, shared by every surface (ROCMAI-62 follow-up, ROCMAI-938) node_efficiency lived in the TUI crate, so the daemon and the assistant could not use it, and the surfaces disagreed: Observe marked a held figure with `*` while the Hardware tab never did. Move it to rocm-dash-core::efficiency. It returns the tokens-per-watt figure and whether any throughput behind it is held. The value is still reported when held, because held throughput expires within the validity window and blanking it would make the figure blink out on a single missed scrape; the flag lets each surface mark it. Observe, the trend sparkline and the Hardware header use the shared function, and the Hardware header now shows the same `*`. The assistant's tokens_per_watt tool returns a `node` object with the figure and its freshness, or null when it cannot be stated. Power in the denominator is whole-board power, including GPUs no instance occupies, because this is the node's efficiency; per-instance figures keep using attributed power. Signed-off-by: Eugene Volen --- crates/rocm-dash-core/src/efficiency.rs | 236 ++++++++++++++++++- crates/rocm-dash-tui/src/agent/snapshot.rs | 116 ++++++++- crates/rocm-dash-tui/src/agent/tools.rs | 10 +- crates/rocm-dash-tui/src/ui/tabs/hardware.rs | 98 +++++++- crates/rocm-dash-tui/src/ui/tabs/observe.rs | 38 +-- crates/rocm-dash-tui/src/ui/widgets.rs | 83 +------ docs/architecture.md | 2 +- docs/manual-testing.md | 4 + 8 files changed, 463 insertions(+), 124 deletions(-) diff --git a/crates/rocm-dash-core/src/efficiency.rs b/crates/rocm-dash-core/src/efficiency.rs index 4083f82f0d..a946b0dee5 100644 --- a/crates/rocm-dash-core/src/efficiency.rs +++ b/crates/rocm-dash-core/src/efficiency.rs @@ -10,7 +10,7 @@ use std::collections::HashMap; use std::hash::BuildHasher; -use crate::metrics::{GpuMetrics, Instance}; +use crate::metrics::{GpuMetrics, Instance, ObservationFreshness, Snapshot}; /// Normalize a GPU identifier to a bare index for joining. /// @@ -103,6 +103,80 @@ pub fn attribute_power_w( .collect() } +/// Whole-node efficiency: aggregate generation throughput over aggregate power. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct NodeEfficiency { + /// Σ `gen_tps` ÷ Σ board `power_w`, in tokens per watt. + pub tokens_per_watt: f64, + /// Freshness of the throughput behind the figure (instances at zero tok/s + /// contribute nothing and are not counted): `Held` when any of it is + /// carried from a prior scrape window, `Fresh` when all of it is known to + /// be current, and `None` when some of it has no freshness metadata (a + /// legacy recording) and none is known to be held. Unknown is never + /// reported as fresh. The figure is still reported when held, so a + /// one-scrape hiccup does not blank it, but a consumer must mark it: a + /// held value expires within the observation validity window. + pub freshness: Option, +} + +impl NodeEfficiency { + /// Whether any throughput behind the figure is held. + #[must_use] + pub fn held(&self) -> bool { + self.freshness == Some(ObservationFreshness::Held) + } +} + +/// Node-level efficiency for a snapshot, or `None` when it cannot be stated. +/// +/// Throughput is summed over instances with a finite `gen_tps` (a single +/// NaN/Inf must not poison the node), power over every GPU's board power. It is +/// `None` with no traffic (`Σ gen_tps == 0`), no power telemetry +/// (`Σ power_w == 0`), or a non-finite quotient. Power here is the whole board, +/// including GPUs no instance occupies, because the question is the node's +/// efficiency, not an instance's: per-instance figures use attributed power +/// ([`attribute_power_w`]) instead. +#[must_use] +pub fn node_efficiency(snap: &Snapshot) -> Option { + let mut tps = 0.0_f64; + let mut held = false; + let mut unknown = false; + for inst in &snap.instances { + let Some(v) = inst.gen_tps.filter(|v| v.is_finite()) else { + continue; + }; + tps += v; + // An instance at zero tok/s adds nothing to the figure, so its + // freshness says nothing about the figure's either: a held idle + // instance must not mark a figure that comes from fresh ones as held. + if v <= 0.0 { + continue; + } + match inst.gen_tps_observation.as_ref().map(|m| m.freshness) { + Some(ObservationFreshness::Held) => held = true, + Some(ObservationFreshness::Fresh) => {} + None => unknown = true, + } + } + let freshness = if held { + Some(ObservationFreshness::Held) + } else if unknown { + None + } else { + Some(ObservationFreshness::Fresh) + }; + let power: f64 = snap.gpus.iter().map(|g| f64::from(g.power_w)).sum(); + if tps > 0.0 && power > 0.0 { + let tokens_per_watt = tps / power; + tokens_per_watt.is_finite().then_some(NodeEfficiency { + tokens_per_watt, + freshness, + }) + } else { + None + } +} + /// Tokens-per-watt for one serving instance: generation throughput (tok/s) /// divided by the power (W) attributed to it by [`attribute_power_w`]. /// @@ -135,6 +209,166 @@ mod tests { assert_eq!(normalize_gpu_id("3"), "3"); } + fn snap_with(instances: Vec, gpus: Vec) -> Snapshot { + Snapshot { + gpus, + instances, + ..Snapshot::default() + } + } + + fn serving( + id: &str, + gen_tps: Option, + freshness: Option, + ) -> Instance { + use crate::metrics::ObservationMetadata; + Instance { + container_id: id.into(), + gen_tps, + gen_tps_observation: freshness.map(|freshness| ObservationMetadata { + observed_at: chrono::Utc::now(), + freshness, + }), + ..Instance::default() + } + } + + #[test] + fn node_efficiency_divides_total_throughput_by_total_board_power() { + let snap = snap_with( + vec![ + serving("a", Some(300.0), None), + serving("b", Some(200.0), None), + ], + vec![gpu("gpu-0", 400.0), gpu("gpu-1", 600.0)], + ); + // (300 + 200) / (400 + 600) = 0.5 tok/W + let n = node_efficiency(&snap).expect("some"); + assert!((n.tokens_per_watt - 0.5).abs() < 1e-9, "got {n:?}"); + assert!(!n.held()); + } + + #[test] + fn node_efficiency_counts_power_of_gpus_no_instance_occupies() { + // The node pays for an idle GPU too, so it stays in the denominator. + let snap = snap_with( + vec![serving("a", Some(100.0), None)], + vec![gpu("gpu-0", 100.0), gpu("gpu-1", 300.0)], + ); + let n = node_efficiency(&snap).expect("some"); + assert!((n.tokens_per_watt - 0.25).abs() < 1e-9, "got {n:?}"); + } + + #[test] + fn node_efficiency_is_none_without_power_or_traffic() { + let no_power = snap_with( + vec![serving("a", Some(100.0), None)], + vec![gpu("gpu-0", 0.0)], + ); + assert_eq!(node_efficiency(&no_power), None); + let no_traffic = snap_with(vec![serving("a", None, None)], vec![gpu("gpu-0", 500.0)]); + assert_eq!(node_efficiency(&no_traffic), None); + let zero_traffic = snap_with( + vec![serving("a", Some(0.0), None)], + vec![gpu("gpu-0", 500.0)], + ); + assert_eq!(node_efficiency(&zero_traffic), None); + } + + #[test] + fn a_held_idle_instance_does_not_mark_a_figure_that_comes_from_fresh_ones() { + let gpus = vec![gpu("gpu-0", 500.0)]; + let snap = snap_with( + vec![ + serving("busy", Some(250.0), Some(ObservationFreshness::Fresh)), + serving("idle", Some(0.0), Some(ObservationFreshness::Held)), + ], + gpus.clone(), + ); + let n = node_efficiency(&snap).unwrap(); + assert!( + !n.held(), + "a zero-throughput held instance must not flag the node" + ); + assert_eq!(n.freshness, Some(ObservationFreshness::Fresh)); + // ...and one with unknown freshness at zero does not make it unknown. + let snap = snap_with( + vec![ + serving("busy", Some(250.0), Some(ObservationFreshness::Fresh)), + serving("idle", Some(0.0), None), + ], + gpus, + ); + assert_eq!( + node_efficiency(&snap).unwrap().freshness, + Some(ObservationFreshness::Fresh) + ); + } + + #[test] + fn node_efficiency_ignores_non_finite_gen_tps() { + // One NaN sample must not poison the sum for the whole node. + let snap = snap_with( + vec![ + serving("finite", Some(250.0), Some(ObservationFreshness::Held)), + serving("poisoned", Some(f64::NAN), Some(ObservationFreshness::Held)), + ], + vec![gpu("gpu-0", 500.0)], + ); + let n = node_efficiency(&snap).expect("finite gen_tps must still produce a result"); + assert!((n.tokens_per_watt - 0.5).abs() < 1e-9, "got {n:?}"); + } + + #[test] + fn node_efficiency_is_held_when_any_contributing_throughput_is_held() { + let gpus = vec![gpu("gpu-0", 500.0)]; + let fresh = snap_with( + vec![serving("a", Some(250.0), Some(ObservationFreshness::Fresh))], + gpus.clone(), + ); + let n = node_efficiency(&fresh).unwrap(); + assert!(!n.held()); + assert_eq!(n.freshness, Some(ObservationFreshness::Fresh)); + // Unknown freshness (legacy snapshot) is neither held nor claimed + // fresh: nothing measured it. + let unknown = snap_with(vec![serving("a", Some(250.0), None)], gpus.clone()); + let n = node_efficiency(&unknown).unwrap(); + assert!(!n.held()); + assert_eq!(n.freshness, None); + // One unknown among fresh ones keeps the whole figure unknown. + let partly = snap_with( + vec![ + serving("a", Some(250.0), Some(ObservationFreshness::Fresh)), + serving("b", Some(10.0), None), + ], + gpus.clone(), + ); + assert_eq!(node_efficiency(&partly).unwrap().freshness, None); + let mixed = snap_with( + vec![ + serving("a", Some(250.0), Some(ObservationFreshness::Fresh)), + serving("b", Some(100.0), Some(ObservationFreshness::Held)), + ], + gpus.clone(), + ); + assert!(node_efficiency(&mixed).unwrap().held()); + // A held instance whose throughput is non-finite does not contribute, + // so it cannot mark the node held. + let excluded = snap_with( + vec![ + serving("a", Some(250.0), Some(ObservationFreshness::Fresh)), + serving("b", Some(f64::INFINITY), Some(ObservationFreshness::Held)), + ], + gpus, + ); + assert!(!node_efficiency(&excluded).unwrap().held()); + assert_eq!( + node_efficiency(&excluded).unwrap().freshness, + Some(ObservationFreshness::Fresh) + ); + } + fn inst(id: &str, gpu_ids: &[&str]) -> Instance { Instance { container_id: id.into(), diff --git a/crates/rocm-dash-tui/src/agent/snapshot.rs b/crates/rocm-dash-tui/src/agent/snapshot.rs index 43ebe0d5b2..27d086774c 100644 --- a/crates/rocm-dash-tui/src/agent/snapshot.rs +++ b/crates/rocm-dash-tui/src/agent/snapshot.rs @@ -10,7 +10,7 @@ use serde_json::{Value, json}; -use rocm_dash_core::metrics::{GpuMetrics, ObservationFreshness, ObservationMetadata}; +use rocm_dash_core::metrics::{GpuMetrics, ObservationFreshness}; use super::StateSnapshot; @@ -43,11 +43,31 @@ pub fn gpu_status_json(snap: &StateSnapshot, gpu_index: Option) -> Value } } +/// The whole-node efficiency object shared by `list_instances` and +/// `tokens_per_watt`, or `null` when it cannot be stated. +/// +/// It is computed from `StateSnapshot::latest` (the daemon's last snapshot), the +/// same source the Hardware and Observe tabs read, so it matches those screens. +/// The per-instance entries come from `StateSnapshot::instances`, the +/// event-driven map the Instances tab reads, which can be a tick ahead of or +/// behind `latest`; the two are separate views, not one. +fn node_json(snap: &StateSnapshot) -> Value { + snap.latest + .as_ref() + .and_then(rocm_dash_core::efficiency::node_efficiency) + .map_or(Value::Null, |n| { + json!({ + "tokens_per_watt": n.tokens_per_watt, + "freshness": freshness_label(n.freshness), + }) + }) +} + /// `"fresh"` | `"held"` | `null` (unknown, e.g. a legacy snapshot). -fn freshness_label(obs: Option<&ObservationMetadata>) -> Value { - obs.map_or(Value::Null, |m| { +fn freshness_label(freshness: Option) -> Value { + freshness.map_or(Value::Null, |f| { Value::String( - match m.freshness { + match f { ObservationFreshness::Fresh => "fresh", ObservationFreshness::Held => "held", } @@ -100,22 +120,29 @@ pub fn list_instances_json(snap: &StateSnapshot) -> Value { "tokens_per_watt": i.tokens_per_watt, "attributed_power_w": i.power_w, "ttft_ms": i.ttft_ms, - "ttft_freshness": freshness_label(i.ttft_observation.as_ref()), + "ttft_freshness": freshness_label(i.ttft_observation.as_ref().map(|m| m.freshness)), "tpot_ms": i.tpot_ms, - "tpot_freshness": freshness_label(i.tpot_observation.as_ref()), + "tpot_freshness": freshness_label(i.tpot_observation.as_ref().map(|m| m.freshness)), "freshness": freshness, "observed_at": observed_at, }) }) .collect(); - json!({ "instances": arr, "instance_count": arr.len() }) + json!({ "instances": arr, "instance_count": arr.len(), "node": node_json(snap) }) } /// Per-instance tokens-per-watt from the daemon-provided field. /// -/// Uses `Instance::tokens_per_watt` directly so this tool matches the screen -/// truth exactly (the daemon computes the same value the TUI displays). Also -/// includes gen_tps, freshness, and observed_at for completeness. +/// Per-instance values come straight from `Instance::tokens_per_watt`, which +/// the daemon computes (never recomputed here), and include gen_tps, freshness +/// and observed_at. +/// +/// `node` is different: it is computed here, from the latest snapshot, by the +/// same function the Hardware and Observe tabs use (Σ tok/s over Σ board +/// power). Its `freshness` is `"fresh"`, `"held"`, or `null` when it is unknown +/// (no freshness metadata, e.g. an old recording), and `node` itself is `null` +/// when it cannot be stated (no traffic, zero measured traffic, or no power +/// telemetry), which is "no figure", not zero. pub fn tokens_per_watt_json(snap: &StateSnapshot) -> Value { let arr: Vec = snap .instances @@ -143,7 +170,7 @@ pub fn tokens_per_watt_json(snap: &StateSnapshot) -> Value { }) }) .collect(); - json!({ "instances": arr }) + json!({ "instances": arr, "node": node_json(snap) }) } /// Pass^N / Pass@N rollup over the cached bench rows, reusing the core rollup. @@ -232,6 +259,63 @@ mod tests { assert_eq!(v["instances"][0]["tokens_per_watt"], 2.0); } + #[test] + fn tokens_per_watt_json_reports_the_node_figure_with_freshness() { + use rocm_dash_core::metrics::{ObservationMetadata, Snapshot}; + let mut snap = fixture_snapshot(); + let mk = |freshness| Instance { + container_name: "a".into(), + gen_tps: Some(300.0), + gen_tps_observation: Some(ObservationMetadata { + observed_at: chrono::Utc::now(), + freshness, + }), + ..Default::default() + }; + let gpu = GpuMetrics { + device_id: "gpu-0".into(), + power_w: 600.0, + ..GpuMetrics::default() + }; + snap.latest = Some(Snapshot { + instances: vec![mk(ObservationFreshness::Held)], + gpus: vec![gpu.clone()], + ..Snapshot::default() + }); + let v = tokens_per_watt_json(&snap); + assert_eq!(v["node"]["tokens_per_watt"], 0.5); + assert_eq!(v["node"]["freshness"], "held"); + snap.latest = Some(Snapshot { + instances: vec![mk(ObservationFreshness::Fresh)], + gpus: vec![gpu], + ..Snapshot::default() + }); + assert_eq!(tokens_per_watt_json(&snap)["node"]["freshness"], "fresh"); + // Unknown freshness (an old recording) is null, never "fresh". + snap.latest = Some(Snapshot { + instances: vec![Instance { + container_name: "a".into(), + gen_tps: Some(300.0), + ..Default::default() + }], + gpus: vec![GpuMetrics { + device_id: "gpu-0".into(), + power_w: 600.0, + ..GpuMetrics::default() + }], + ..Snapshot::default() + }); + let v = tokens_per_watt_json(&snap); + assert_eq!(v["node"]["tokens_per_watt"], 0.5); + assert!( + v["node"]["freshness"].is_null(), + "freshness must not be fabricated" + ); + // Nothing to state: null, not zero. + snap.latest = Some(Snapshot::default()); + assert!(tokens_per_watt_json(&snap)["node"].is_null()); + } + #[test] fn bench_summary_json_rolls_up_groups() { let v = bench_summary_json(&fixture_snapshot()); @@ -293,6 +377,16 @@ mod tests { assert_eq!(i["attributed_power_w"], 123.0); } + #[test] + fn list_instances_json_carries_the_same_node_object() { + let snap = fixture_snapshot(); + assert_eq!( + list_instances_json(&snap)["node"], + tokens_per_watt_json(&snap)["node"], + "the two tools must report one node figure" + ); + } + #[test] fn gpu_status_json_reports_the_power_limit_or_null() { use rocm_dash_core::metrics::Snapshot; diff --git a/crates/rocm-dash-tui/src/agent/tools.rs b/crates/rocm-dash-tui/src/agent/tools.rs index 6e9e2f6ac9..0a6907278c 100644 --- a/crates/rocm-dash-tui/src/agent/tools.rs +++ b/crates/rocm-dash-tui/src/agent/tools.rs @@ -113,6 +113,7 @@ impl Tool for ListInstancesTool { name: Self::NAME.to_string(), description: "List discovered serving instances: name, model, status, \ KV-cache usage %, running/waiting request counts, \ + the whole-node `node` figure (see tokens_per_watt), \ generation tok/s, TTFT/TPOT (each with a fresh/held \ flag; held means the last value, not a live reading), \ and attributed_power_w (this instance's share of its \ @@ -171,7 +172,14 @@ impl Tool for TokensPerWattTool { name: Self::NAME.to_string(), description: "Per-instance efficiency: generation tokens/sec divided by \ the instance's attributed share of its GPUs' power (W). \ - GPUs shared by several instances are split between them." + GPUs shared by several instances are split between them. \ + Also returns `node`: whole-node tokens/sec over total \ + board power (whole-board, so it is not the sum of the \ + per-instance values), with freshness `fresh`, `held` \ + (carried from a prior scrape, expires within about \ + 30 s) or null when unknown. `node` is null, meaning \ + no figure and not zero, when there is no traffic or \ + no power telemetry." .to_string(), parameters: json!({ "type": "object", "properties": {} }), } diff --git a/crates/rocm-dash-tui/src/ui/tabs/hardware.rs b/crates/rocm-dash-tui/src/ui/tabs/hardware.rs index 2474b32437..c6f8f453cb 100644 --- a/crates/rocm-dash-tui/src/ui/tabs/hardware.rs +++ b/crates/rocm-dash-tui/src/ui/tabs/hardware.rs @@ -26,9 +26,7 @@ use crate::ui::gradient::GradientGauge; use crate::ui::panel::{self, BoxRole}; use crate::ui::sparkline::BrailleSparkline; use crate::ui::theme::Theme; -use crate::ui::widgets::{ - gpu_stats_line, instances_on_gpu, node_efficiency, power_style, temperature_style, trunc, -}; +use crate::ui::widgets::{gpu_stats_line, instances_on_gpu, power_style, temperature_style, trunc}; /// Height of the GPU-section summary header (partition + efficiency). const GPU_HEADER_H: u16 = 1; @@ -281,6 +279,24 @@ fn gpu_section_header(snap: &Snapshot, theme: &Theme) -> Line<'static> { .fg(theme.accent) .add_modifier(Modifier::BOLD), )]; + let eff = rocm_dash_core::efficiency::node_efficiency(snap); + // Spelled out rather than the `*` the tabs with a footer use: this header + // has no room for the legend, and a marker with nothing to define it is + // worse than none. It sits right after the GPU count, ahead of the + // partition and VRAM text, so a narrow terminal clips those and never the + // marker that says the figure is not live. + let held = if eff.is_some_and(|n| n.held()) { + " (held)" + } else { + "" + }; + spans.push(Span::styled( + format!( + " · eff {}{held}", + format::tokens_per_watt(eff.map(|n| n.tokens_per_watt)) + ), + Style::default().fg(if eff.is_some() { theme.ok } else { theme.muted }), + )); if let Some(si) = snap.gpu_system_info.as_ref() { spans.push(Span::styled( format!( @@ -301,11 +317,6 @@ fn gpu_section_header(snap: &Snapshot, theme: &Theme) -> Line<'static> { format!(" · {:.1} kW", total_power / 1000.0), Style::default().fg(theme.fg), )); - let eff = node_efficiency(snap); - spans.push(Span::styled( - format!(" · eff {}", format::tokens_per_watt(eff)), - Style::default().fg(if eff.is_some() { theme.ok } else { theme.muted }), - )); Line::from(spans) } @@ -601,7 +612,9 @@ mod tests { use crate::app::{ActiveTab, AppState}; use ratatui::Terminal; use ratatui::backend::TestBackend; - use rocm_dash_core::metrics::{GpuSystemInfo, SystemMetrics}; + use rocm_dash_core::metrics::{ + GpuSystemInfo, ObservationFreshness, ObservationMetadata, SystemMetrics, + }; use rocm_dash_core::partition::{ComputePartitionMode, MemoryPartitionMode}; /// Render `draw` to a TestBackend and return the buffer as a flat string. @@ -852,6 +865,73 @@ mod tests { assert!(text.contains("0.50 tok/W"), "missing efficiency: {text}"); } + fn header_text_with_freshness(freshness: Option) -> String { + let theme = Theme::default_dark(); + let mut inst = mk_instance("a", &["0"], Some(250.0)); + inst.gen_tps_observation = freshness.map(|freshness| ObservationMetadata { + observed_at: chrono::Utc::now(), + freshness, + }); + let snap = Snapshot { + gpus: vec![mk_gpu("gpu-0", 50.0, 65.0, 500.0)], + instances: vec![inst], + ..Default::default() + }; + gpu_section_header(&snap, &theme) + .spans + .iter() + .map(|s| s.content.as_ref()) + .collect() + } + + #[test] + fn gpu_section_header_marks_a_held_efficiency_and_only_then() { + // 250 tok/s over 500 W = 0.50 tok/W in every case. + let held = header_text_with_freshness(Some(ObservationFreshness::Held)); + assert!( + held.contains("0.50 tok/W (held)"), + "held must be marked: {held}" + ); + let fresh = header_text_with_freshness(Some(ObservationFreshness::Fresh)); + assert!(fresh.contains("0.50 tok/W"), "missing efficiency: {fresh}"); + assert!(!fresh.contains("held"), "fresh must not be marked: {fresh}"); + // Unknown freshness (a legacy snapshot) is never presented as held. + let legacy = header_text_with_freshness(None); + assert!( + legacy.contains("0.50 tok/W") && !legacy.contains("held"), + "{legacy}" + ); + } + + #[test] + fn a_held_efficiency_survives_an_80_column_terminal() { + // The full header with a partitioned system is wider than 80 columns, and + // a `Paragraph` clips its line at the right edge. The marker must not be + // the part that goes, or a held figure reads as live. + let theme = Theme::default_dark(); + let mut inst = mk_instance("a", &["0"], Some(250.0)); + inst.gen_tps_observation = Some(ObservationMetadata { + observed_at: chrono::Utc::now(), + freshness: ObservationFreshness::Held, + }); + let snap = Snapshot { + gpus: vec![mk_gpu("gpu-0", 50.0, 65.0, 500.0)], + gpu_system_info: Some(sysinfo_partitioned()), + instances: vec![inst], + ..Default::default() + }; + let mut term = Terminal::new(TestBackend::new(80, 1)).unwrap(); + term.draw(|f| f.render_widget(Paragraph::new(gpu_section_header(&snap, &theme)), f.area())) + .unwrap(); + let row: String = (0..80) + .map(|x| term.backend().buffer()[(x, 0)].symbol().to_string()) + .collect(); + assert!( + row.contains("0.50 tok/W (held)"), + "marker clipped at 80 columns: {row:?}" + ); + } + #[test] fn gpu_section_header_efficiency_dash_without_traffic() { let theme = Theme::default_dark(); diff --git a/crates/rocm-dash-tui/src/ui/tabs/observe.rs b/crates/rocm-dash-tui/src/ui/tabs/observe.rs index f200ef3b81..fa78e3a43e 100644 --- a/crates/rocm-dash-tui/src/ui/tabs/observe.rs +++ b/crates/rocm-dash-tui/src/ui/tabs/observe.rs @@ -24,9 +24,9 @@ use ratatui::text::{Line, Span}; use ratatui::widgets::Paragraph; use crate::app::{AppState, ConnState}; +use crate::ui::format; use crate::ui::panel::{self, BoxRole}; use crate::ui::theme::Theme; -use crate::ui::{format, widgets}; /// True when we have no live daemon telemetry to show — i.e. not connected to a /// running daemon, or connected but no snapshot has arrived yet. The @@ -67,7 +67,7 @@ pub fn draw(f: &mut Frame, area: Rect, state: &AppState, theme: &Theme) { } /// Two hero panels: Node efficiency (tok/watt + trend) and Node throughput -/// (Σ gen_tps + total power W). Reuses `widgets::node_efficiency` and the +/// (Σ gen_tps + total power W). Reuses `rocm_dash_core::efficiency::node_efficiency` and the /// braille sparkline; honest `—` when a metric is unavailable (color is never /// the only signal — every value carries a text label + unit). fn draw_hero_band(f: &mut Frame, area: Rect, state: &AppState, theme: &Theme) { @@ -93,22 +93,16 @@ fn draw_efficiency_hero(f: &mut Frame, area: Rect, state: &AppState, theme: &The if inner.height == 0 { return; } - // Track aggregate held: an instance contributes if it has a finite gen_tps - // AND its observation metadata says Held. Mirrors the finite-value filter - // `node_efficiency` applies below, so this can't mark the aggregate held - // over an instance that `node_efficiency` itself excludes as NaN/Inf. - // Any contributing Held → whole aggregate is held. - let any_held = state.latest.as_ref().is_some_and(|snap| { - snap.instances.iter().any(|i| { - i.gen_tps.is_some_and(f64::is_finite) - && i.gen_tps_observation.as_ref().is_some_and(|m| { - m.freshness == rocm_dash_core::metrics::ObservationFreshness::Held - }) - }) - }); - let eff = state.latest.as_ref().and_then(widgets::node_efficiency); + // One shared implementation: the value, and whether any throughput behind it + // is held, come from the same function the Hardware tab and the assistant use. + let node = state + .latest + .as_ref() + .and_then(rocm_dash_core::efficiency::node_efficiency); + let eff = node.map(|n| n.tokens_per_watt); + let any_held = node.is_some_and(|n| n.held()); let value_base = eff.map_or_else(|| "—".to_string(), |v| format!("{v:.2} tok/W")); - let value = if any_held && eff.is_some() { + let value = if any_held { format!("{value_base}{}", format::HELD_MARKER) } else { value_base @@ -118,8 +112,8 @@ fn draw_efficiency_hero(f: &mut Frame, area: Rect, state: &AppState, theme: &The let trend: Vec = state .history .iter() - .filter_map(widgets::node_efficiency) - .map(|v| (v * 1000.0).round().max(0.0) as u64) + .filter_map(rocm_dash_core::efficiency::node_efficiency) + .map(|n| (n.tokens_per_watt * 1000.0).round().max(0.0) as u64) .collect(); // Layout: value | sparkline (min) | label/legend. @@ -494,6 +488,12 @@ mod tests { out.contains(format::HELD_MARKER), "HELD_MARKER must appear in efficiency hero when any instance is held; got:\n{out}" ); + // The throughput hero prints a `*` too, so pin the efficiency one: the + // marker must sit right after the tok/W figure. + assert!( + out.contains(&format!("tok/W{}", format::HELD_MARKER)), + "efficiency figure must carry the held marker; got:\n{out}" + ); assert!( out.contains(format::HELD_LEGEND), "HELD_LEGEND must appear in a hero when held; got:\n{out}" diff --git a/crates/rocm-dash-tui/src/ui/widgets.rs b/crates/rocm-dash-tui/src/ui/widgets.rs index f429ecdbda..a014878715 100644 --- a/crates/rocm-dash-tui/src/ui/widgets.rs +++ b/crates/rocm-dash-tui/src/ui/widgets.rs @@ -7,7 +7,7 @@ use crossterm::event::KeyCode; use ratatui::style::Style; use ratatui::text::{Line, Span}; -use rocm_dash_core::metrics::{GpuMetrics, Instance, Snapshot}; +use rocm_dash_core::metrics::{GpuMetrics, Instance}; use crate::ui::theme::Theme; @@ -129,29 +129,6 @@ pub fn instances_on_gpu<'a>(device_id: &str, instances: &'a [Instance]) -> Vec<& .collect() } -/// Node-level energy efficiency: total generation throughput divided by total board power, in tokens per watt. -/// -/// `None` when there is no traffic -/// (`sum gen_tps == 0`) or no power telemetry (`sum power_w == 0`), or when the -/// result is non-finite. -pub fn node_efficiency(snap: &Snapshot) -> Option { - // A single NaN/Inf `gen_tps` sample must not poison the whole sum — - // same guard commit 0bf99ac added to `home.rs`'s hero aggregates. - let tps: f64 = snap - .instances - .iter() - .filter_map(|i| i.gen_tps) - .filter(|v| v.is_finite()) - .sum(); - let power: f64 = snap.gpus.iter().map(|g| f64::from(g.power_w)).sum(); - if tps > 0.0 && power > 0.0 { - let eff = tps / power; - eff.is_finite().then_some(eff) - } else { - None - } -} - /// One-line GPU stats: id, util, vram, temp, power. pub fn gpu_stats_line<'a>(g: &'a GpuMetrics, theme: &Theme) -> Line<'a> { let vram_pct = if g.vram_total_mb > 0 { @@ -203,14 +180,6 @@ mod tests { } } - fn gpu(device_id: &str, power_w: f32) -> GpuMetrics { - GpuMetrics { - device_id: device_id.into(), - power_w, - ..Default::default() - } - } - #[test] fn trunc_keeps_short_strings() { assert_eq!(trunc("abc", 5), "abc"); @@ -318,56 +287,6 @@ mod tests { assert!(instances_on_gpu("gpu-7", &[]).is_empty()); } - #[test] - fn node_efficiency_divides_tps_by_power() { - let snap = Snapshot { - gpus: vec![gpu("gpu-0", 400.0), gpu("gpu-1", 600.0)], - instances: vec![ - inst("a", &["0"], Some(300.0)), - inst("b", &["1"], Some(200.0)), - ], - ..Default::default() - }; - // (300 + 200) / (400 + 600) = 0.5 tok/W - let eff = node_efficiency(&snap).expect("some"); - assert!((eff - 0.5).abs() < 1e-9, "got {eff}"); - } - - #[test] - fn node_efficiency_none_without_power_or_traffic() { - // no power - let no_power = Snapshot { - gpus: vec![gpu("gpu-0", 0.0)], - instances: vec![inst("a", &["0"], Some(100.0))], - ..Default::default() - }; - assert_eq!(node_efficiency(&no_power), None); - // no traffic - let no_traffic = Snapshot { - gpus: vec![gpu("gpu-0", 500.0)], - instances: vec![inst("a", &["0"], None)], - ..Default::default() - }; - assert_eq!(node_efficiency(&no_traffic), None); - } - - #[test] - fn node_efficiency_ignores_non_finite_gen_tps() { - // A NaN sample from one instance must not poison the sum for the - // whole node — the same class of bug commit 0bf99ac fixed for - // `home.rs`'s hero aggregates. - let snap = Snapshot { - gpus: vec![gpu("gpu-0", 500.0)], - instances: vec![ - inst("finite", &["0"], Some(250.0)), - inst("poisoned", &["0"], Some(f64::NAN)), - ], - ..Default::default() - }; - let eff = node_efficiency(&snap).expect("finite gen_tps must still produce a result"); - assert!((eff - 0.5).abs() < 1e-9, "got {eff}"); - } - #[test] fn apply_char_key_appends_chars_in_order() { let mut buf = String::from("ab"); diff --git a/docs/architecture.md b/docs/architecture.md index 631735cb1e..88345f426d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -375,7 +375,7 @@ The other three dashboard crates each have a crate-level bullet, followed by a b - [`bench_rollup.rs`](../crates/rocm-dash-core/src/bench_rollup.rs) — Pass^N / Pass@N rollups: `rollup_pass_n` groups rows into trial sets keyed by `(cell, model, engine, tp, dtype, concurrency)` and returns one `PassNRollup` per group, sorted by that key, with a strict verdict (all N trials passed), a lenient one (at least one passed) and mean prompt and generation throughput; `row_verdict` falls back from `pass_fail` to the judge verdict when the rollup is `Unknown`. Because `engine` is in the key, rows with a blank `engine` do not group with rows that have one. It is pure, and the Bench tab ([`ui/tabs/bench.rs`](../crates/rocm-dash-tui/src/ui/tabs/bench.rs)) and the agent's telemetry helpers ([`agent/snapshot.rs`](../crates/rocm-dash-tui/src/agent/snapshot.rs)) recompute it from the rows rather than reading the CSV's `pass_n_of_n` and `pass_at_n` columns. - [`bench_schema.rs`](../crates/rocm-dash-core/src/bench_schema.rs) — `BenchmarkRow`, the one row type for a benchmark result (identity, platform, backend configuration, request statistics, throughput, latency, quality, rollup and provenance columns), and `PassFail`. Almost every field is an `Option` and the struct is `#[serde(default)]`, so a CSV or a recording that omits columns still deserializes. `CsvBenchTailer` deserializes CSV rows into it, `bench_load.rs` builds it, and the daemon forwards it in `Event::BenchmarkRowsAppended`. - [`config.rs`](../crates/rocm-dash-core/src/config.rs) — the standalone dashboard configuration read from `/rocm-dash/config.toml` (`default_config_path`; a missing file means defaults and `Config::load` fails only on a read or parse error): `Config` with `DaemonConfig` (listen address, token, tick intervals, benchmark CSV path), `TuiConfig` (connect address, theme, chat endpoint, model and auth-header name) and per-engine `EngineConfig`. It is separate from the unified `rocm` configuration (the `dashboard` section of `rocm-core`'s `RocmCliConfig`, which `rocm dash` reads); in the tree only the TUI's chat-endpoint save (`persist_chat_endpoint` in [`app/chat.rs`](../crates/rocm-dash-tui/src/app/chat.rs)) loads and writes this file. Its default socket path (`$XDG_RUNTIME_DIR`, then `~/.rocm/data/telemetry`, then a user-named directory under the temp dir) is a copy of `rocm-core`'s on purpose, because this crate may have no first-party dependencies (`cargo xtask check-crate-edges` enforces that). - - [`efficiency.rs`](../crates/rocm-dash-core/src/efficiency.rs) — the pure join of throughput and power. `normalize_gpu_id` strips the `gpu-` prefix so the bare indices Docker discovery records in `Instance.gpu_ids` match amd-smi's `gpu-N` device ids; `attribute_power_w` splits each GPU's board power among the instances that occupy it, weighted by per-container VRAM, equally when any occupant has no reading, and yields `None` for an instance none of whose GPUs reported a positive power reading; `tokens_per_watt` divides generation throughput by that attributed power. The daemon runner calls `attribute_power_w`, `tokens_per_watt` and `gpu_ids_overlap`, which it uses to warn when the id join finds nothing. + - [`efficiency.rs`](../crates/rocm-dash-core/src/efficiency.rs) — the pure join of throughput and power. `normalize_gpu_id` strips the `gpu-` prefix so the bare indices Docker discovery records in `Instance.gpu_ids` match amd-smi's `gpu-N` device ids; `attribute_power_w` splits each GPU's board power among the instances that occupy it, weighted by per-container VRAM, equally when any occupant has no reading, and yields `None` for an instance none of whose GPUs reported a positive power reading; `tokens_per_watt` divides generation throughput by that attributed power. `node_efficiency` returns the whole-node figure as a `NodeEfficiency` (Σ `gen_tps` over Σ board power, including GPUs no instance occupies) with a `held` flag that is set when any throughput behind it is held; it is the one implementation behind the Observe efficiency hero and its trend, the Hardware header, and the assistant's `tokens_per_watt` tool (the Home tab's tokens-per-watt figure is a separate sum of per-instance values). The daemon runner calls `attribute_power_w`, `tokens_per_watt` and `gpu_ids_overlap`, which it uses to warn when the id join finds nothing. - [`metrics.rs`](../crates/rocm-dash-core/src/metrics.rs) — the live metric types every other dashboard crate shares: `Snapshot` (one tick: `SystemMetrics`, a `GpuMetrics` per GPU, an optional `GpuSystemInfo`, the `Instance` list and warnings), `Instance` with its `InstanceStatus` (`Starting` carries an optional `StartupPhase`; `is_serving`, `is_starting`, `counts_as_running` and `label` are the one definition of those predicates and chip labels) and `ObservationMetadata`/`ObservationFreshness`, which mark a throughput or latency value as freshly measured or held over from an earlier scrape. The optional fields added after the first recordings (`power_limit_w`, `gen_tps`, `tokens_per_watt`, `power_w`, `ttft_ms`, `tpot_ms` and the three `*_observation` fields) are `#[serde(default)]`, so older recordings still deserialize. - [`observation.rs`](../crates/rocm-dash-core/src/observation.rs) — how a generation-throughput counter becomes a rate that stays honest. `GenerationObservationTracker` keeps a bounded window of counter samples, computes a rate over `rate_window(instance_tick)` (`clamp(5 x tick, 10 s, 30 s)`), reports the value as fresh or held for up to `observation_validity(instance_tick)` (`clamp(3 x tick, 6 s, 30 s)`), clears on a counter reset or on expiry, and accepts a rate an engine reports directly through `observe_direct`. All time is passed in, so the module reads no clock. The runner keeps one tracker per instance for throughput and one each for TTFT and TPOT; it drops them when a service is retired and calls `invalidate` when a service's port changes under the same id. - [`partition.rs`](../crates/rocm-dash-core/src/partition.rs) — the `ComputePartitionMode` (`Spx`, `Dpx`, `Qpx`, `Cpx`) and `MemoryPartitionMode` (`Nps1`, `Nps2`, `Nps4`) enums, each defaulting to `Unknown` and serialized in upper case. `GpuSystemInfo` in `metrics.rs` holds them and `amd_smi.rs` parses them from amd-smi output. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index e2976d09ce..e302008e37 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -954,6 +954,10 @@ Expected result: and disappear **together** as the terminal is resized. A `*` on a reading with no legend anywhere on screen is a bug; so is the legend with nothing marked. +- The Hardware tab's GPU header has no room for a legend, so it spells the + same condition out: `eff 0.50 tok/W (held)`. It sits right after the GPU + count, so on an 80-column terminal the partition and VRAM text clips before + it does. A held figure that shows no `(held)` there is a bug. Check this one by **starting tall and shrinking**, not at the 22-to-24 rows above. The legend is the first row the hero drops, and the marker is gated on