telemetry.rs
telemetry.rs
//! `GET /api/telemetry`:這台伺服器的幾個即時數字(設備頁 HOME SERVER 那張圖紙的遙測)。
//!
//! 刻意只給不會被拿來利用的數字:CPU 溫度、負載、記憶體用量、APU 整顆的功耗,都取整。
//! **不給運作時間**(看得出多久沒重開、核心多久沒更新)、容器、服務、版本、IP、主機名。
//! 讀的是 `/sys/class/hwmon` 與 `/proc`(容器裡看到的就是主機的),回應由路由層快取 30 秒,
//! 所以不管多少人在看,最多每 30 秒才真的去讀一次。
use std::fs;
use std::path::{Path, PathBuf};
use axum::Json;
use serde::Serialize;
/// `GET /api/telemetry` 的回應。每個欄位讀不到就是 null(例如換了機器、沒有那顆感測器)
#[derive(Debug, Default, PartialEq, Eq, Serialize, specta::Type, utoipa::ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct Telemetry {
/// CPU 溫度(°C):k10temp 的 Tctl
pub cpu_temp: Option<u32>,
/// 一分鐘平均負載除以邏輯核心數(百分比,可能超過 100)
pub load: Option<u32>,
/// 記憶體用了幾成(百分比):(總量 − 可用) / 總量
pub memory: Option<u32>,
/// APU 整顆的功耗(W):amdgpu 的 power1_input(APU 回報的是整顆封裝)
pub power: Option<u32>,
}
/// 找名字是 `name` 的那個 hwmon 目錄(hwmon 的編號開機時才決定,不能寫死)
fn hwmon_named(root: &Path, name: &str) -> Option<PathBuf> {
fs::read_dir(root)
.ok()?
.flatten()
.map(|e| e.path())
.find(|p| fs::read_to_string(p.join("name")).is_ok_and(|n| n.trim() == name))
}
fn read_u64(path: &Path) -> Option<u64> {
fs::read_to_string(path).ok()?.trim().parse().ok()
}
/// 千分之一的單位(毫攝氏度)四捨五入成整數
fn round_thousandths(v: u64) -> u32 {
u32::try_from((v + 500) / 1000).unwrap_or(u32::MAX)
}
/// `/proc/loadavg` 的第一個數字(一分鐘平均)
fn parse_loadavg(s: &str) -> Option<f64> {
s.split_whitespace().next()?.parse().ok()
}
/// `/proc/cpuinfo` 裡有幾個邏輯核心(容器的 cgroup 限制不影響主機的負載,所以照主機的算)
fn parse_cpu_count(s: &str) -> usize {
s.lines().filter(|l| l.starts_with("processor")).count()
}
/// `/proc/meminfo` → 用了幾成
fn parse_memory(s: &str) -> Option<u32> {
let field = |key: &str| -> Option<u64> {
let line = s.lines().find(|l| l.starts_with(key))?;
line.split_whitespace().nth(1)?.parse().ok()
};
let total = field("MemTotal:")?;
let available = field("MemAvailable:")?;
if total == 0 {
return None;
}
let used = total.saturating_sub(available);
u32::try_from((used * 100 + total / 2) / total).ok()
}
/// 負載換成百分比:一分鐘平均負載 / 核心數
fn load_percent(load: f64, cpus: usize) -> Option<u32> {
if cpus == 0 || !load.is_finite() || load < 0.0 {
return None;
}
#[allow(
clippy::cast_possible_truncation,
clippy::cast_sign_loss,
clippy::cast_precision_loss,
reason = "負載已確認是非負的有限數,核心數只有幾十,乘 100 再四捨五入遠小於 u32 上限"
)]
let pct = (load / cpus as f64 * 100.0).round() as u32;
Some(pct)
}
/// 讀一次。`hwmon` 與 `proc` 是根目錄(測試時換成假的目錄)
pub fn read(hwmon: &Path, proc_root: &Path) -> Telemetry {
let cpu_temp =
hwmon_named(hwmon, "k10temp").and_then(|d| read_u64(&d.join("temp1_input"))).map(round_thousandths);
let power = hwmon_named(hwmon, "amdgpu").and_then(|d| {
read_u64(&d.join("power1_input"))
.or_else(|| read_u64(&d.join("power1_average")))
// 微瓦 → 瓦
.map(|uw| round_thousandths(uw / 1000))
});
let cpus = fs::read_to_string(proc_root.join("cpuinfo")).map_or(0, |s| parse_cpu_count(&s));
let load = fs::read_to_string(proc_root.join("loadavg"))
.ok()
.and_then(|s| parse_loadavg(&s))
.and_then(|l| load_percent(l, cpus));
let memory = fs::read_to_string(proc_root.join("meminfo")).ok().and_then(|s| parse_memory(&s));
Telemetry { cpu_temp, load, memory, power }
}
/// `GET /api/telemetry`
#[utoipa::path(get, path = "/api/telemetry", tag = "home",
responses((status = 200, description = "伺服器的幾個即時數字(溫度、負載、記憶體、功耗),快取 30 秒", body = Telemetry)))]
pub async fn telemetry() -> Json<Telemetry> {
Json(read(Path::new("/sys/class/hwmon"), Path::new("/proc")))
}
#[cfg(test)]
mod tests {
use super::*;
/// 假的 /sys/class/hwmon 與 /proc:每個測試一個獨立的暫存目錄
fn fixture(tag: &str) -> PathBuf {
let root = std::env::temp_dir().join(format!("telemetry-{tag}-{}", std::process::id()));
let _ = fs::remove_dir_all(&root);
fs::create_dir_all(root.join("hwmon/hwmon0")).unwrap();
fs::create_dir_all(root.join("hwmon/hwmon3")).unwrap();
fs::create_dir_all(root.join("hwmon/hwmon6")).unwrap();
fs::create_dir_all(root.join("proc")).unwrap();
fs::write(root.join("hwmon/hwmon0/name"), "nvme\n").unwrap();
fs::write(root.join("hwmon/hwmon3/name"), "k10temp\n").unwrap();
fs::write(root.join("hwmon/hwmon3/temp1_input"), "81625\n").unwrap();
fs::write(root.join("hwmon/hwmon6/name"), "amdgpu\n").unwrap();
fs::write(root.join("hwmon/hwmon6/power1_input"), "42500000\n").unwrap();
fs::write(root.join("proc/loadavg"), "5.10 4.07 4.22 6/48021 32181\n").unwrap();
fs::write(root.join("proc/cpuinfo"), "processor\t: 0\nfoo\nprocessor\t: 1\n").unwrap();
fs::write(
root.join("proc/meminfo"),
"MemTotal: 1000 kB\nMemFree: 100 kB\nMemAvailable: 250 kB\n",
)
.unwrap();
root
}
#[test]
fn reads_every_field_from_the_real_layout() {
let root = fixture("all");
let t = read(&root.join("hwmon"), &root.join("proc"));
assert_eq!(t, Telemetry { cpu_temp: Some(82), load: Some(255), memory: Some(75), power: Some(43) });
let _ = fs::remove_dir_all(root);
}
#[test]
fn missing_sensors_are_null_not_errors() {
let root = fixture("missing");
fs::remove_dir_all(root.join("hwmon/hwmon3")).unwrap();
fs::remove_file(root.join("hwmon/hwmon6/power1_input")).unwrap();
fs::write(root.join("hwmon/hwmon6/power1_average"), "9400000").unwrap();
fs::remove_file(root.join("proc/cpuinfo")).unwrap();
let t = read(&root.join("hwmon"), &root.join("proc"));
assert_eq!(t.cpu_temp, None);
// power1_input 不在就退回 power1_average
assert_eq!(t.power, Some(9));
// 不知道有幾顆核心就不算負載
assert_eq!(t.load, None);
assert_eq!(t.memory, Some(75));
let _ = fs::remove_dir_all(root);
}
#[test]
fn nothing_readable_gives_all_nulls() {
let t = read(Path::new("/nonexistent/hwmon"), Path::new("/nonexistent/proc"));
assert_eq!(t, Telemetry::default());
}
#[test]
fn parsers_reject_garbage() {
assert_eq!(parse_loadavg(""), None);
assert_eq!(parse_loadavg("x 1 2"), None);
assert_eq!(parse_memory("MemTotal: 0 kB\nMemAvailable: 0 kB"), None);
assert_eq!(parse_memory("MemFree: 1 kB"), None);
assert_eq!(load_percent(1.0, 0), None);
assert_eq!(load_percent(f64::NAN, 4), None);
assert_eq!(load_percent(-1.0, 4), None);
assert_eq!(load_percent(2.0, 4), Some(50));
assert_eq!(round_thousandths(499), 0);
assert_eq!(round_thousandths(500), 1);
}
}