Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
import type { AggregatedMetricPoint, HistoryTimeRange, ResourceType } from '@/api/charts';
import { formatBytes } from '@/utils/format';
export interface HistoryChartProps {
resourceType: ResourceType;
resourceId: string;
metric: string;
height?: number;
color?: string;
label?: string;
unit?: string;
range?: HistoryTimeRange;
onRangeChange?: (range: HistoryTimeRange) => void;
hideSelector?: boolean;
compact?: boolean;
hideLock?: boolean;
data?: AggregatedMetricPoint[];
/**
* False pauses stored reads and polling while keeping the readings already
* shown, e.g. for a chart inside a drawer tab that is mounted but hidden.
*/
enabled?: boolean;
}
export interface HistoryChartHoverPoint {
value: number;
timestamp: number;
x: number;
y: number;
}
export interface HistoryChartTooltipLayout {
x: number;
y: number;
width: number;
height: number;
}
export const HISTORY_CHART_RANGES: HistoryTimeRange[] = [
'1h',
'6h',
'12h',
'24h',
'7d',
'14d',
'30d',
'90d',
];
export const HISTORY_CHART_MIN_LEFT_INSET = 40;
// The one label every history range picker shows for an option, so a drawer,
// a disk and a pool never name the same range three ways.
const HISTORY_RANGE_OPTION_LABELS: Record<HistoryTimeRange, string> = {
'30m': '30 minutes',
'1h': '1 hour',
'6h': '6 hours',
'12h': '12 hours',
'24h': '24 hours',
'7d': '7 days',
'14d': '14 days',
'30d': '30 days',
'90d': '90 days',
};
export const formatHistoryRangeOptionLabel = (range: HistoryTimeRange): string =>
HISTORY_RANGE_OPTION_LABELS[range] ?? range;
const HISTORY_CHART_RANGE_LABELS: Record<HistoryTimeRange, string> = {
'30m': '30-minute',
'1h': '1-hour',
'6h': '6-hour',
'12h': '12-hour',
'24h': '24-hour',
'7d': '7-day',
'14d': '14-day',
'30d': '30-day',
'90d': '90-day',
};
export interface HistoryChartAccessibleDescriptionInput {
data: AggregatedMetricPoint[];
error: string | null;
isLocked: boolean;
loading: boolean;
range: HistoryTimeRange;
unit?: string;
}
export function formatHistoryChartTooltipValue(value: number, unit?: string): string {
if (unit === '%' && value > 0 && value < 0.1) return '<0.1%';
if (unit === '%') return `${value.toFixed(1)}%`;
if (unit === 'B/s') return `${formatBytes(value)}/s`;
if (unit === 'C') return `${Math.round(value)}°C`;
if (!unit) return formatBytes(value);
return `${Number.isInteger(value) ? value : value.toFixed(1)} ${unit}`;
}
export function getHistoryChartAccessibleLabel(label?: string): string {
return `${label?.trim() || 'History'} chart`;
}
export function getHistoryChartAccessibleDescription({
data,
error,
isLocked,
loading,
range,
unit,
}: HistoryChartAccessibleDescriptionInput): string {
const rangeLabel = HISTORY_CHART_RANGE_LABELS[range] ?? `${range} history`;
if (loading) return `Loading ${rangeLabel} history data.`;
if (error) return `${rangeLabel} history data could not be loaded.`;
if (isLocked) return `${rangeLabel} history data is unavailable on the current plan.`;
if (data.length === 0) return `No ${rangeLabel} history data is available.`;
const first = data[0];
const latest = data[data.length - 1];
const minimum = getHistoryChartDataMin(data)!;
const maximum = getHistoryChartDataMax(data)!;
const formatTimestamp = (timestamp: number) => new Date(timestamp).toLocaleString();
const formatValue = (value: number) => formatHistoryChartTooltipValue(value, unit);
if (data.length === 1) {
return `${rangeLabel} history contains 1 data point at ${formatTimestamp(latest.timestamp)}: ${formatValue(latest.value)}.`;
}
const direction =
latest.value > first.value
? 'increased'
: latest.value < first.value
? 'decreased'
: 'remained unchanged';
const changeSummary =
direction === 'remained unchanged'
? `Values remained unchanged at ${formatValue(latest.value)}.`
: `Values ${direction} from ${formatValue(first.value)} to ${formatValue(latest.value)}.`;
return `${rangeLabel} history contains ${data.length} data points from ${formatTimestamp(first.timestamp)} to ${formatTimestamp(latest.timestamp)}. ${changeSummary} Minimum ${formatValue(minimum)}. Maximum ${formatValue(maximum)}.`;
}
export function getHistoryChartRefreshIntervalMs(range: HistoryTimeRange) {
switch (range) {
case '7d':
case '14d':
return 30000;
case '30d':
return 60000;
case '90d':
return 120000;
default:
return 10000;
}
}
export function getHistoryChartDefaultColor(metric: string, color?: string) {
if (color) return color;
if (metric === 'cpu') return '#8b5cf6';
if (metric === 'memory') return '#f59e0b';
if (metric === 'disk') return '#10b981';
return '#3b82f6';
}
export function getHistoryChartDataMin(points: AggregatedMetricPoint[]) {
if (points.length === 0) return null;
let min = Infinity;
for (const point of points) {
const value = point.min != null ? point.min : point.value;
if (value < min) min = value;
}
return min;
}
export function getHistoryChartDataMax(points: AggregatedMetricPoint[]) {
if (points.length === 0) return null;
let max = -Infinity;
for (const point of points) {
const value = point.max != null ? point.max : point.value;
if (value > max) max = value;
}
return max;
}
export type HistorySource = 'store' | 'memory' | 'live' | 'mock_synthetic';
/**
* Names where a History reply's readings came from. `store` is the history
* store; `memory` means the store had nothing for the range, so the readings
* are the recent ones Pulse holds in memory; `live` is one current reading
* because no history exists yet. Demo data reads like stored history.
*/
export function getHistoryReadoutLabel(
source: HistorySource | null | undefined,
inspected: boolean,
): string {
if (source === 'live') return 'Current';
if (source === 'memory') return inspected ? 'Recorded' : 'Latest recorded';
return inspected ? 'Stored' : 'Latest stored';
}
/** A short badge and its explanation for a reply that is not stored history. */
export function getHistorySourceNotice(
source: HistorySource | null | undefined,
): { badge: string; detail: string } | null {
if (source === 'memory') {
return {
badge: 'Recent only',
detail: 'Recent readings only. The history store has none for this range yet.',
};
}
if (source === 'live') {
return {
badge: 'Current only',
detail: 'No history for this range yet. Showing the current reading.',
};
}
return null;
}
/** True when any stored bucket's lowest and highest readings differ. */
export function hasHistoryChartSpread(points: readonly AggregatedMetricPoint[]): boolean {
return (
points.length > 1 &&
points.some((point) => (point.max ?? point.value) > (point.min ?? point.value))
);
}
export function getHistoryChartScale(points: AggregatedMetricPoint[], unit?: string) {
const minValue = 0;
const isPercentLike = unit === '%';
const isByteLike = !unit || unit === 'B/s';
let maxValue = 100;
if (points.length > 0) {
const rawMax = Math.max(...points.map((point) => point.max || point.value));
maxValue = isPercentLike ? Math.max(100, rawMax) : Math.max(1, rawMax * 1.15);
}
return {
isPercentLike,
isByteLike,
minValue,
maxValue,
};
}
export function getHistoryChartYAxisLabels(
{
minValue,
maxValue,
isPercentLike,
isByteLike,
}: {
minValue: number;
maxValue: number;
isPercentLike: boolean;
isByteLike: boolean;
},
unit?: string,
) {
const ticks = [0, 0.5, 1].map((pct) => {
const scaleValue = minValue + pct * (maxValue - minValue);
let label: string;
if (isPercentLike) {
label = `${Math.round(scaleValue)}%`;
} else if (isByteLike) {
label = formatHistoryChartTooltipValue(scaleValue, unit);
} else {
label = `${Math.round(scaleValue)}`;
}
return { pct, label };
});
const labels = withoutRepeatedHistoryAxisLabels(ticks.map((tick) => tick.label));
return ticks.map((tick, index) => ({ ...tick, label: labels[index] }));
}
/**
* Gridline labels in axis order. A middle label that reads the same as a
* neighbour (a small range rounded, or "<1K/s" twice on a quiet link) says
* nothing and crowds the axis, so it is left blank; the gridline stays. The
* end labels always remain.
*/
export function withoutRepeatedHistoryAxisLabels(labels: string[]): string[] {
return labels.map((label, index) =>
index > 0 &&
index < labels.length - 1 &&
(label === labels[index - 1] || label === labels[index + 1])
? ''
: label,
);
}
/**
* Time ticks left to right without one that reads the same as the tick
* before it: a short window at a coarse label ("Oct 2" four times, or
* "11:00 AM" twice) states its time once.
*/
export function withoutRepeatedHistoryTimeTicks<T extends { label: string }>(
ticks: readonly T[],
): T[] {
return ticks.filter((tick, index) => index === 0 || tick.label !== ticks[index - 1].label);
}
const HISTORY_CHART_TIME_LABEL_GAP = 12;
/**
* How many evenly spaced time labels fit along a plot of `plotWidth` pixels
* when the widest label is `labelWidth` pixels, from `maxCount` down to the
* first and last time. Labels are centred on their times, so neighbours need
* a label's width plus a gap between their centres.
*/
export function getHistoryChartTimeTickCount(
plotWidth: number,
labelWidth: number,
maxCount = 4,
): number {
if (!(plotWidth > 0) || !(labelWidth > 0)) return maxCount;
for (let count = maxCount; count > 2; count--) {
if (plotWidth / (count - 1) >= labelWidth + HISTORY_CHART_TIME_LABEL_GAP) return count;
}
return 2;
}
export function getHistoryChartLeftInset(labelWidths: number[]) {
const widestLabel = Math.max(0, ...labelWidths);
return Math.max(HISTORY_CHART_MIN_LEFT_INSET, Math.ceil(widestLabel) + 8);
}
export function getHistoryChartRightInset(lastTimeLabelWidth: number) {
return Math.max(0, Math.ceil(lastTimeLabelWidth / 2) + 2);
}
export function formatHistoryChartTimeLabel(timestamp: number, range: HistoryTimeRange) {
const date = new Date(timestamp);
if (range === '30d' || range === '90d' || range === '14d' || range === '7d') {
return date.toLocaleDateString([], { month: 'short', day: 'numeric' });
}
return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
}
export function createHistoryChartGeometry({
width,
height,
startTime,
endTime,
minValue,
maxValue,
leftInset = HISTORY_CHART_MIN_LEFT_INSET,
rightInset = 0,
}: {
width: number;
height: number;
startTime: number;
endTime: number;
minValue: number;
maxValue: number;
leftInset?: number;
rightInset?: number;
}) {
const timeSpan = Math.max(1, endTime - startTime);
const plotWidth = width - leftInset - rightInset;
const singleTimestamp = startTime === endTime;
const getX = (timestamp: number) =>
singleTimestamp
? leftInset + plotWidth / 2
: leftInset + ((timestamp - startTime) / timeSpan) * plotWidth;
const getTimestamp = (x: number) =>
singleTimestamp ? startTime : startTime + ((x - leftInset) / plotWidth) * timeSpan;
const getY = (value: number) =>
height - 20 - ((value - minValue) / (maxValue - minValue)) * (height - 40);
return {
timeSpan,
getX,
getTimestamp,
getY,
};
}
export function findHistoryChartClosestPoint(
points: AggregatedMetricPoint[],
hoverTimestamp: number,
) {
let closest = points[0];
let minDiff = Math.abs(points[0].timestamp - hoverTimestamp);
for (const point of points) {
const diff = Math.abs(point.timestamp - hoverTimestamp);
if (diff < minDiff) {
minDiff = diff;
closest = point;
}
}
return closest;
}
export function getHistoryChartTooltipLayout({
hoveredPoint,
chartWidth,
chartHeight,
}: {
hoveredPoint: HistoryChartHoverPoint;
chartWidth: number;
chartHeight: number;
}): HistoryChartTooltipLayout {
const width = 156;
// Allow a wrapped local timestamp plus the reading at normal text size.
const height = 64;
const margin = 8;
const pointGap = 12;
const minX = margin;
const maxX = Math.max(minX, chartWidth - width - margin);
const minY = margin;
const maxY = Math.max(minY, chartHeight - height - margin);
const clampX = (value: number) => Math.min(Math.max(value, minX), maxX);
const clampY = (value: number) => Math.min(Math.max(value, minY), maxY);
const rightX = hoveredPoint.x + pointGap;
const leftX = hoveredPoint.x - width - pointGap;
const canPlaceRight = rightX <= maxX;
const canPlaceLeft = leftX >= minX;
const rightRoom = chartWidth - margin - hoveredPoint.x;
const leftRoom = hoveredPoint.x - margin;
const x =
canPlaceRight && (!canPlaceLeft || rightRoom >= leftRoom)
? rightX
: canPlaceLeft
? leftX
: clampX(hoveredPoint.x - width / 2);
let y = clampY(hoveredPoint.y - height / 2);
const overlapsHoveredPoint =
hoveredPoint.x >= x &&
hoveredPoint.x <= x + width &&
hoveredPoint.y >= y &&
hoveredPoint.y <= y + height;
if (overlapsHoveredPoint) {
const showBelow = hoveredPoint.y < height + margin;
y = showBelow ? clampY(hoveredPoint.y + pointGap) : clampY(hoveredPoint.y - height - pointGap);
}
return { x, y, width, height };
}