On Thu, Apr 23, 2026 at 12:28:40 +0200, Claudio Fontana wrote:

Hello,

at least for virDomainInterfaceStats() and virDomainMemoryStats() they actually seem to fail when called on a non active domain (for example a shutoff domain).

It would be beneficial to document clearly which domain states are allowed when calling the APIS in

https://libvirt.org/html/libvirt-libvirt-domain.html

because it can be also reasonable to assume, for example, that a call would just return empty values when the domain is not active.

IMO that depends on whether the resource that you want to report stats even exists. E.g. the bulk stats API (backing virsh domstats) reports some data even if the VM is offline. One example is some disk image statistics as the image itself exists.

It is not 100% clear from the code either, because the domain state is not enforced at the core libvirt level, but rather by the QEMU driver implementation:

liveness check must happen at the driver impl level because you need to be able to do it after obtaining lock on the VM object. If you'd use a public API (without taking the lock and possibly job) you 'd have a TOCTOU race since the VM could have stopped/started.

qemuDomainInterfaceStats(): ... if (virDomainObjCheckActive(vm) < 0) goto cleanup;

qemuDomainMemoryStatsInternal(): ... if (virDomainObjCheckActive(vm) < 0) return -1;

E.g. the interface itself doesn't exist if the VM is running there isn't much to report. Once could argue though that an offline VM uses 0 ram.

so could a different driver decide that InterfaceStats or MemoryStats calls _are_ allowed for shutoff domains, possibly returning empty values, or latest run results, or ...?

Theoretically yes. Practically it doesn't make much sense. And a hard no for reporting stale data.

If it is 100% the case that these APIs are for active domains only, I think it could be documented in the APIs; not finding it there could make one assume that these are fine to call, especially since others _are_ documented in terms of active/inactivey:

virDomainAddIOThread virDomainAttachDevice virDomainDelIOThread virDomainDelThrottleGroup virDomainGetBlockInfo virDomainGetIOThreadInfo

All of the above work on both live and inactive configs

virDomainPinVcpu

This one works only on live VMs, but the virDomainPinVcpuFlags variant works on both.

virDomainGetJobInfo (this is the best because it explicitly says "return an error if the domain is not active" virDomainGetJobStats (same virtuous description)

virDomainGetMaxVcpus

Same as virDomainPinVcpu, there's virDomainGetVcpusFlags which works everywhere.

virDomainGetSecurityLabel virDomainGetSecurityLabelList

These "work" on inactive VMs, return nothing for qemu though. Arguably other drivers could have a value, even qemu driver could report something if it's explicitly configured.

virDomainGetVcpus (not great: "This call may fail on an inactive domain" May? Depending on what? Driver?)

Well at least qemu driver does error out.

virDomainGetVcpusFlags

This one is fun though, because it depends on flags if it works on inactive VM or not :) (e.g. with VIR_DOMAIN_VCPU_GUEST your VM has to be active, without that flag you get an answer even for inactive VM :)

virDomainPinEmulator (again "may fail if domain is not alive" - is it really conditional, as opposed to "will fail for transient domains"?)

Well, because it doesn't fail for inactive qemu domains.

virDomainPinVcpu ("can only be called on an active domain" -> would be better to say "returns an error if the domain is not active")

Sure, but also use qemuDomainPinVcpuFlags which works on active VMs too.

virDomainSetMemoryFlags ("will wail if domain is not active") -Ok, clear. virDomainSetMemoryStatsPeriod (same)

virDomainSetVcpus virDomainSetVcpusFlags

Same fun with flags as with the getter.

virDomainSuspend (but not very clear: "Suspends an active domain". Does it return an error if the domain is not active? Or just do nothing?)

virDomainUndefine virDomainUndefineFlags

Both do work on inactive VMs. These have another dimension of fun, because if the VM is active, it keeps being present and active. If you shut it down it vanishes. (same as starting it without persistent config directly)

Maybe a good bite-sized task to queue that can create a lot of value. I would suggest an additional table generated for each API mentioning allowed domain states, or something to that effect.

This would also need to be per-driver because it in many cases depends on the actual implementation. I don't think there's a way around it which also makes it extremely impractical to implement.