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. 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: qemuDomainInterfaceStats(): ... if (virDomainObjCheckActive(vm) < 0) goto cleanup; qemuDomainMemoryStatsInternal(): ... if (virDomainObjCheckActive(vm) < 0) return -1; 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 ...? 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 virDomainPinVcpu virDomainGetIOThreadInfo virDomainGetJobInfo (this is the best because it explicitly says "return an error if the domain is not active" virDomainGetJobStats (same virtuous description) virDomainGetMaxVcpus virDomainGetSecurityLabel virDomainGetSecurityLabelList virDomainGetVcpus (not great: "This call may fail on an inactive domain" May? Depending on what? Driver?) virDomainGetVcpusFlags virDomainPinEmulator (again "may fail if domain is not alive" - is it really conditional, as opposed to "will fail for transient domains"?) virDomainPinVcpu ("can only be called on an active domain" -> would be better to say "returns an error if the domain is not active") virDomainSetMemoryFlags ("will wail if domain is not active") -Ok, clear. virDomainSetMemoryStatsPeriod (same) virDomainSetVcpus virDomainSetVcpusFlags 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 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. Thanks, -- Claudio Fontana Engineering Manager Virtualization, SUSE Labs Core SUSE Software Solutions Italy Srl
