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