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 { HistoryTimeRange, ResourceType as HistoryChartResourceType } from '@/api/charts';
import {
getPhysicalDiskTemperaturePresentation,
type PhysicalDiskAlertResourceIdResolver,
} from '@/features/storageBackups/diskPresentation';
import type { StorageRecord } from '@/features/storageBackups/models';
import {
getStorageRecordContent,
getStorageRecordNodeLabel,
getStorageRecordPlatformLabel,
getStorageRecordShared,
getStorageRecordStatus,
getStorageRecordType,
getStorageRecordZfsPool,
} from '@/features/storageBackups/recordPresentation';
import { resolveStorageRecordMetricResourceId } from '@/features/storageBackups/storageMetricsIdentity';
import type { Resource } from '@/types/resource';
import { formatBytes, formatPercent } from '@/utils/format';
import { formatHistoryRangeOptionLabel } from '@/components/shared/historyChartModel';
export type StoragePoolDetailConfigRow = {
label: string;
value: string;
};
export type StoragePoolDetailLinkedDisk = {
id: string;
devPath: string;
model: string;
role: string;
state: string;
sizeLabel: string;
diskType: string;
/** Alert override keys of the machine whose agent reports the disk. */
alertResourceIds?: string[];
temperature: number;
/** Set only when the temperature is a retained, not current, reading. */
temperatureLastKnownTitle?: string;
hasIssue: boolean;
spunDown: boolean;
errorCount: number;
ioLabel: string;
};
export type StoragePoolDetailTopologyRow = {
label: string;
value: string;
};
export type StoragePoolDetailChartTarget = {
resourceType: HistoryChartResourceType;
resourceId: string | null;
};
export type StoragePoolDetailZfsDevice = {
name: string;
type: string;
state: string;
errorSummary: string;
message: string;
};
export type StoragePoolDetailZfsSummary = {
state: string;
scan: string;
/** Errors the current or last scrub/resilver found; 0 when none or unreported. */
scanErrors: number;
errorSummary: string | null;
devices: StoragePoolDetailZfsDevice[];
datasets: Array<{
name: string;
type: string;
mountpoint: string;
usedLabel: string;
availableLabel: string;
referencedLabel: string;
}>;
};
export const STORAGE_POOL_DETAIL_HISTORY_RANGE_OPTIONS: readonly {
value: HistoryTimeRange;
label: string;
}[] = (['24h', '7d', '14d', '30d', '90d'] as const).map((value) => ({
value,
label: formatHistoryRangeOptionLabel(value),
}));
export function getZfsScanTextClass(): string {
return 'text-yellow-600 dark:text-yellow-400 italic';
}
export function getZfsErrorSummary(
readErrors: number,
writeErrors: number,
checksumErrors: number,
): string {
return `Errors: R:${readErrors} W:${writeErrors} C:${checksumErrors}`;
}
export function getZfsErrorTextClass(): string {
return 'font-medium text-red-600 dark:text-red-400';
}
export function resolveStoragePoolDetailChartTarget(
record: StorageRecord,
): StoragePoolDetailChartTarget {
return {
resourceType: (record.metricsTarget?.resourceType as HistoryChartResourceType) || 'storage',
resourceId: resolveStorageRecordMetricResourceId(record),
};
}
export function buildStoragePoolDetailConfigRows(
record: StorageRecord,
): StoragePoolDetailConfigRow[] {
// Missing collector observations are not measurements of an empty pool.
const observed = (value: number | null): number | null =>
typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
const totalBytes = observed(record.capacity.totalBytes);
const usedBytes = observed(record.capacity.usedBytes);
const freeBytes =
observed(record.capacity.freeBytes) ??
(totalBytes !== null && usedBytes !== null ? Math.max(totalBytes - usedBytes, 0) : null);
const usagePercent =
observed(record.capacity.usagePercent) ??
(totalBytes !== null && totalBytes > 0 && usedBytes !== null
? (usedBytes / totalBytes) * 100
: null);
const bytesLabel = (value: number | null): string =>
value === null ? 'n/a' : formatBytes(value);
const content = getStorageRecordContent(record);
const rows: StoragePoolDetailConfigRow[] = [
{ label: 'Node', value: getStorageRecordNodeLabel(record) },
{ label: 'Source', value: getStorageRecordPlatformLabel(record) },
{ label: 'Type', value: getStorageRecordType(record) },
{ label: 'Status', value: getStorageRecordStatus(record) },
{
label: 'Shared',
value:
getStorageRecordShared(record) === null
? '-'
: getStorageRecordShared(record)
? 'Yes'
: 'No',
},
{ label: 'Used', value: bytesLabel(usedBytes) },
{ label: 'Free', value: bytesLabel(freeBytes) },
{ label: 'Total', value: bytesLabel(totalBytes) },
{ label: 'Usage', value: usagePercent === null ? 'n/a' : formatPercent(usagePercent) },
];
if (content) {
rows.splice(3, 0, { label: 'Content', value: content });
}
return rows;
}
const getRecordDetails = (record: StorageRecord): Record<string, unknown> =>
(record.details || {}) as Record<string, unknown>;
const readRecordDetailString = (record: StorageRecord, key: string): string => {
const value = getRecordDetails(record)[key];
return typeof value === 'string' ? value.trim() : '';
};
const readRecordDetailNumber = (record: StorageRecord, key: string): number => {
const value = getRecordDetails(record)[key];
return typeof value === 'number' && Number.isFinite(value) ? value : 0;
};
const isUnraidStorageRecord = (record: StorageRecord): boolean => {
const platform = readRecordDetailString(record, 'platform').toLowerCase();
const type = getStorageRecordType(record).toLowerCase();
return record.source.platform === 'unraid' || platform === 'unraid' || type.startsWith('unraid-');
};
const getUnraidStorageGroup = (record: StorageRecord): string => {
if (!isUnraidStorageRecord(record)) return '';
const type = getStorageRecordType(record).toLowerCase();
const topology = readRecordDetailString(record, 'topology').toLowerCase();
if (type === 'unraid-array' || topology === 'array') return 'unraid-array';
if (type === 'unraid-cache-pool') return record.name.trim();
return '';
};
const pluralize = (count: number, singular: string, plural = `${singular}s`): string =>
`${count} ${count === 1 ? singular : plural}`;
const titleizeStorageState = (value: string): string =>
value
.split(/[\s_-]+/)
.filter(Boolean)
.map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
.join(' ');
export function buildStoragePoolDetailTopologyRows(
record: StorageRecord,
linkedDisks: StoragePoolDetailLinkedDisk[],
): StoragePoolDetailTopologyRow[] {
if (!isUnraidStorageRecord(record)) return [];
const type = getStorageRecordType(record).toLowerCase();
const arrayState = readRecordDetailString(record, 'arrayState');
const syncAction = readRecordDetailString(record, 'syncAction');
const syncProgress = readRecordDetailNumber(record, 'syncProgress');
const parityDisks = linkedDisks.filter((disk) => disk.role.toLowerCase() === 'parity').length;
const dataDisks = linkedDisks.filter((disk) => disk.role.toLowerCase() === 'data').length;
const cacheDisks = linkedDisks.filter((disk) => disk.role.toLowerCase() === 'cache').length;
const errorCount = linkedDisks.reduce((sum, disk) => sum + disk.errorCount, 0);
const spunDownCount = linkedDisks.filter((disk) => disk.spunDown).length;
const rows: StoragePoolDetailTopologyRow[] = [];
rows.push({ label: 'Kind', value: type === 'unraid-cache-pool' ? 'Cache pool' : 'Array' });
if (arrayState) rows.push({ label: 'State', value: titleizeStorageState(arrayState) });
if (type === 'unraid-array') {
rows.push({
label: 'Parity',
value: parityDisks > 0 ? pluralize(parityDisks, 'disk') : 'None configured',
});
rows.push({ label: 'Data disks', value: pluralize(dataDisks, 'disk') });
} else {
rows.push({ label: 'Devices', value: pluralize(cacheDisks || linkedDisks.length, 'disk') });
}
if (spunDownCount > 0) {
rows.push({ label: 'Spun down', value: pluralize(spunDownCount, 'disk') });
}
if (errorCount > 0) {
rows.push({ label: 'Disk errors', value: errorCount.toLocaleString() });
}
if (syncAction) {
rows.push({
label: 'Sync',
value: syncProgress > 0 ? `${syncAction} (${Math.round(syncProgress)}%)` : syncAction,
});
}
return rows;
}
export function getZfsDeviceErrorSummary(
readErrors: number,
writeErrors: number,
checksumErrors: number,
): string {
if (readErrors <= 0 && writeErrors <= 0 && checksumErrors <= 0) return '';
return `${readErrors}R/${writeErrors}W/${checksumErrors}C errors`;
}
export function getZfsDeviceStateTextClass(state: string): string {
const normalized = (state || '').trim().toUpperCase();
if (!normalized || normalized === 'ONLINE') return 'text-muted';
if (normalized === 'DEGRADED') return 'font-medium text-amber-700 dark:text-amber-300';
return 'font-medium text-red-700 dark:text-red-300';
}
export function buildStoragePoolDetailZfsSummary(
record: StorageRecord,
): StoragePoolDetailZfsSummary | null {
const pool = getStorageRecordZfsPool(record);
if (!pool) return null;
const hasErrors = pool.readErrors > 0 || pool.writeErrors > 0 || pool.checksumErrors > 0;
return {
state: pool.state,
scan: pool.scan && pool.scan !== 'none' ? pool.scan : '',
scanErrors:
typeof pool.scanDetails?.errors === 'number' && Number.isFinite(pool.scanDetails.errors)
? Math.max(0, pool.scanDetails.errors)
: 0,
errorSummary: hasErrors
? getZfsErrorSummary(pool.readErrors, pool.writeErrors, pool.checksumErrors)
: null,
devices: (pool.devices || []).map((device) => ({
name: device.name,
type: device.type || '',
state: device.state || '',
errorSummary: getZfsDeviceErrorSummary(
device.readErrors || 0,
device.writeErrors || 0,
device.checksumErrors || 0,
),
message: (device.message || '').trim(),
})),
datasets: (pool.datasets || []).map((dataset) => ({
name: dataset.name,
type: dataset.type || 'filesystem',
mountpoint: dataset.mountpoint || '',
usedLabel: formatBytes(dataset.usedBytes || 0),
availableLabel: formatBytes(dataset.availableBytes || 0),
referencedLabel: formatBytes(dataset.referencedBytes || 0),
})),
};
}
const readPhysicalDisk = (disk: Resource): NonNullable<Resource['physicalDisk']> => {
const platformData = (disk.platformData || {}) as Record<string, unknown>;
const platformDisk = platformData.physicalDisk as
NonNullable<Resource['physicalDisk']> | undefined;
return (disk.physicalDisk || platformDisk || {}) as NonNullable<Resource['physicalDisk']>;
};
const readDiskDevPath = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.devPath === 'string' ? physicalDisk.devPath : '';
};
const readDiskModel = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.model === 'string' && physicalDisk.model.trim()
? physicalDisk.model
: 'Unknown';
};
const readDiskTemperature = (disk: Resource): number => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.temperature === 'number' ? physicalDisk.temperature : 0;
};
const readDiskTemperatureLastKnownTitle = (disk: Resource): string | undefined =>
getPhysicalDiskTemperaturePresentation({
temperature: readDiskTemperature(disk),
collection: readPhysicalDisk(disk).collection,
})?.title;
const readDiskType = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.diskType === 'string' ? physicalDisk.diskType.trim() : '';
};
const readDiskHasIssue = (disk: Resource): boolean => {
const physicalDisk = readPhysicalDisk(disk);
const smart = physicalDisk.smart as Record<string, unknown> | undefined;
const reallocated = smart?.reallocatedSectors;
const errorCount = typeof physicalDisk.errorCount === 'number' ? physicalDisk.errorCount : 0;
return errorCount > 0 || (typeof reallocated === 'number' && reallocated > 0);
};
const readDiskStorageGroup = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.storageGroup === 'string' ? physicalDisk.storageGroup.trim() : '';
};
const readDiskRole = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.storageRole === 'string' ? physicalDisk.storageRole.trim() : '';
};
const readDiskState = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.storageState === 'string' ? physicalDisk.storageState.trim() : '';
};
const readDiskSizeLabel = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
return typeof physicalDisk.sizeBytes === 'number' && physicalDisk.sizeBytes > 0
? formatBytes(physicalDisk.sizeBytes)
: '';
};
const readDiskSpunDown = (disk: Resource): boolean => readPhysicalDisk(disk).spunDown === true;
const readDiskErrorCount = (disk: Resource): number => {
const count = readPhysicalDisk(disk).errorCount;
return typeof count === 'number' && Number.isFinite(count) ? count : 0;
};
const readDiskIOLabel = (disk: Resource): string => {
const physicalDisk = readPhysicalDisk(disk);
const readCount = typeof physicalDisk.readCount === 'number' ? physicalDisk.readCount : 0;
const writeCount = typeof physicalDisk.writeCount === 'number' ? physicalDisk.writeCount : 0;
if (readCount <= 0 && writeCount <= 0) return '';
return `R ${readCount.toLocaleString()} / W ${writeCount.toLocaleString()}`;
};
const diskRoleRank = (role: string): number => {
switch (role.toLowerCase()) {
case 'parity':
return 0;
case 'data':
return 1;
case 'cache':
return 2;
default:
return 3;
}
};
const diskBelongsToStorageHost = (record: StorageRecord, disk: Resource): boolean => {
const hostId = readRecordDetailString(record, 'parentId');
const diskParentId = disk.parentId?.trim();
// Canonical ownership outranks labels, paths and source-native names.
// In particular, two hosts may both be called pve1 and both report /dev/sda.
if (hostId && diskParentId) return hostId === diskParentId;
// Older Proxmox snapshots may lack canonical parents. Only the complete
// native instance/node pair is a scope; a hostname alone is not one.
const platformData = (disk.platformData || {}) as Record<string, unknown>;
const proxmox = platformData.proxmox as Resource['proxmox'] | undefined;
const node = readRecordDetailString(record, 'node').toLowerCase();
const instance = readRecordDetailString(record, 'instance');
const diskNode = (disk.proxmox?.nodeName || disk.proxmox?.node || proxmox?.nodeName || '')
.trim()
.toLowerCase();
const diskInstance = (disk.proxmox?.instance || proxmox?.instance || '').trim();
return Boolean(node && instance && node === diskNode && instance === diskInstance);
};
const normalizeDevicePath = (value: string): string => value.trim().replace(/^\/dev\//, '');
export function getStoragePoolLinkedDisks(
record: StorageRecord,
physicalDisks: Resource[],
getAlertResourceIds?: PhysicalDiskAlertResourceIdResolver,
): StoragePoolDetailLinkedDisk[] {
const pool = getStorageRecordZfsPool(record);
const unraidStorageGroup = getUnraidStorageGroup(record).toLowerCase();
const directParentIds = new Set(
[record.id, record.refs?.resourceId].filter((value): value is string => Boolean(value)),
);
return physicalDisks
.filter((disk) => {
const devPath = readDiskDevPath(disk);
const group = readDiskStorageGroup(disk).toLowerCase();
if (directParentIds.has(disk.parentId?.trim() || '')) return true;
if (!diskBelongsToStorageHost(record, disk)) return false;
if (pool?.devices?.length && devPath) {
return pool.devices.some(
(device) =>
Boolean(device.name.trim()) &&
normalizeDevicePath(devPath) === normalizeDevicePath(device.name),
);
}
return Boolean(unraidStorageGroup && group === unraidStorageGroup);
})
.map((disk) => ({
id: disk.id,
devPath: readDiskDevPath(disk) || disk.name,
model: readDiskModel(disk),
role: readDiskRole(disk),
state: readDiskState(disk),
sizeLabel: readDiskSizeLabel(disk),
diskType: readDiskType(disk),
alertResourceIds: getAlertResourceIds?.(disk) ?? [],
temperature: readDiskTemperature(disk),
temperatureLastKnownTitle: readDiskTemperatureLastKnownTitle(disk),
hasIssue: readDiskHasIssue(disk),
spunDown: readDiskSpunDown(disk),
errorCount: readDiskErrorCount(disk),
ioLabel: readDiskIOLabel(disk),
}))
.sort((left, right) => {
const roleDelta = diskRoleRank(left.role) - diskRoleRank(right.role);
if (roleDelta !== 0) return roleDelta;
return left.devPath.localeCompare(right.devPath);
});
}