[PATCH-SERIES qemu-server 0/2] backup: improve logging upon backup start

[PATCH-SERIES qemu-server 0/2] backup: improve logging upon backup start

[Fiona Ebner]

Add some context to the error message when a VMA backup fails upon
backup start.

Clarify that the QMP command to start a backup happens in between
freeze and thaw.

qemu-server:

Fiona Ebner (2):
  backup: vma: add context to error message upon backup start
  backup: log backup start via QMP command to avoid confusion about
    freeze/thaw

 src/PVE/VZDump/QemuServer.pm | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)


Summary over all repositories:
  1 files changed, 3 insertions(+), 1 deletions(-)

-- 
Generated by git-murpp 0.5.0

[PATCH qemu-server 1/2] backup: vma: add context to error message upon backup start

[Fiona Ebner]

Upon failure, the queue_execute() function returns the error message
from QEMU directly:

> INFO: issuing guest-agent 'fs-freeze' command
> INFO: issuing guest-agent 'fs-thaw' command
> ERROR: <error message from QEMU>

Many such error messages mention internal QEMU functions and can be
hard to interpret without knowledge of QEMU.

Add some context to the error message to improve this:

> INFO: issuing guest-agent 'fs-freeze' command
> INFO: issuing guest-agent 'fs-thaw' command
> ERROR: executing QMP command to start backup failed - <error message from QEMU>

In case of PBS and provider-based backups, mon_cmd() is used, which
already includes the information which failed QMP command it is, for
example, for PBS:

> ERROR: VM 100 qmp command 'backup' failed - <error message from QEMU>

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
 src/PVE/VZDump/QemuServer.pm | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/PVE/VZDump/QemuServer.pm b/src/PVE/VZDump/QemuServer.pm
index 0681661d..2d55fbfa 100644
--- a/src/PVE/VZDump/QemuServer.pm
+++ b/src/PVE/VZDump/QemuServer.pm
@@ -1031,7 +1031,7 @@ sub archive_vma {
             $self->qga_fs_thaw($vmid);
         }
 
-        die $qmperr if $qmperr;
+        die "executing QMP command to start backup failed - $qmperr" if $qmperr;
         die $qmpclient->{errors}->{$vmid} if $qmpclient->{errors}->{$vmid};
 
         if ($cpid) {
-- 
2.47.3

[PATCH qemu-server 2/2] backup: log backup start via QMP command to avoid confusion about freeze/thaw

[Fiona Ebner]

Curently, a backup task log looks like:

> INFO: issuing guest-agent 'fs-freeze' command
> INFO: issuing guest-agent 'fs-thaw' command
> INFO: started backup task 'beebb719-bdb8-4de8-9d34-5cbf182cea3e'

or in case of a failure during backup start:

> INFO: issuing guest-agent 'fs-freeze' command
> INFO: issuing guest-agent 'fs-thaw' command
> ERROR: VM 100 qmp command 'backup' failed - <error message from QEMU>

Both might suggest that the thaw operation and starting the backup
happen in the wrong order, which can lead to confusion. Add a log line
when issuing the 'backup' QMP command to clarify that this is not the
case.

After the patch, the task logs look like:

> INFO: issuing guest-agent 'fs-freeze' command
> INFO: starting backup via QMP command
> INFO: issuing guest-agent 'fs-thaw' command
> INFO: started backup task 'e4e961c1-661b-4971-aefb-6715fd6a0d70'

or in case of a failure during backup start:

> INFO: issuing guest-agent 'fs-freeze' command
> INFO: starting backup via QMP command
> INFO: issuing guest-agent 'fs-thaw' command
> ERROR: VM 100 qmp command 'backup' failed - <error message from QEMU>

In case of provider-based backups, there already is a log-message
between freeze and thaw:

> INFO: issuing guest-agent 'fs-freeze' command
> INFO: setting up snapshot-access for backup
> INFO: issuing guest-agent 'fs-thaw' command

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
 src/PVE/VZDump/QemuServer.pm | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/PVE/VZDump/QemuServer.pm b/src/PVE/VZDump/QemuServer.pm
index 2d55fbfa..cdf20219 100644
--- a/src/PVE/VZDump/QemuServer.pm
+++ b/src/PVE/VZDump/QemuServer.pm
@@ -841,6 +841,7 @@ sub archive_pbs {
 
         $params->{timeout} = 125; # give some time to connect to the backup server
 
+        $self->loginfo("starting backup via QMP command");
         my $res = eval { mon_cmd($vmid, "backup", %$params) };
         my $qmperr = $@;
         $backup_job_uuid = $res->{UUID} if $res;
@@ -1024,6 +1025,7 @@ sub archive_vma {
 
         my $fs_frozen = $self->qga_fs_freeze($task, $vmid);
 
+        $self->loginfo("starting backup via QMP command");
         eval { $qmpclient->queue_execute(30) };
         my $qmperr = $@;
 
-- 
2.47.3

applied: [PATCH-SERIES qemu-server 0/2] backup: improve logging upon backup start

[Thomas Lamprecht]

On Thu, 26 Mar 2026 12:31:40 +0100, Fiona Ebner wrote:
> Add some context to the error message when a VMA backup fails upon
> backup start.
> 
> Clarify that the QMP command to start a backup happens in between
> freeze and thaw.
> 
> qemu-server:
> 
> [...]

Applied, thanks!

[1/2] backup: vma: add context to error message upon backup start
      commit: d83de8f21356808a800dbd4cff0d2d8e770fb0c4
[2/2] backup: log backup start via QMP command to avoid confusion about freeze/thaw
      commit: b9b7d0535dc63ae3fced940a9a2d25baa08f1c5b