From 704ae106ea27a7ab2c6682c71c092a53fe890752 Mon Sep 17 00:00:00 2001
From: Pulse Monitor <pulse@pulse-monitor.dev>
Date: Mon, 25 Aug 2025 09:12:25 +0000
Subject: [PATCH] improve: add better diagnostics for guest agent issues

- Add verification steps for qemu-guest-agent service status
- Clarify that the service is socket-activated (not systemctl enable)
- Add diagnostic commands users can run to verify agent is working
- Update FAQ with correct troubleshooting steps for agent issues

This helps users like @RLSinRFV who were trying to enable the service
when it's actually socket-activated and should start automatically.
---
 docs/FAQ.md                    | 6 +++++-
 internal/monitoring/monitor.go | 4 ++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/FAQ.md b/docs/FAQ.md
index 14366730a..753512be0 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -105,7 +105,11 @@ This is usually one of these issues:
 **All versions**: 
 - Guest agent must be installed: `apt install qemu-guest-agent` (Linux) or virtio-win tools (Windows)
 - Enable in VM Options → QEMU Guest Agent
-- Restart the VM after installing
+- The service should start automatically after install. To verify:
+  - Check status: `systemctl status qemu-guest-agent`
+  - If not running: `systemctl start qemu-guest-agent` (not `enable` - it's socket-activated)
+  - Alternative check: `ps aux | grep qemu-ga`
+- Restart the VM after installing/enabling in Proxmox options
 
 ### How do I see real disk usage for VMs?
 Install QEMU Guest Agent in your VMs:
diff --git a/internal/monitoring/monitor.go b/internal/monitoring/monitor.go
index 3aaa48725..b09036332 100644
--- a/internal/monitoring/monitor.go
+++ b/internal/monitoring/monitor.go
@@ -962,6 +962,10 @@ func (m *Monitor) pollVMsAndContainersEfficient(ctx context.Context, instanceNam
 									Str("vm", res.Name).
 									Int("vmid", res.VMID).
 									Msg("Guest agent enabled in VM config but not running inside guest OS. Install and start qemu-guest-agent in the VM")
+								log.Info().
+									Str("instance", instanceName).
+									Str("vm", res.Name).
+									Msg("To verify: ssh into VM and run 'systemctl status qemu-guest-agent' or 'ps aux | grep qemu-ga'")
 							} else if strings.Contains(errMsg, "timeout") {
 								log.Info().
 									Str("instance", instanceName).