A UPS in the map: read over NUT or SNMP, alerts, shutdown order

New UPS integration (NUT or SNMP v2c, read only). Monitoring -> UPS shows charge,
runtime, load and mains voltage with history and the times mains power was lost.
Mains lost and a nearly empty battery are critical alerts; battery to be replaced
and a heavy load are warnings. The UPS is a node in the dependency map and counts
as down while on battery, so servers that go offline with it are folded under its
alert; the page lists what is on it in the order to shut it down. /metrics series
and docs added.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 21:47:31 +02:00
1 parent 3cb3e4988f
commit 232a5661ab
38 files changed
+8049 -16

No files matched your search

+2
View File
@@ -28,6 +28,7 @@ const TYPE_LABELS: Record<IntegrationType, string> = {
unifi: "UniFi",
npm: "Nginx Proxy Manager",
homeassistant: "Home Assistant",
ups: "UPS",
};
/** The page each kind of integration gets once it is connected. */
@@ -45,6 +46,7 @@ const TYPE_PAGES: Record<IntegrationType, string> = {
unifi: "/network/devices",
npm: "/proxy-hosts",
homeassistant: "/home-assistant",
ups: "/ups",
};
/** "pve.example.lan" out of "https://pve.example.lan:8006/", or the text itself when it isn't an address. */
+265
View File
@@ -0,0 +1,265 @@
import { useEffect, useMemo, useState } from "react";
import { Link } from "react-router-dom";
import { api, type CurrentUser, type UpsHistory, type UpsInfo } from "../api/client";
import EmptyState from "../components/EmptyState";
import RangeSelect from "../components/RangeSelect";
import TimeAgo from "../components/TimeAgo";
import TimeChart from "../components/TimeChart";
import { BlockSkeleton } from "../components/Skeleton";
import { ErrorNotice } from "../components/Notice";
import { useChartRange } from "../utils/chartRanges";
import { readableError } from "../utils/errors";
const minutes = (seconds: number) => {
const m = Math.max(0, Math.round(seconds / 60));
return m < 120 ? `${m} min` : `${Math.round(m / 60)} h`;
};
const lasting = (fromIso: string, toIso: string) => minutes((Date.parse(toIso) - Date.parse(fromIso)) / 1000);
function Badge({ u }: { u: UpsInfo }) {
const s = u.state;
if (!s) return <span className="badge bg-secondary-lt text-secondary">Not read yet</span>;
if (!u.fresh) return <span className="badge bg-yellow-lt text-yellow">Can&rsquo;t be read</span>;
if (s.onBattery && s.lowBattery) return <span className="badge bg-red text-white">On battery — nearly empty</span>;
if (s.onBattery) return <span className="badge bg-red-lt text-red">On battery</span>;
if (s.lowBattery) return <span className="badge bg-red-lt text-red">Battery low</span>;
return <span className="badge bg-green-lt text-green">On mains power</span>;
}
function Tile({ label, value, sub, bar }: { label: string; value: string; sub?: string; bar?: { percent: number; color: string } }) {
return (
<div className="col-6 col-lg-3">
<div className="card card-sm h-100">
<div className="card-body">
<div className="text-secondary small">{label}</div>
<div className="h2 mb-0">{value}</div>
{bar && (
<div className="progress progress-sm mt-1" aria-hidden="true">
<div className="progress-bar" style={{ width: `${Math.max(0, Math.min(100, bar.percent))}%`, background: bar.color }} />
</div>
)}
{sub && <div className="text-secondary small">{sub}</div>}
</div>
</div>
</div>
);
}
const linkOf = (c: UpsInfo["carries"][number]) => (c.type === "server" ? `/servers/${c.id}` : c.type === "device" ? "/network/devices" : "/integrations");
/** Charge, load and mains voltage over time, from what is kept (up to 35 days), with the times mains power was lost. */
function History({ id, name }: { id: number; name: string }) {
const [days, setDays] = useChartRange(7);
const shown = Math.min(days, 30);
const [history, setHistory] = useState<UpsHistory | null>(null);
const [error, setError] = useState<string | null>(null);
const [to, setTo] = useState(() => Date.now());
useEffect(() => {
let alive = true;
api.ups
.history(id, shown)
.then((res) => {
if (!alive) return;
setHistory(res);
setTo(Date.now());
setError(null);
})
.catch((err) => alive && setError(readableError(err)));
return () => {
alive = false;
};
}, [id, shown]);
const from = to - shown * 86_400_000;
const series = (key: "charge" | "loadPercent" | "inputVoltage", label: string, color: string) => [{ name: label, color, points: (history?.points ?? []).flatMap((p) => (p[key] === null ? [] : [{ t: p.t, v: p[key] as number }])) }];
const charge = useMemo(() => series("charge", "Battery charge", "#2fb344"), [history]);
const load = useMemo(() => series("loadPercent", "Load", "#4299e1"), [history]);
const volts = useMemo(() => series("inputVoltage", "Mains voltage", "#ae3ec9"), [history]);
const hasVolts = volts[0].points.length > 0;
return (
<div>
<div className="d-flex align-items-center mb-2">
<h4 className="mb-0">History</h4>
<div className="ms-auto">
<RangeSelect value={shown} onChange={setDays} only={[1, 7, 30]} />
</div>
</div>
<ErrorNotice error={error} />
{!history && !error && <BlockSkeleton lines={4} />}
{history && (
<>
<div className="text-secondary small mb-1">Battery charge</div>
<div className="mb-3">
<TimeChart series={charge} from={from} to={to} unit="%" compact label={`${name}: battery charge`} empty="Nothing read in this stretch yet." />
</div>
<div className="text-secondary small mb-1">Load</div>
<div className="mb-3">
<TimeChart series={load} from={from} to={to} unit="%" compact label={`${name}: load`} empty="This UPS doesn't say how loaded it is." />
</div>
{hasVolts && (
<>
<div className="text-secondary small mb-1">Mains voltage (V)</div>
<div className="mb-3">
<TimeChart series={volts} from={from} to={to} unit="value" compact label={`${name}: mains voltage`} empty="" format={(v) => `${Math.round(v)} V`} />
</div>
</>
)}
<div className="text-secondary small mb-1">Mains power lost</div>
{history.onBatteryPeriods.length === 0 ? (
<div className="text-secondary">Not at all in the last {shown === 1 ? "24 hours" : `${shown} days`}.</div>
) : (
<ul className="mb-0">
{[...history.onBatteryPeriods].reverse().map((p) => (
<li key={p.from}>
<TimeAgo value={p.from} /> — {p.ongoing ? `still on battery (${lasting(p.from, new Date().toISOString())} so far)` : `for ${lasting(p.from, p.to)}`}
</li>
))}
</ul>
)}
</>
)}
</div>
);
}
function UpsCard({ u }: { u: UpsInfo }) {
const s = u.state;
const chargeColor = s?.charge == null ? "#9aa0a6" : s.charge < 20 ? "#e05252" : s.charge < 50 ? "#f59f00" : "#2fb344";
const steps = new Map<number, UpsInfo["carries"]>();
for (const c of u.carries) steps.set(c.step, [...(steps.get(c.step) ?? []), c]);
return (
<div className="card mb-3">
<div className="card-header">
<div>
<h3 className="card-title mb-0">
{u.name} <Badge u={u} />
</h3>
{s && (s.model || s.manufacturer) && <div className="text-secondary small">{[s.manufacturer, s.model].filter(Boolean).join(" ")} · read over {u.protocol === "snmp" ? "SNMP" : "NUT"}</div>}
</div>
{!u.enabled && <span className="badge bg-secondary-lt text-secondary ms-auto">Switched off</span>}
</div>
<div className="card-body">
{u.status && !u.status.ok && (
<div className="alert alert-warning" role="status">
<div>
Couldn&rsquo;t be read: {u.status.error}.{s ? <> What is shown is from <TimeAgo value={s.updatedAt} />.</> : null}
</div>
</div>
)}
{u.problems.length > 0 && (
<div className="alert alert-danger" role="alert">
<div>
{u.problems.map((p) => (
<div key={p.key}>{p.message}</div>
))}
</div>
</div>
)}
{s ? (
<div className="row row-cards mb-3">
<Tile label="Battery" value={s.charge === null ? "—" : `${Math.round(s.charge)} %`} bar={s.charge === null ? undefined : { percent: s.charge, color: chargeColor }} sub={s.onBattery ? "running on it now" : s.statusText} />
<Tile label={s.onBattery ? "Left on battery" : "Would last"} value={s.runtimeSeconds === null ? "—" : minutes(s.runtimeSeconds)} sub="at the present load" />
<Tile label="Load" value={s.loadPercent === null ? "—" : `${Math.round(s.loadPercent)} %`} bar={s.loadPercent === null ? undefined : { percent: s.loadPercent, color: s.loadPercent >= 90 ? "#e05252" : "#4299e1" }} sub="of what it can carry" />
<Tile label="Mains in" value={s.inputVoltage === null ? "—" : `${Math.round(s.inputVoltage)} V`} sub={s.outputVoltage === null ? undefined : `${Math.round(s.outputVoltage)} V out`} />
</div>
) : (
!u.status && <div className="text-secondary mb-3">Not read yet — the first read happens within a minute of adding it.</div>
)}
<div className="row g-4">
<div className="col-lg-7">
<History id={u.id} name={u.name} />
</div>
<div className="col-lg-5">
<h4>On this UPS</h4>
{u.carries.length === 0 ? (
<EmptyState
title="Nothing is recorded as needing it"
hint={
<>
Say which servers it powers in the <Link to={`/map?view=dependencies&select=integration:${u.id}`}>dependency map</Link>, and they are listed here in the order to shut them down, and folded under this UPS&rsquo;s alert if they go offline with it.
</>
}
/>
) : (
<>
<div className="text-secondary small mb-2">In the order to shut them down — nothing is switched off while something that needs it is still running.</div>
<ol className="list-group list-group-flush mb-2" style={{ listStyle: "none", paddingLeft: 0 }}>
{[...steps.entries()].map(([step, items]) => (
<li key={step} className="list-group-item px-0 d-flex gap-3">
<span className="badge bg-blue-lt text-blue align-self-start" style={{ minWidth: 28 }} title={step === 1 ? "Shut down first" : `Shut down after step ${step - 1}`}>
{step}
</span>
<div className="d-flex flex-wrap gap-2">
{items.map((c) => (
<Link key={c.key} to={linkOf(c)}>
{c.name}
</Link>
))}
</div>
</li>
))}
</ol>
{u.orderLooped && <div className="text-secondary small">Some of these need each other, so their order here is only a guess.</div>}
<div className="text-secondary small">
While this UPS runs on battery it counts as down in the dependency map: servers that go offline with it are folded under its alert instead of each being announced.
</div>
</>
)}
</div>
</div>
</div>
</div>
);
}
/** Each UPS the app reads (over NUT or SNMP): how it is, what is wrong, how long it would last, and what is on it in the order to shut it down. */
export default function Ups({ user }: { user: CurrentUser }) {
const [list, setList] = useState<UpsInfo[] | null>(null);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
const load = () =>
api.ups
.list()
.then((r) => {
setList(r.ups);
setError(null);
})
.catch((err) => setError(readableError(err)));
load();
const t = setInterval(load, 30_000);
return () => clearInterval(t);
}, []);
return (
<>
<h2 className="page-title mb-1">UPS</h2>
<p className="text-secondary">
The battery backups the app reads (over NUT or SNMP): whether mains power is there, how much battery is left and for how long, and what each one carries. Mains power lost is a critical alert and a notification; while it lasts, what
goes offline with the UPS is folded under it.
</p>
<ErrorNotice error={error} />
{list === null && !error && <BlockSkeleton lines={4} />}
{list?.length === 0 && (
<div className="card">
<div className="card-body">
<EmptyState
title="No UPS is connected"
hint={
<>
Add an integration of type <strong>UPS</strong>: the address of the machine running NUT (<code>upsd</code>), or of the UPS&rsquo;s network card for SNMP. The app only reads it.
</>
}
action={user.role === "admin" ? { label: "Add an integration", to: "/integrations" } : undefined}
/>
</div>
</div>
)}
{list?.map((u) => <UpsCard key={u.id} u={u} />)}
</>
);
}
+1
View File
@@ -26,6 +26,7 @@ const INTEGRATION_NAMES: Record<string, string> = {
unifi: "UniFi",
npm: "Nginx Proxy Manager",
homeassistant: "Home Assistant",
ups: "UPS",
};
function ColorList({