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
// Properly typed TypeScript interfaces for Pulse API
import type { Resource, ResourceCapability, ResourcePolicy, ResourceChange } from './resource';
import type { EvidenceEnvelope, LifecycleTransition, OperationalRecord } from './operationalTrust';
/** Client-only binding for RBAC administration; these are not JSON payload fields. */
export interface RBACAdminRequestOptions {
signal?: AbortSignal;
expectedOrgID?: string;
retry?: boolean;
}
export interface ResourceListFacetsPayload {
byType?: Partial<Record<string, number>>;
incidentCount?: number;
}
export interface APITokenRecord {
id: string;
name: string;
prefix: string;
suffix: string;
createdAt: string;
lastUsedAt?: string;
expiresAt?: string;
scopes?: string[];
ownerUserId?: string;
}
export interface State {
// Canonical v6 resource contract.
// Platform entities (nodes, guests, agents, storage, PBS/PMG, etc.) are modeled in `resources`.
connectedInfrastructure: ConnectedInfrastructureItem[];
metrics: Metric[];
performance: Performance;
connectionHealth: Record<string, boolean>;
stats: Stats;
activeAlerts: Alert[];
recentlyResolved: ResolvedAlert[];
lastUpdate: number;
temperatureMonitoringEnabled?: boolean;
pveTagColors: Record<string, string>;
pveTagStyles?: Record<string, PVETagStyle>;
// Unified resources (canonical resource model)
resources: Resource[];
// Distinct capability blobs referenced by Resource.capabilitiesRef; the
// websocket store expands refs into inline capabilities at ingestion.
capabilityCatalog?: Record<string, ResourceCapability[]> | null;
// Distinct non-default policy postures and templated AI-safe summaries
// referenced by Resource.policyRef / Resource.aiSafeSummaryRef.
policyCatalog?: Record<string, ResourcePolicy> | null;
aiSafeSummaryCatalog?: Record<string, string> | null;
}
export interface ResourceStateDelta {
upserts?: Array<Partial<Resource> & Pick<Resource, 'id'>>;
removed?: string[];
order?: string[];
}
export type StateUpdate = Partial<State> & {
resourceDelta?: ResourceStateDelta;
};
export interface PVETagStyle {
colors: Record<string, string>;
caseSensitive: boolean;
}
export interface ConnectedInfrastructureSurface {
id: string;
kind: 'agent' | 'availability' | 'docker' | 'kubernetes' | 'proxmox' | 'pbs' | 'pmg' | 'truenas';
label: string;
detail?: string;
controlId?: string;
action?: 'stop-monitoring' | 'allow-reconnect';
idLabel?: string;
idValue?: string;
}
export interface ConnectedInfrastructureItem {
id: string;
name: string;
displayName?: string;
hostname?: string;
status: 'active' | 'ignored';
healthStatus?: string;
lastSeen?: number;
removedAt?: number;
version?: string;
isOutdatedBinary?: boolean;
linkedNodeId?: string;
linkedVmId?: string;
linkedContainerId?: string;
commandsEnabled?: boolean;
scopeAgentId?: string;
upgradePlatform?: 'linux' | 'macos' | 'freebsd' | 'windows';
uninstallAgentId?: string;
uninstallHostname?: string;
surfaces: ConnectedInfrastructureSurface[];
}
export interface KubernetesNode {
uid: string;
name: string;
ready: boolean;
unschedulable?: boolean;
kubeletVersion?: string;
containerRuntimeVersion?: string;
osImage?: string;
kernelVersion?: string;
architecture?: string;
capacityCpuCores?: number;
capacityMemoryBytes?: number;
capacityPods?: number;
allocatableCpuCores?: number;
allocatableMemoryBytes?: number;
allocatablePods?: number;
roles?: string[];
}
export interface KubernetesPodContainer {
name: string;
image?: string;
ready: boolean;
restartCount?: number;
state?: string;
reason?: string;
message?: string;
}
export interface KubernetesPod {
uid: string;
name: string;
namespace: string;
nodeName?: string;
phase?: string;
reason?: string;
message?: string;
qosClass?: string;
createdAt?: number;
startTime?: number;
restarts?: number;
labels?: Record<string, string>;
ownerKind?: string;
ownerName?: string;
containers?: KubernetesPodContainer[];
}
export interface KubernetesDeployment {
uid: string;
name: string;
namespace: string;
desiredReplicas?: number;
updatedReplicas?: number;
readyReplicas?: number;
availableReplicas?: number;
labels?: Record<string, string>;
}
export interface Node {
metricsTarget?: Resource['metricsTarget'];
id: string;
name: string;
displayName?: string;
instance: string;
host: string;
guestURL?: string; // Optional guest-accessible URL (for navigation)
status: string;
type: string;
cpu: number;
memory: Memory;
disk: Disk;
networkIn?: number;
networkOut?: number;
diskRead?: number;
diskWrite?: number;
networkInterfaces?: HostNetworkInterface[];
uptime: number;
loadAverage: number[];
kernelVersion: string;
pveVersion: string;
cpuInfo: CPUInfo;
/** Typed telemetry from a linked Unified Agent, when this PVE node is hybrid. */
sensors?: HostSensorSummary;
/** Client-only projection of the linked agent's reporting lease, not PVE API health. */
sensorsStale?: boolean;
temperature?: Temperature; // CPU/NVMe temperatures
/**
* The node's primary CPU temperature in Celsius, chosen by the backend
* (models.PrimaryCPUTemperatureCelsius) and recorded under the same rule in
* the node's history. Show this value; never recompute it from `temperature`.
*/
cpuTemperature?: number;
temperatureMonitoringEnabled?: boolean | null; // Per-node temperature monitoring override
pendingUpdates?: number; // Number of pending apt updates
pendingUpdatesCheckedAt?: string; // When updates were last checked
pendingUpdatesStatus?: 'checked' | 'stale' | 'unavailable' | 'not_checked';
pendingUpdatesReason?:
'permission_denied' | 'source_unavailable' | 'check_failed' | 'node_offline';
lastSeen: string;
connectionHealth: string;
isClusterMember?: boolean; // True if part of a cluster
clusterName?: string; // Name of cluster (empty if standalone)
linkedAgentId?: string; // ID of Pulse agent running on this node (for merging)
}
export interface GuestNetworkInterface {
name?: string;
mac?: string;
addresses?: string[];
rxBytes?: number;
txBytes?: number;
}
export interface VM {
id: string;
vmid: number;
name: string;
node: string;
pool?: string;
instance: string;
status: string;
type: string;
cpu: number;
cpus: number;
memory: Memory;
disk: Disk;
disks?: Disk[];
diskStatusReason?: string;
guestAgentStatus?: string;
guestAgentExpected?: boolean;
ipAddresses?: string[];
osName?: string;
osVersion?: string;
agentVersion?: string;
networkInterfaces?: GuestNetworkInterface[];
networkIn: number;
networkOut: number;
diskRead: number;
diskWrite: number;
uptime: number;
template: boolean;
lastBackup: number;
/** A backup of this guest is running right now; lastBackup still points at the latest completed backup. */
backupInProgress?: boolean;
tags: string[] | string | null;
lock: string;
lastSeen: string;
}
export interface Container {
id: string;
vmid: number;
name: string;
node: string;
pool?: string;
instance: string;
status: string;
type: string;
cpu: number;
cpus: number;
memory: Memory;
disk: Disk;
disks?: Disk[];
ipAddresses?: string[];
osName?: string;
osVersion?: string;
agentVersion?: string;
networkInterfaces?: GuestNetworkInterface[];
networkIn: number;
networkOut: number;
diskRead: number;
diskWrite: number;
uptime: number;
template: boolean;
lastBackup: number;
/** A backup of this guest is running right now; lastBackup still points at the latest completed backup. */
backupInProgress?: boolean;
tags: string[] | string | null;
lock: string;
lastSeen: string;
// OCI container support (Proxmox VE 9.1+)
isOci?: boolean; // True if this is an OCI container
osTemplate?: string; // Template or OCI image used (e.g., "oci:docker.io/library/alpine:latest")
}
export interface DockerRuntime {
id: string;
agentId: string;
hostname: string;
displayName: string;
customDisplayName?: string;
machineId?: string;
os?: string;
kernelVersion?: string;
architecture?: string;
runtime?: string;
runtimeVersion?: string;
dockerVersion?: string;
collectionMode?: string;
cpus: number;
totalMemoryBytes: number;
uptimeSeconds: number;
cpuUsagePercent?: number;
loadAverage?: number[];
memory?: Memory;
disks?: Disk[];
networkInterfaces?: HostNetworkInterface[];
status: string;
lastSeen: number;
intervalSeconds: number;
agentVersion?: string;
containers: DockerContainer[];
services?: DockerService[];
tasks?: DockerTask[];
swarm?: DockerSwarmInfo;
tokenId?: string;
tokenName?: string;
tokenHint?: string;
tokenLastUsedAt?: number;
revokedTokenId?: string;
tokenRevokedAt?: number;
hidden?: boolean;
pendingUninstall?: boolean;
command?: DockerRuntimeCommand;
isLegacy?: boolean;
}
export interface DockerRuntimeCommand {
id: string;
type: string;
status: string;
message?: string;
createdAt: number;
updatedAt: number;
dispatchedAt?: number;
acknowledgedAt?: number;
completedAt?: number;
failedAt?: number;
failureReason?: string;
expiresAt?: number;
}
export interface DockerService {
id: string;
name: string;
stack?: string;
image?: string;
mode?: string;
desiredTasks?: number;
runningTasks?: number;
completedTasks?: number;
labels?: Record<string, string>;
endpointPorts?: DockerServicePort[];
updateStatus?: DockerServiceUpdate;
createdAt?: number;
updatedAt?: number;
}
export interface DockerServicePort {
name?: string;
protocol?: string;
targetPort?: number;
publishedPort?: number;
publishMode?: string;
}
export interface DockerServiceUpdate {
state?: string;
message?: string;
completedAt?: number;
}
export interface DockerTask {
id: string;
serviceId?: string;
serviceName?: string;
slot?: number;
nodeId?: string;
nodeName?: string;
desiredState?: string;
currentState?: string;
error?: string;
message?: string;
containerId?: string;
containerName?: string;
createdAt?: number | string; // Unix timestamp or ISO string
updatedAt?: number | string; // Unix timestamp or ISO string
startedAt?: number | string; // Unix timestamp or ISO string
completedAt?: number | string; // Unix timestamp or ISO string
}
export interface DockerSwarmInfo {
nodeId?: string;
nodeRole?: string;
localState?: string;
controlAvailable?: boolean;
clusterId?: string;
clusterName?: string;
scope?: string;
error?: string;
}
export interface DockerContainer {
id: string;
name: string;
image: string;
imageDigest?: string; // Current image digest (sha256:...)
state: string;
status: string;
health?: string;
cpuPercent: number;
memoryUsageBytes: number;
memoryLimitBytes: number;
memoryPercent: number;
uptimeSeconds: number;
restartCount: number;
exitCode: number;
createdAt: number;
startedAt?: number | null;
finishedAt?: number | null;
ports?: DockerContainerPort[];
labels?: Record<string, string>;
env?: string[];
networks?: DockerContainerNetwork[];
writableLayerBytes?: number;
rootFilesystemBytes?: number;
blockIo?: DockerContainerBlockIO;
mounts?: DockerContainerMount[];
podman?: PodmanContainerMetadata;
updateStatus?: DockerContainerUpdateStatus; // Image update detection status
}
// Update status for container images
export interface DockerContainerUpdateStatus {
updateAvailable: boolean;
currentDigest?: string;
latestDigest?: string;
lastChecked: number;
error?: string;
}
export interface DockerContainerPort {
privatePort: number;
publicPort?: number;
protocol: string;
ip?: string;
}
export interface DockerContainerNetwork {
name: string;
ipv4?: string;
ipv6?: string;
}
export interface DockerContainerBlockIO {
readBytes?: number;
writeBytes?: number;
readRateBytesPerSecond?: number;
writeRateBytesPerSecond?: number;
}
export interface DockerContainerMount {
type?: string;
source?: string;
destination?: string;
mode?: string;
rw?: boolean;
propagation?: string;
name?: string;
driver?: string;
}
export interface PodmanContainerMetadata {
podName?: string;
podId?: string;
infra?: boolean;
composeProject?: string;
composeService?: string;
composeWorkdir?: string;
composeConfigHash?: string;
autoUpdatePolicy?: string;
autoUpdateRestart?: string;
userNamespace?: string;
}
export interface Agent {
id: string;
hostname: string;
displayName: string;
platform?: string;
osName?: string;
osVersion?: string;
kernelVersion?: string;
architecture?: string;
cpuCount?: number;
cpuUsage?: number;
loadAverage?: number[];
memory: Memory;
disks?: Disk[];
diskIO?: HostDiskIO[];
networkInterfaces?: HostNetworkInterface[];
sensors?: HostSensorSummary;
raid?: HostRAIDArray[];
status: string;
uptimeSeconds?: number;
lastSeen: number;
intervalSeconds?: number;
agentVersion?: string;
commandsEnabled?: boolean; // Whether AI command execution is enabled on this agent
appliedConfig?: AgentConfigFingerprint;
agentUpdate?: AgentUpdateStatus;
agentModules?: AgentModuleStatus[];
packageUpdates?: HostPackageUpdateStatus;
storageCleanup?: HostStorageCleanupStatus;
tokenId?: string;
tokenName?: string;
tokenHint?: string;
tokenLastUsedAt?: number;
revokedTokenId?: string;
tokenRevokedAt?: number;
tags?: string[];
isLegacy?: boolean;
// Linking: When this agent is running on a known PVE entity
linkedNodeId?: string; // ID of PVE node this agent is running on
linkedVmId?: string; // ID of VM this agent is running inside
linkedContainerId?: string; // ID of container this agent is running inside
}
export interface HostPackageUpdateStatus {
supported: boolean;
manager?: string;
inventoryHash?: string;
pendingCount: number;
packages?: HostPackageUpdate[];
checkedAt?: string;
rebootRequired?: boolean;
error?: string;
}
export interface HostPackageUpdate {
name: string;
installedVersion?: string;
availableVersion?: string;
}
export interface HostStorageCleanupStatus {
supported: boolean;
provider?: string;
fingerprint?: string;
reclaimableBytes: number;
checkedAt?: string;
error?: string;
}
export interface AgentConfigFingerprint {
version: string;
hash: string;
}
export interface AgentUpdateStatus {
state: 'idle' | 'checking' | 'update-available' | 'updating' | 'error' | 'disabled';
autoUpdate: boolean;
updatedFrom?: string;
availableVersion?: string;
lastCheckedAt?: string;
lastAttemptAt?: string;
lastSuccessAt?: string;
lastError?: string;
}
export interface AgentModuleStatus {
name: string;
enabled: boolean;
state: 'disabled' | 'starting' | 'retrying' | 'running';
lastError?: string;
updatedAt: string;
}
export interface HostNetworkInterface {
name: string;
mac?: string;
addresses?: string[];
rxBytes?: number;
txBytes?: number;
speedMbps?: number;
}
export interface HostSensorSummary {
temperatureCelsius?: Record<string, number>;
fanRpm?: Record<string, number>;
powerWatts?: Record<string, number>;
additional?: Record<string, number>;
custom?: HostCustomSensorMetric[];
native?: HostNativeSensor[];
gpu?: HostGPUSensor[];
thermalState?: HostThermalState;
smart?: HostDiskSMART[]; // S.M.A.R.T. disk data
}
/**
* One lm-sensors temperature or fan input from the host agent's inventory.
* `id` is the host-scoped "<chip>/<channel>" source key (e.g.
* "applesmc-isa-0300/temp1"), not a physical-device identity; `label` is the
* chip's original feature name and is not unique. `invalid` marks an
* implausible reading, and `value` is absent when the chip gave no number.
*/
export interface HostNativeSensor {
id: string;
chip: string;
adapter?: string;
channel: string;
label: string;
kind: 'temperature' | 'fan';
unit: 'celsius' | 'rpm';
value?: number;
status: 'ok' | 'invalid';
}
export interface HostCustomSensorMetric {
id: string;
name: string;
group?: string;
subgroup?: string;
kind?: 'number' | 'boolean' | 'timestamp' | string;
unit?: string;
value?: number;
status: 'ok' | 'warning' | 'critical' | 'error' | string;
observedAt: string;
eventAt?: string;
error?: string;
alertOnError?: boolean;
stale?: boolean;
}
export interface HostGPUSensor {
id?: string;
name?: string;
temperatureCelsius?: number;
utilizationPercent?: number;
memoryUsedBytes?: number;
memoryTotalBytes?: number;
}
export interface HostThermalState {
source?: string;
pressure?: 'nominal' | 'constrained' | 'unknown' | string;
thermalWarningLevel?: number;
performanceWarningLevel?: number;
cpuPowerStatus?: number;
limitsPercent?: Record<string, number>;
}
export interface HostDiskSMART {
device: string; // Device name (e.g., sda)
model?: string; // Disk model
serial?: string; // Serial number
wwn?: string; // World Wide Name
type?: string; // Transport type: sata, sas, nvme
temperature: number; // Temperature in Celsius
health?: string; // PASSED, FAILED, UNKNOWN
standby?: boolean; // True if disk was in standby
// A non-available temperature state marks the value as last known, such as
// a host agent that stopped reporting.
collection?: import('./resource').PhysicalDiskCollectionStatus;
}
export interface HostRAIDArray {
device: string;
name?: string;
level: string;
state: string;
totalDevices: number;
activeDevices: number;
workingDevices: number;
failedDevices: number;
spareDevices: number;
uuid?: string;
devices?: HostRAIDDevice[];
rebuildPercent?: number;
rebuildSpeed?: string;
}
export interface HostRAIDDevice {
device: string;
state: string;
slot: number;
}
export interface HostDiskIO {
device: string;
readBytes?: number;
writeBytes?: number;
readOps?: number;
writeOps?: number;
readTimeMs?: number;
writeTimeMs?: number;
ioTimeMs?: number;
}
export interface AgentLookupIdentity {
id: string;
hostname: string;
displayName?: string;
status: string;
connected: boolean;
lastSeen: number;
agentVersion?: string;
}
export interface AgentLookupResponse {
success: boolean;
agent?: AgentLookupIdentity;
}
export interface ReplicationJob {
id: string;
instance: string;
jobId: string;
jobNumber?: number;
guest?: string;
guestId?: number;
guestName?: string;
guestType?: string;
guestNode?: string;
sourceNode?: string;
sourceStorage?: string;
targetNode?: string;
targetStorage?: string;
schedule?: string;
type?: string;
enabled: boolean;
state?: string;
status?: string;
lastSyncStatus?: string;
// The Go model serializes *time.Time fields as RFC3339 strings; the
// *Unix companions carry the same instants as epoch seconds.
lastSyncTime?: number | string;
lastSyncUnix?: number;
lastSyncDurationSeconds?: number;
lastSyncDurationHuman?: string;
nextSyncTime?: number | string;
nextSyncUnix?: number;
durationSeconds?: number;
durationHuman?: string;
failCount?: number;
error?: string;
comment?: string;
removeJob?: string;
rateLimitMbps?: number;
polledAt?: number;
}
export interface ReplicationJobsResponse {
data: ReplicationJob[];
meta: { total: number };
}
export interface BackupTask {
id: string;
node: string;
instance: string;
type: string;
vmid: number;
status: string;
startTime: string;
endTime?: string;
size?: number;
error?: string;
}
export interface StorageBackup {
id: string;
storage: string;
node: string;
instance: string;
type: string;
vmid: number;
time: string;
ctime: number;
size: number;
format: string;
notes?: string;
protected: boolean;
volid: string;
isPBS: boolean;
verified: boolean;
verification?: string;
/** Partial artifact a still-running backup is writing; not a completed backup. */
inProgress?: boolean;
}
export interface GuestSnapshot {
id: string;
name: string;
node: string;
instance: string;
type: string;
vmid: number;
time: string;
description?: string;
parent?: string;
vmstate: boolean;
sizeBytes?: number;
}
export interface PBSBackup {
id: string;
instance: string;
datastore: string;
namespace: string;
backupType: string;
vmid: string;
backupTime: string;
size: number;
protected: boolean;
verified: boolean;
/** Incomplete snapshot with no manifest; never a completed backup. */
inProgress?: boolean;
/** Whether the collector successfully observed PBS's current running-task set. */
writeActivityObserved?: boolean;
/** Whether a running backup or sync task currently accounts for this incomplete snapshot. */
writeActive?: boolean;
verificationRaw?: unknown;
comment?: string;
files: string[];
owner?: string;
}
export interface PBSBackupsPayload {
backups: PBSBackup[];
}
export interface PBSBackupsResponse {
data: PBSBackupsPayload;
meta: {
totalBackups: number;
};
}
export interface PVEBackupsPayload {
backupTasks: BackupTask[];
storageBackups: StorageBackup[];
guestSnapshots: GuestSnapshot[];
}
export interface PVEBackupsResponse {
data: PVEBackupsPayload;
meta: {
totalBackupTasks: number;
totalStorageBackups: number;
totalGuestSnapshots: number;
};
}
export interface Storage {
id: string;
name: string;
node: string;
instance: string;
type: string;
status: string;
total: number;
used: number;
free: number;
usage: number;
content: string;
shared: boolean;
enabled: boolean;
active: boolean;
// RFC3339 timestamp of the last poll that delivered this entry; absent = never seen
lastSeen?: string;
// Added for deduplication in storage view
nodes?: string[];
nodeIds?: string[];
nodeCount?: number;
pbsNames?: string[];
pool?: string;
// Canonical platform key (e.g. `vmware-vsphere`, `truenas`, `proxmox-pve`)
// set by source adapters that know what platform owns the storage
// record. Storage filter chips and platform-page source filters
// resolve against this when present, so on-disk `type` like `vsan`
// or `vmfs` does not silently bucket VMware datastores under their
// technology label instead of the canonical platform.
platform?: string;
// ZFS pool status
zfsPool?: ZFSPool;
}
export interface CephCluster {
id: string;
instance: string;
name: string;
fsid?: string;
health: string;
healthMessage?: string;
totalBytes: number;
usedBytes: number;
availableBytes: number;
usagePercent: number;
numMons: number;
numMgrs: number;
numOsds: number;
numOsdsUp: number;
numOsdsIn: number;
numPGs: number;
pools?: CephPool[];
services?: CephServiceStatus[];
lastUpdated: number;
}
export interface CephPool {
id: number;
name: string;
storedBytes: number;
availableBytes: number;
objects: number;
percentUsed: number;
}
export interface CephServiceStatus {
type: string;
running: number;
total: number;
message?: string;
}
export interface ZFSPool {
name: string;
state: string; // ONLINE, DEGRADED, FAULTED, OFFLINE, REMOVED, UNAVAIL
status: string; // Healthy, Degraded, Faulted, etc.
scan: string; // Current scan status (scrub, resilver, none)
scanDetails?: ZFSScan;
readErrors: number;
writeErrors: number;
checksumErrors: number;
devices: ZFSDevice[];
datasets?: ZFSDataset[];
}
export interface ZFSDataset {
name: string;
type?: 'filesystem' | 'volume' | string;
mountpoint?: string;
usedBytes?: number;
availableBytes?: number;
referencedBytes?: number;
}
export interface ZFSScan {
function?: string;
state?: string;
percentage?: number;
errors?: number;
bytesExamined?: number;
bytesToProcess?: number;
totalSecondsRemaining?: number;
startedAt?: string;
endedAt?: string;
}
export interface ZFSDevice {
name: string;
type: string; // disk, mirror, raidz, raidz2, raidz3, spare, log, cache
role?: string;
parent?: string;
guid?: string;
disk?: string;
path?: string;
state: string; // ONLINE, DEGRADED, FAULTED, OFFLINE, REMOVED, UNAVAIL
readErrors: number;
writeErrors: number;
checksumErrors: number;
missing?: boolean;
message?: string;
}
export interface PBSInstance {
id: string;
name: string;
host: string;
nodeName?: string; // Hostname the PBS node reports about itself
guestURL?: string; // Optional guest-accessible URL (for navigation)
status: string;
version: string;
cpu: number;
memory: number;
memoryUsed: number;
memoryTotal: number;
uptime: number;
datastores: PBSDatastore[];
backupJobs: PBSBackupJob[];
syncJobs: PBSSyncJob[];
verifyJobs: PBSVerifyJob[];
pruneJobs: PBSPruneJob[];
garbageJobs: PBSGarbageJob[];
jobHealthEvidence?: PBSJobHealthEvidence[];
connectionHealth: string;
lastSeen: string;
}
export interface PMGInstance {
id: string;
name: string;
host: string;
guestURL?: string; // Optional guest-accessible URL (for navigation)
status: string;
version: string;
nodes?: PMGNodeStatus[];
mailStats?: PMGMailStats;
mailCount?: PMGMailCountPoint[];
spamDistribution?: PMGSpamBucket[];
quarantine?: PMGQuarantineTotals;
relayDomains?: PMGRelayDomain[];
domainStats?: PMGDomainStat[];
domainStatsAsOf?: string;
connectionHealth: string;
lastSeen: string;
lastUpdated: string;
}
export interface PMGRelayDomain {
domain: string;
comment?: string;
}
export interface PMGDomainStat {
domain: string;
mailCount: number;
spamCount: number;
virusCount: number;
bytes?: number;
}
export interface PMGNodeStatus {
name: string;
status: string;
role?: string;
uptime?: number;
loadAvg?: string;
queueStatus?: PMGQueueStatus;
}
export interface PMGMailStats {
timeframe: string;
countTotal: number;
countIn: number;
countOut: number;
spamIn: number;
spamOut: number;
virusIn: number;
virusOut: number;
bouncesIn: number;
bouncesOut: number;
bytesIn: number;
bytesOut: number;
greylistCount: number;
junkIn: number;
averageProcessTimeMs: number;
rblRejects: number;
pregreetRejects: number;
updatedAt: string;
}
export interface PMGMailCountPoint {
timestamp: string;
count: number;
countIn: number;
countOut: number;
spamIn: number;
spamOut: number;
virusIn: number;
virusOut: number;
rblRejects: number;
pregreet: number;
bouncesIn: number;
bouncesOut: number;
greylist: number;
index: number;
timeframe: string;
windowStart?: string;
windowEnd?: string;
}
export interface PMGSpamBucket {
score: string;
count: number;
}
export interface PMGQuarantineTotals {
spam: number;
virus: number;
attachment?: number;
blacklisted?: number;
}
export interface PMGQueueStatus {
active: number;
deferred: number;
hold: number;
incoming: number;
total: number;
oldestAge: number;
updatedAt: string;
}
export interface PBSDatastore {
name: string;
total: number;
used: number;
free: number;
usage: number;
status: string;
error: string;
namespaces: PBSNamespace[];
deduplicationFactor?: number;
}
export interface PBSNamespace {
path: string;
parent: string;
depth: number;
}
export interface PBSBackupJob {
id: string;
store: string;
type: string;
vmid?: string;
lastBackup: string;
nextRun?: string;
status: string;
error?: string;
}
export interface PBSSyncJob {
id: string;
store: string;
remote: string;
status: string;
lastSync: string;
nextRun?: string;
error?: string;
}
export interface PBSVerifyJob {
id: string;
store: string;
status: string;
lastVerify: string;
nextRun?: string;
error?: string;
}
export interface PBSPruneJob {
id: string;
store: string;
status: string;
lastPrune: string;
nextRun?: string;
error?: string;
}
export interface PBSGarbageJob {
id: string;
store: string;
status: string;
lastGarbage: string;
nextRun?: string;
removedBytes?: number;
error?: string;
}
export interface PBSJobHealthFreshness {
observedAt: string;
lastRunEndTime?: string;
nextRun?: string;
ageSeconds?: number;
state?: string;
}
export interface PBSJobHealthEvidence {
id: string;
family: string;
store?: string;
remote?: string;
namespace?: string;
schedule?: string;
comment?: string;
enabled?: boolean;
'last-run-state'?: string;
'last-run-upid'?: string;
'last-run-endtime'?: number;
'next-run'?: number;
upid?: string;
'worker-type'?: string;
'worker-id'?: string;
'task-status'?: string;
'task-starttime'?: number;
'task-endtime'?: number;
confidence: string;
evidenceSource?: string;
evidenceScope?: string;
freshness?: PBSJobHealthFreshness;
posture?: string;
postureReason?: string;
error?: string;
}
/** Server-owned provenance of the selected guest-memory reading. */
export interface MemoryObservation {
/** current, last-known or unavailable. Unrecognised/absent states are unknown. */
state: string;
source: string;
/** Original source time, never the refreshed resource LastSeen. */
observedAt?: string;
}
export interface Memory {
total: number;
used: number;
free: number;
/** Reclaimable buff/cache (available - truly free); used + cache + free ≈ total. */
cache?: number;
/** Total is known, but no cache-aware source can establish current usage. */
usageUnavailable?: boolean;
observation?: MemoryObservation;
usage: number;
balloon?: number;
swapUsed?: number;
swapTotal?: number;
}
// Models both the legacy state payload (models.Disk, numerics always present,
// filesystem under `type`) and the unified resources facet (DiskInfo, every
// field omitempty so zero values arrive absent, filesystem under `filesystem`).
// Consumers must default absent numerics rather than assume presence (#1663).
export interface Disk {
total?: number;
used?: number;
free?: number;
usage?: number;
mountpoint?: string;
type?: string;
filesystem?: string;
device?: string;
}
export interface SMARTAttributes {
powerOnHours?: number;
powerCycles?: number;
reallocatedSectors?: number;
pendingSectors?: number;
offlineUncorrectable?: number;
udmaCrcErrors?: number;
percentageUsed?: number;
availableSpare?: number;
mediaErrors?: number;
unsafeShutdowns?: number;
}
export interface PhysicalDisk {
id: string;
node: string;
instance: string;
devPath: string;
device?: string;
model: string;
serial: string;
wwn: string;
type: 'nvme' | 'sata' | 'sas' | string;
controller?: string;
target?: string;
size: number;
health: 'PASSED' | 'FAILED' | 'UNKNOWN' | string;
wearout: number; // 0-100, 100 is best, -1 when the controller doesn't report it
temperature: number;
rpm: number;
used: string;
lastChecked: string;
smartAttributes?: SMARTAttributes;
io?: {
device?: string;
readBytes?: number;
writeBytes?: number;
readOps?: number;
writeOps?: number;
readTimeMs?: number;
writeTimeMs?: number;
ioTimeMs?: number;
};
collection?: import('./resource').PhysicalDiskCollectionStatus;
}
export interface CPUInfo {
model: string;
cores: number;
sockets: number;
mhz: string;
}
export interface Temperature {
cpuPackage?: number; // CPU package temperature (primary metric)
cpuMax?: number; // Highest core temperature
cpuMin?: number; // Minimum recorded CPU temperature (since monitoring started)
cpuMaxRecord?: number; // Maximum recorded CPU temperature (since monitoring started)
minRecorded?: string; // When minimum temperature was recorded
maxRecorded?: string; // When maximum temperature was recorded
cores?: CoreTemp[]; // Individual core temperatures
gpu?: GPUTemp[]; // GPU temperatures
nvme?: NVMeTemp[]; // NVMe drive temperatures
available: boolean; // Whether any temperature data is available
hasCPU?: boolean; // Whether CPU temperature data is available
hasGPU?: boolean; // Whether GPU temperature data is available
hasNVMe?: boolean; // Whether NVMe temperature data is available
legacySensorsFormat?: boolean; // SSH payload was raw `sensors -j` (pre-rc.6 node setup); SMART disk temps cannot arrive until the setup script is re-run
lastUpdate: string; // When this data was collected
}
export interface CoreTemp {
core: number;
temp: number;
}
export interface GPUTemp {
device: string; // GPU device identifier (e.g., "amdgpu-pci-0400")
edge?: number; // Edge temperature
junction?: number; // Junction/hotspot temperature
mem?: number; // Memory temperature
}
export interface NVMeTemp {
device: string;
temp: number;
}
export interface Metric {
timestamp: string;
type: string;
id: string;
values: Record<string, number | string | boolean>;
}
export interface Performance {
apiCallDuration: Record<string, number>;
lastPollDuration: number;
pollingStartTime: string;
totalApiCalls: number;
failedApiCalls: number;
cacheHits?: number;
cacheMisses?: number;
}
export interface Stats {
startTime: string;
uptime: number;
pollingCycles: number;
webSocketClients: number;
version: string;
}
// Alert types
export type AlertFailureClass =
| 'runtime'
| 'network-path'
| 'application-response'
| 'certificate'
| 'dependency'
| 'evidence-coverage';
export interface AlertCorrelationObservation {
alertId: string;
resourceId: string;
resourceName: string;
failureClass: AlertFailureClass;
level: 'info' | 'warning' | 'critical';
observedAt: string;
evidenceIds?: string[];
}
export interface AlertCorrelation {
key: string;
kind: 'shared-system' | 'infrastructure-incident';
role: 'primary' | 'supporting';
reason: string;
failureClass?: AlertFailureClass;
inference?: 'supported-cause' | 'observation-set';
primaryAlertId?: string;
primaryResourceId?: string;
affectedResourceIds?: string[];
observations?: AlertCorrelationObservation[];
}
export interface Alert {
id: string;
type: string;
level: 'info' | 'warning' | 'critical';
resourceId: string;
canonicalSpecId?: string;
canonicalKind?: string;
canonicalState?: string;
resourceName: string;
node: string;
nodeDisplayName?: string;
instance: string;
message: string;
/** The message without its subject, for rows that already name the resource. */
summary?: string;
value: number;
threshold: number;
startTime: string;
lastSeen?: string;
acknowledged: boolean;
ackTime?: string;
ackUser?: string;
correlation?: AlertCorrelation;
metadata?: Record<string, unknown>;
/**
* Live evaluation behind an open threshold alert. `value`, `message` and
* `lastSeen` keep the last reading that met the trigger; this is the
* reading being evaluated now and why the alert has not cleared.
*/
metricStatus?: MetricAlertStatus;
operationalRecord?: OperationalRecord;
latestTransition?: LifecycleTransition;
transitions?: LifecycleTransition[];
evidence?: EvidenceEnvelope[];
// Set only on a closed alert whose condition did not clear, such as a node
// metric handed to its Pulse agent. Absent for an ordinary recovery.
resolution?: AlertResolution;
}
// Why an alert closed without recovering (alerts.AlertResolution).
export interface AlertResolution {
reason: 'moved_to_agent' | (string & {});
successorResourceId?: string;
successorName?: string;
// The alert engine's one-line account; carried on state snapshots only.
summary?: string;
}
export interface ResolvedAlert extends Alert {
resolvedTime: string;
}
export type MetricAlertPhase = 'breaching' | 'latched' | 'recovering';
export interface MetricAlertStatus {
phase: MetricAlertPhase;
/** Value compared with the rule (the average for a rolling-average rule). */
value: number;
/** Latest sample when the rule evaluates a rolling average. */
rawValue?: number;
evaluationWindowSeconds?: number;
unit?: string;
observedAt: string;
/** Dates Alert.value, not the newer held/recovering observation; absent when unknown. */
lastBreachAt?: string;
/** Opens at or above this value. */
trigger: number;
/** Clears after staying at or below this value for recoveryDelaySeconds. */
recovery: number;
recoveryDelaySeconds?: number;
recoveryStartedAt?: string;
recoveryElapsedSeconds?: number;
}
// One entry from the append-only alert event log
// (GET /api/alerts/events): a lifecycle transition or a notification
// decision, including suppressions with the mechanism that held them.
export interface AlertEvent {
id: number;
occurredAt: string;
type: string;
alertId: string;
resourceId?: string;
resourceName?: string;
alertType?: string;
level?: string;
reason?: string;
message?: string;
details?: Record<string, string>;
}
// Read-only projection of notification delivery policy for one active alert,
// from GET /api/alerts/delivery-diagnosis.
export interface AlertDeliveryDiagnosis {
alertIdentifier: string;
alertId: string;
trackingKey: string;
status: 'would_send' | 'deferred' | 'suppressed';
reason: string;
message: string;
alertType: string;
level: 'info' | 'warning' | 'critical';
resourceId?: string;
resourceName?: string;
node?: string;
notificationsEnabled: boolean;
activationState: string;
cooldownMinutes: number;
maxAlertsHour: number;
recentAlertsInHour: number;
flappingActive: boolean;
flappingHistoryInWindow: number;
flappingThreshold: number;
flappingWindowSeconds: number;
lastNotified?: string;
nextEligibleAt?: string;
quietHoursReplayAt?: string;
suppressedUntil?: string;
}
export interface IncidentEvent {
source?: string;
evidence?: ResourceChange;
id: string;
type: string;
timestamp: string;
summary: string;
details?: Record<string, unknown>;
}
export interface IncidentHistoryCoverage {
source: string;
observedSince: string;
observedBefore: string;
changeLimit: number;
hasMoreChanges: boolean;
hasMoreIncidents: boolean;
}
export interface Incident {
history?: IncidentHistoryCoverage;
id: string;
alertIdentifier: string;
alertType: string;
level: string;
resourceId: string;
resourceName: string;
resourceType?: string;
node?: string;
instance?: string;
message?: string;
status: string;
openedAt: string;
closedAt?: string;
acknowledged: boolean;
ackUser?: string;
ackTime?: string;
events?: IncidentEvent[];
}
// WebSocket message types
export type WSMessage =
| { type: 'initialState'; data: State }
| { type: 'rawData'; data: StateUpdate }
| {
type: 'stateTooLarge';
data: {
supersedes: 'initialState' | 'rawData';
bytes?: number;
maxBytes: number;
resourceCount: number;
hydrateFrom: '/api/state';
};
}
| { type: 'error'; error: string }
| { type: 'ping'; data?: unknown }
| { type: 'pong'; data?: unknown }
| { type: 'welcome'; data?: unknown }
| { type: 'alert'; data: Alert }
| { type: 'alertResolved'; data: { alertIdentifier: string } }
| { type: 'settingsUpdate'; data: { theme?: string } }
| {
type: 'update:progress';
data: {
phase: string;
progress: number;
message: string;
};
}
| {
type: 'node_auto_registered';
data: {
type: string;
source?: string;
host: string;
name: string;
tokenId: string;
hasToken: boolean;
verifySSL?: boolean;
status?: string;
};
}
| { type: 'node_deleted'; data: { nodeType: string } }
| { type: 'nodes_changed'; data?: unknown }
| {
type: 'discovery_update';
data: {
servers: Array<{
ip: string;
port: number;
type: string;
version: string;
hostname?: string;
release?: string;
}>;
errors?: string[];
timestamp?: number;
immediate?: boolean;
scanning?: boolean;
cached?: boolean;
};
}
| {
type: 'discovery_started';
data?: {
subnet?: string;
timestamp?: number;
scanning?: boolean;
};
}
| {
type: 'discovery_complete';
data?: {
timestamp?: number;
scanning?: boolean;
};
};