Monitoring & diagnostics

NexoVirt collects node and guest metrics in the background and keeps a searchable record of what happened, so pages open instantly and every failure can be traced to its real cause. The pages on this page are admin-only.

The dashboard

Dashboard is a panel-wide overview built from stored data, without a live Proxmox call:

• A Getting started checklist (add a node, set up the agent, start the background workers, create a guest) that disappears once everything is done.
• KPI cards: Guests (with the number running), Nodes online (with clusters, offline nodes and agent problems), Open alerts and Suspended (plan guests on hold).
• One card per connection: a single node, or a cluster with its nodes as links. Each card shows aggregate CPU, RAM and disk bars, network up/down, and Cluster, Down or Maintenance badges.
• Latest activity (recent guest events) and Open alerts, with View all to the alerts inbox.

Metrics collection

The metrics collector (metrics:collect, started every minute by cron) samples guests and nodes into the database. Configure it under Settings > Metrics:

Setting	Default
Guest sampling interval (seconds)	5
Node sampling interval (seconds)	30
Guest metrics retention (hours)	24
Node metrics retention (days)	180

Old samples are removed by the daily metrics:prune job, which also enforces the log retention below. Because metrics are stored, charts never wait on Proxmox and keep working while a node is briefly unreachable.

• Node pages show CPU, Memory, Storage and Uptime cards with network rates, refreshed every 5 seconds.
• Guest detail pages show CPU, RAM and disk usage bars, per-drive storage usage and live charts of the last 30 minutes, refreshed every 5 seconds.

Accurate RAM and disk

For running QEMU VMs with the guest agent, NexoVirt replaces Proxmox’s memory figure (which counts page cache and often looks like ~100% used) with the guest’s real usage, and shows real per-drive disk usage. Percentages are computed against the guest’s configured allotment.

Logs

Monitoring > Logs is the unified Event log: actions, errors and coded failures from across the panel (sources: panel, audit, diag, guest). It refreshes every 20 seconds and can be searched and filtered by Level, Source and Area. View opens the full technical detail of an entry.

Export CSV downloads the log for a date range (From, To) and optional area.

Info and notice entries are kept for 90 days, warnings and errors for 365 days.

Error codes

Errors carry a stable code in the form NX-<AREA>-<NNNN>. Error-code reference on the Logs page lists every code with its title, when it happens and what to do. The same list is in the Error codes reference.

Diagnostics

Monitoring > Diagnostics has three tabs:

• Panel errors: every failed action with what you saw and the real cause (the Proxmox error and the exact request). Click View for the detail. Kept for 30 days.
• System logs and PVE logs: recent system and Proxmox daemon log lines, read live from the agent of the node you select (read-only). Use Refresh to load them again.

Error notifications in the panel also carry a Details link to the same technical detail, and each guest’s Activity tab shows the real error of failed actions.

Jobs

Monitoring > Jobs lists every queued guest job (create, reinstall, delete, power, password, restore, migration) with its status (queued, running, done, failed) and error. Job payloads are never shown.

Audit log

Monitoring > Audit log records security, account and infrastructure actions with the user, target, detail and source IP: logins and logouts, impersonation, node create and delete, user and admin changes, 2FA changes, node console sessions, settings changes and more. Filter by action and use Export CSV with a date range.

System status

System > System status shows whether each background worker is running, based on its last heartbeat: metrics collector, inventory collector, provisioning and migration workers, alerting engine, mail outbox, firewall collector, node facts scanner, console proxy watchdog, update channel and PBS prune. Each row shows its status (running, down, disabled), last seen time, expected cadence and command.

Down usually means the cron jobs are not installed (install them with deploy/install-cron.sh); disabled means the feature is turned off. Run now starts one pass of a worker immediately.

Prometheus & Grafana

Settings > Prometheus & Grafana exposes the panel’s metrics at /metrics for Prometheus:

1. Tick Enable the /metrics scrape endpoint and optionally set an IP allowlist (IPs or IPv4 CIDRs, comma-separated). Click Save.
2. Click Generate token. The scrape token is shown once and stored only as a hash. Rotate token replaces it.
3. Add the scrape job shown on the page to prometheus.yml (the token goes in authorization.credentials).
4. Download Grafana dashboard (JSON) and import it in Grafana with your Prometheus data source.

The endpoint exports node, guest, plan and alert metrics (for example nexovirt_node_cpu_ratio, nexovirt_guest_up, nexovirt_alerts_active).

Log forwarding

Settings > Log forwarding streams the event log to a SIEM. Tick Enable log forwarding, set the Webhook URL and the Minimum level, then Save settings. Events at or above that level are POSTed as {events:[...]} JSON by the logs:forward cron job (best-effort). Send test sends a test event.

Alerts & webhooksTurn metric thresholds and events into notifications.

Error codesWhat each NX-* code means.

CLI & daemonsThe background workers and their cron jobs.