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 {
ResourceType,
ResourceVMwareHardware,
ResourceVMwareMeta,
ResourceVMwareNetworkAdapter,
ResourceVMwareSnapshot,
ResourceVMwareTools,
ResourceVMwareVirtualDisk,
} from '@/types/resource';
import { formatVmwareClusterServices } from '@/utils/vmwareDisplay';
import {
compactDetailRows as compactRows,
compactDetailSections as compactSections,
type DetailRow,
type DetailSection,
type DetailValueTone,
formatDetailBytesValue,
formatDetailCountValue,
makeDetailRow as makeRow,
} from '@/components/shared/detailSectionModel';
const asTrimmedString = (value?: string | null): string => (value || '').trim();
// Names, addresses and paths an operator copies into vCenter or a shell wrap
// in full instead of ending in an ellipsis.
const wrapRow = (
label: string,
value?: string | null,
options: Parameters<typeof makeRow>[2] = {},
) => makeRow(label, value, { ...options, wrap: true });
// Tools and vNIC state only mean something while the VM runs: a powered-off
// VM has no running Tools and no connected adapters by design. Without a
// reported power state the readings are taken at face value.
const isPoweredOff = (vmware?: ResourceVMwareMeta): boolean => {
const state = asTrimmedString(vmware?.powerState)
.toLowerCase()
.replace(/[^a-z]/g, '');
return state === 'poweredoff' || state === 'suspended' || state === 'off';
};
const summarizeList = (values: string[] | undefined): string =>
(values ?? []).map(asTrimmedString).filter(Boolean).join(', ');
const formatBoolLabel = (value?: boolean): string => {
if (value === undefined) return '';
return value ? 'Yes' : 'No';
};
const VMWARE_ENUM_ACRONYMS: Record<string, string> = {
API: 'API',
BIOS: 'BIOS',
CPU: 'CPU',
IP: 'IP',
OS: 'OS',
VM: 'VM',
VMDK: 'VMDK',
VMX: 'VMX',
EFI: 'EFI',
IPV4: 'IPv4',
IPV6: 'IPv6',
};
const formatEnumLabel = (value?: string | null): string => {
const normalized = asTrimmedString(value);
if (!normalized) return '';
return normalized
.split(/[_\s-]+/)
.filter(Boolean)
.map((part) => {
const upper = part.toUpperCase();
return (
VMWARE_ENUM_ACRONYMS[upper] ?? part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
);
})
.join(' ');
};
const formatMiB = (value?: number): string => {
if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return '';
return (
formatDetailBytesValue(value * 1024 * 1024, {
allowZero: true,
precision: 'compact',
trimWhole: true,
}) ?? ''
);
};
const countSnapshotTree = (snapshots?: ResourceVMwareSnapshot[]): number =>
(snapshots ?? []).reduce(
(total, snapshot) => total + 1 + countSnapshotTree(snapshot.children),
0,
);
const snapshotDisplayName = (snapshot: ResourceVMwareSnapshot): string =>
asTrimmedString(snapshot.name) ||
asTrimmedString(snapshot.snapshot) ||
(typeof snapshot.id === 'number' ? `Snapshot ${snapshot.id}` : 'Snapshot');
const formatSnapshotDate = (value?: string | number): string => {
if (value === undefined || value === null || value === '') return '';
const date = new Date(value);
if (Number.isNaN(date.getTime())) return asTrimmedString(String(value));
const pad = (part: number) => String(part).padStart(2, '0');
return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(
date.getUTCDate(),
)} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())} UTC`;
};
const snapshotValue = (snapshot: ResourceVMwareSnapshot): string => {
const parts = [
snapshot.current ? 'current' : '',
asTrimmedString(snapshot.state),
formatSnapshotDate(snapshot.createdAt),
snapshot.quiesced === undefined ? '' : snapshot.quiesced ? 'quiesced' : 'not quiesced',
asTrimmedString(snapshot.description),
].filter(Boolean);
return parts.join(' · ');
};
const flattenSnapshotRows = (
snapshots: ResourceVMwareSnapshot[] | undefined,
depth = 0,
): DetailRow[] => {
const rows: DetailRow[] = [];
for (const snapshot of snapshots ?? []) {
const snapshotRow = wrapRow(
`${depth > 0 ? `${'-'.repeat(depth)} ` : ''}${snapshotDisplayName(snapshot)}`,
snapshotValue(snapshot) || asTrimmedString(snapshot.snapshot),
{ tone: snapshot.current ? 'accent' : 'default' },
);
if (snapshotRow) rows.push(snapshotRow);
rows.push(...flattenSnapshotRows(snapshot.children, depth + 1));
}
return rows;
};
const adapterDisplayName = (adapter: ResourceVMwareNetworkAdapter): string =>
asTrimmedString(adapter.label) ||
asTrimmedString(adapter.nic) ||
asTrimmedString(adapter.macAddress) ||
'Network adapter';
const adapterNetworkName = (adapter: ResourceVMwareNetworkAdapter): string =>
asTrimmedString(adapter.networkName) ||
asTrimmedString(adapter.networkId) ||
asTrimmedString(adapter.opaqueNetworkId) ||
asTrimmedString(adapter.hostDevice) ||
asTrimmedString(adapter.backingType);
const adapterConnectionLabel = (adapter: ResourceVMwareNetworkAdapter): string => {
const parts = [
asTrimmedString(adapter.state),
adapter.startConnected === undefined
? ''
: adapter.startConnected
? 'starts connected'
: 'does not start connected',
adapter.allowGuestControl === undefined
? ''
: adapter.allowGuestControl
? 'guest control'
: 'no guest control',
].filter(Boolean);
return parts.join(' · ');
};
const adapterValue = (adapter: ResourceVMwareNetworkAdapter): string => {
const parts = [
asTrimmedString(adapter.type),
adapterNetworkName(adapter),
asTrimmedString(adapter.macAddress),
adapterConnectionLabel(adapter),
].filter(Boolean);
return parts.join(' · ');
};
const adapterTone = (adapter: ResourceVMwareNetworkAdapter): DetailValueTone =>
asTrimmedString(adapter.state).toLowerCase() === 'not_connected' ? 'warning' : 'default';
const networkAdapterRows = (
adapters: ResourceVMwareNetworkAdapter[] | undefined,
poweredOff: boolean,
): DetailRow[] =>
compactRows(
(adapters ?? []).map((adapter) =>
wrapRow(adapterDisplayName(adapter), adapterValue(adapter), {
tone: poweredOff ? 'default' : adapterTone(adapter),
}),
),
);
const getWarningTone = (hasWarning: boolean): DetailValueTone =>
hasWarning ? 'warning' : 'default';
const hardwareSummary = (hardware?: ResourceVMwareHardware): string => {
if (!hardware) return '';
const upgradeStatus = asTrimmedString(hardware.upgradeStatus);
if (upgradeStatus && !['NONE', 'OK'].includes(upgradeStatus.toUpperCase())) {
return `Hardware ${formatEnumLabel(upgradeStatus).toLowerCase()}`;
}
return formatEnumLabel(hardware.version);
};
const cpuTopologyLabel = (vmware: ResourceVMwareMeta): string => {
const parts = [];
if (
typeof vmware.cpuCount === 'number' &&
Number.isFinite(vmware.cpuCount) &&
vmware.cpuCount > 0
) {
parts.push(`${vmware.cpuCount} vCPU`);
}
if (
typeof vmware.hardware?.cpuCoresPerSocket === 'number' &&
Number.isFinite(vmware.hardware.cpuCoresPerSocket) &&
vmware.hardware.cpuCoresPerSocket > 0
) {
parts.push(`${vmware.hardware.cpuCoresPerSocket} cores/socket`);
}
return parts.join(' · ');
};
const hardwareRows = (vmware?: ResourceVMwareMeta): DetailRow[] => {
if (!vmware?.hardware) return [];
const hardware = vmware.hardware;
const upgradeStatus = asTrimmedString(hardware.upgradeStatus).toUpperCase();
const upgradeAttention = Boolean(upgradeStatus) && !['NONE', 'OK'].includes(upgradeStatus);
return compactRows([
makeRow('Guest OS', formatEnumLabel(hardware.guestOs)),
makeRow('Hardware version', formatEnumLabel(hardware.version)),
makeRow('CPU topology', cpuTopologyLabel(vmware)),
makeRow('Memory size', formatMiB(vmware?.memorySizeMib)),
// Upgrade and clone status only surface when something is actionable;
// when everything is in the default state these rows resolve to empty
// strings and compactRows drops them. Capability toggles
// (CPU/memory hot-add, boot config) live in the raw API and stay out
// of the operator drawer because they don't change minute to minute
// and operators don't act on them from Pulse.
makeRow('Upgrade status', upgradeAttention ? formatEnumLabel(hardware.upgradeStatus) : '', {
tone: getWarningTone(upgradeAttention),
}),
makeRow('Upgrade error', asTrimmedString(hardware.upgradeErrorMessage), {
tone: 'warning',
wrap: true,
}),
makeRow(
'Instant clone frozen',
hardware.instantCloneFrozen === true ? formatBoolLabel(true) : '',
{
tone: getWarningTone(hardware.instantCloneFrozen === true),
},
),
makeRow('Enter setup mode', hardware.enterSetupMode === true ? formatBoolLabel(true) : '', {
tone: getWarningTone(hardware.enterSetupMode === true),
}),
]);
};
const toolsSummary = (tools?: ResourceVMwareTools): string => {
if (!tools) return '';
if (tools.guestRebootRequested) return 'Tools reboot requested';
const versionStatus = asTrimmedString(tools.versionStatus);
if (versionStatus && !['CURRENT', 'OK'].includes(versionStatus.toUpperCase())) {
return `Tools ${formatEnumLabel(versionStatus).toLowerCase()}`;
}
const runState = asTrimmedString(tools.runState);
if (runState) return `Tools ${formatEnumLabel(runState).toLowerCase()}`;
return '';
};
const toolsRows = (tools: ResourceVMwareTools | undefined, poweredOff: boolean): DetailRow[] => {
if (!tools) return [];
const versionStatus = asTrimmedString(tools.versionStatus).toUpperCase();
const versionAttention = Boolean(versionStatus) && !['CURRENT', 'OK'].includes(versionStatus);
// Drawer surfaces what an operator scans for: is Tools running, is its
// version current, has the guest asked for a reboot, did the last install
// error. Install metadata (install type, upgrade policy, auto-update
// capability, attempt count, reboot components / time) stays in the raw
// API; we only surface it when something is actionable.
return compactRows([
makeRow('Run state', formatEnumLabel(tools.runState), {
tone: getWarningTone(
!poweredOff &&
Boolean(asTrimmedString(tools.runState)) &&
!['RUNNING', 'STARTED'].includes(asTrimmedString(tools.runState).toUpperCase()),
),
}),
makeRow('Version status', versionAttention ? formatEnumLabel(tools.versionStatus) : '', {
tone: getWarningTone(versionAttention),
}),
makeRow('Version', asTrimmedString(tools.version)),
makeRow('Guest reboot', tools.guestRebootRequested === true ? 'Requested' : '', {
tone: getWarningTone(tools.guestRebootRequested === true),
}),
makeRow('Last install error', asTrimmedString(tools.errorMessage), {
tone: 'warning',
wrap: true,
}),
]);
};
const virtualDiskDisplayName = (disk: ResourceVMwareVirtualDisk): string =>
asTrimmedString(disk.label) || asTrimmedString(disk.disk) || 'Virtual disk';
const formatVirtualDiskAddress = (disk: ResourceVMwareVirtualDisk): string => {
const type = asTrimmedString(disk.type).toUpperCase();
if (type === 'SCSI' && disk.scsiBus !== undefined && disk.scsiUnit !== undefined) {
return `SCSI ${disk.scsiBus}:${disk.scsiUnit}`;
}
if (type === 'SATA' && disk.sataBus !== undefined && disk.sataUnit !== undefined) {
return `SATA ${disk.sataBus}:${disk.sataUnit}`;
}
if (type === 'NVME' && disk.nvmeBus !== undefined && disk.nvmeUnit !== undefined) {
return `NVMe ${disk.nvmeBus}:${disk.nvmeUnit}`;
}
if (type === 'IDE' && disk.idePrimary !== undefined && disk.ideMaster !== undefined) {
return `IDE ${disk.idePrimary ? 'primary' : 'secondary'} ${
disk.ideMaster ? 'master' : 'slave'
}`;
}
return type;
};
const virtualDiskValue = (disk: ResourceVMwareVirtualDisk): string => {
const parts = [
formatVirtualDiskAddress(disk),
formatDetailBytesValue(disk.capacityBytes, {
allowZero: true,
precision: 'compact',
trimWhole: true,
}),
asTrimmedString(disk.datastoreName),
asTrimmedString(disk.backingType),
asTrimmedString(disk.vmdkFile),
].filter(Boolean);
return parts.join(' · ');
};
const virtualDiskRows = (disks: ResourceVMwareVirtualDisk[] | undefined): DetailRow[] =>
compactRows(
(disks ?? []).map((disk) =>
wrapRow(virtualDiskDisplayName(disk), virtualDiskValue(disk), { tone: 'default' }),
),
);
const vmwareEntityLabel = (entityType?: string): string => {
const normalized = asTrimmedString(entityType).toLowerCase();
switch (normalized) {
case 'host':
case 'hostsystem':
return 'Host';
case 'vm':
case 'virtualmachine':
return 'VM';
case 'datastore':
return 'Datastore';
case 'network':
return 'Network';
default:
return asTrimmedString(entityType);
}
};
const buildSignalValue = (count: number | undefined, label: string, summary?: string): string => {
const parts: string[] = [];
if (typeof count === 'number') {
parts.push(formatDetailCountValue(Math.max(0, count), label));
}
const trimmedSummary = asTrimmedString(summary);
if (trimmedSummary) {
parts.push(trimmedSummary);
}
return parts.join(' · ');
};
// vCenter's overall status colours, in plain words: red is a problem, yellow
// may be one, green is fine and gray is not known.
const OVERALL_STATUS_PRESENTATION: Record<string, { label: string; tone: DetailValueTone }> = {
red: { label: 'Problem (red)', tone: 'danger' },
yellow: { label: 'Warning (yellow)', tone: 'warning' },
green: { label: 'OK (green)', tone: 'success' },
gray: { label: 'Unknown (gray)', tone: 'default' },
};
const overallStatusRow = (status?: string | null): DetailRow | null => {
const normalized = asTrimmedString(status).toLowerCase();
const presentation = OVERALL_STATUS_PRESENTATION[normalized];
return presentation
? makeRow('Overall status', presentation.label, { tone: presentation.tone })
: makeRow('Overall status', asTrimmedString(status));
};
// A host that vCenter cannot reach is the reason its row reads offline.
const connectionStateTone = (state?: string): DetailValueTone => {
const normalized = asTrimmedString(state)
.toLowerCase()
.replace(/[^a-z]/g, '');
return normalized === 'disconnected' || normalized === 'notresponding' ? 'warning' : 'default';
};
// Datastores report "normal" when not in maintenance; anything else
// (entering or in maintenance) means VMs cannot rely on it.
const maintenanceRow = (mode?: string): DetailRow | null => {
const raw = asTrimmedString(mode);
if (!raw) return null;
if (raw.toLowerCase() === 'normal') return makeRow('Maintenance', 'No');
const words = raw.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ');
return makeRow('Maintenance', words.charAt(0).toUpperCase() + words.slice(1).toLowerCase(), {
tone: 'warning',
});
};
const getAccentTone = (hasAccent: boolean): DetailValueTone => (hasAccent ? 'accent' : 'default');
export const buildVMwareDetailsSummary = (
resourceType: ResourceType,
vmware?: ResourceVMwareMeta,
): string | null => {
if (!vmware) return null;
const parts: string[] = [];
const connection = asTrimmedString(vmware.connectionName) || asTrimmedString(vmware.vcenterHost);
if (connection) {
parts.push(connection);
}
parts.push('Read-only vCenter context');
const snapshotCount =
typeof vmware.snapshotCount === 'number'
? Math.max(0, vmware.snapshotCount)
: countSnapshotTree(vmware.snapshotTree);
if (resourceType === 'vm' && snapshotCount > 0) {
parts.push(formatDetailCountValue(snapshotCount, 'snapshot'));
}
const networkAdapterCount = vmware.networkAdapters?.length ?? 0;
if (resourceType === 'vm' && networkAdapterCount > 0) {
parts.push(formatDetailCountValue(networkAdapterCount, 'vNIC'));
}
const virtualDiskCount = vmware.virtualDisks?.length ?? 0;
if (resourceType === 'vm' && virtualDiskCount > 0) {
parts.push(formatDetailCountValue(virtualDiskCount, 'disk'));
}
if (resourceType === 'network') {
const hostCount = vmware.networkHostNames?.length ?? vmware.networkHostIds?.length ?? 0;
const vmCount = vmware.networkVmNames?.length ?? vmware.networkVmIds?.length ?? 0;
if (hostCount > 0) parts.push(formatDetailCountValue(hostCount, 'host'));
if (vmCount > 0) parts.push(formatDetailCountValue(vmCount, 'VM'));
}
const hardware = resourceType === 'vm' ? hardwareSummary(vmware.hardware) : '';
if (hardware) {
parts.push(hardware);
}
const tools = resourceType === 'vm' ? toolsSummary(vmware.tools) : '';
if (tools) {
parts.push(tools);
}
if ((vmware.activeAlarmCount ?? 0) > 0) {
parts.push(formatDetailCountValue(vmware.activeAlarmCount ?? 0, 'alarm'));
}
if ((vmware.recentTaskCount ?? 0) > 0) {
parts.push(formatDetailCountValue(vmware.recentTaskCount ?? 0, 'task'));
}
return parts.join(' · ');
};
export const buildVMwareDetailSections = (
resourceType: ResourceType,
vmware?: ResourceVMwareMeta,
): DetailSection[] => {
if (!vmware) {
return [];
}
const poweredOff = isPoweredOff(vmware);
const stateRows = compactRows([
wrapRow('Connection', asTrimmedString(vmware.connectionName)),
wrapRow('vCenter', asTrimmedString(vmware.vcenterHost)),
makeRow('Entity', vmwareEntityLabel(vmware.entityType)),
overallStatusRow(vmware.overallStatus),
// Power state is already conveyed by the workload row's status dot and
// the SYSTEM card. We only resurface Connection state here because it
// matters when an ESXi host is disconnected and the row dot alone can't
// tell you why.
makeRow('Connection state', formatEnumLabel(vmware.connectionState), {
tone: connectionStateTone(vmware.connectionState),
}),
makeRow('Datastore type', asTrimmedString(vmware.datastoreType)),
makeRow('Accessible', formatBoolLabel(vmware.datastoreAccessible), {
tone: getWarningTone(vmware.datastoreAccessible === false),
}),
makeRow('Shared access', formatBoolLabel(vmware.multipleHostAccess)),
maintenanceRow(vmware.maintenanceMode),
makeRow('Network type', formatEnumLabel(vmware.networkType)),
]);
const placementRows = compactRows([
wrapRow('Datacenter', asTrimmedString(vmware.datacenterName)),
wrapRow('Cluster', asTrimmedString(vmware.clusterName)),
makeRow('Cluster services', formatVmwareClusterServices(vmware)),
wrapRow('Compute resource', asTrimmedString(vmware.computeResourceName)),
wrapRow('Folder', asTrimmedString(vmware.folderName)),
wrapRow('Resource pool', asTrimmedString(vmware.resourcePoolName)),
wrapRow('Runtime host', asTrimmedString(vmware.runtimeHostName)),
wrapRow('Datastores', (vmware.datastoreNames ?? []).filter(Boolean).join(', ')),
]);
// UUID fields (host / instance / BIOS) and datastoreUrl are API-shaped
// identifiers an operator never types or compares from the drawer; they
// are still available in the raw resource payload. Keep guest identity
// human-readable.
const guestRows = compactRows([
makeRow('Guest OS', asTrimmedString(vmware.guestOsFamily)),
wrapRow('Guest hostname', asTrimmedString(vmware.guestHostname)),
wrapRow('Guest IPs', (vmware.guestIpAddresses ?? []).filter(Boolean).join(', ')),
]);
const networkRows =
resourceType === 'vm'
? networkAdapterRows(vmware.networkAdapters, poweredOff)
: compactRows([
wrapRow('Hosts', summarizeList(vmware.networkHostNames)),
wrapRow('VMs', summarizeList(vmware.networkVmNames)),
]);
const vmwareHardwareRows = resourceType === 'vm' ? hardwareRows(vmware) : [];
const vmwareToolsRows = resourceType === 'vm' ? toolsRows(vmware.tools, poweredOff) : [];
const diskRows = resourceType === 'vm' ? virtualDiskRows(vmware.virtualDisks) : [];
const signalRows = compactRows([
makeRow(
'Alarms',
buildSignalValue(vmware.activeAlarmCount, 'alarm', vmware.activeAlarmSummary),
{
tone: getWarningTone((vmware.activeAlarmCount ?? 0) > 0),
wrap: true,
},
),
makeRow('Tasks', buildSignalValue(vmware.recentTaskCount, 'task', vmware.recentTaskSummary), {
tone: getAccentTone((vmware.recentTaskCount ?? 0) > 0),
}),
makeRow(
'Snapshots',
resourceType === 'vm' || typeof vmware.snapshotCount === 'number'
? formatDetailCountValue(
Math.max(
0,
typeof vmware.snapshotCount === 'number'
? vmware.snapshotCount
: countSnapshotTree(vmware.snapshotTree),
),
'snapshot',
)
: '',
),
]);
const snapshotRows = resourceType === 'vm' ? flattenSnapshotRows(vmware.snapshotTree) : [];
return compactSections([
{ label: 'State', rows: stateRows },
{ label: 'Placement', rows: placementRows },
{ label: 'Guest', rows: guestRows },
{ label: 'Virtual hardware', rows: vmwareHardwareRows },
{ label: 'VMware Tools', rows: vmwareToolsRows },
{ label: 'Virtual disks', rows: diskRows },
{ label: 'Network', rows: networkRows },
{ label: 'Signals', rows: signalRows },
{ label: 'Snapshot tree', rows: snapshotRows },
]);
};