openkylin
/
libvirt
mirror of https://gitee.com/openkylin/libvirt.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

getstats: improve documentation 

At least with 'virsh domstats --block' on an offline domain, we
currently output no stats even though we recognize the stat
category.  Although a later patch will improve this situation,
it is better to document that this is expected behavior.

Also, while the current implementation rejects filtering flags
for virDomainListGetStats, this limitation may be lifted in the
future and we do not enforce it at the API level.

* src/libvirt-domain.c (virConnectGetAllDomainStats): Document
that recognized stats might not be reported.
(virDomainListGetStats): Likewise, and tweak filtering documentation.

Signed-off-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Eric Blake 2014-12-04 21:39:55 -07:00
parent 2f61602edb
commit f301fe77c6
1 changed files with 11 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
src/libvirt-domain.c
View File

@ -10940,7 +10940,11 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
*
* Specifying VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS as @flags makes
* the function return error in case some of the stat types in @stats were
* not recognized by the daemon.
* not recognized by the daemon. However, even with this flag, a hypervisor
* may omit individual fields within a known group if the information is not
* available; as an extreme example, a supported group may produce zero
* fields for offline domains if the statistics are meaningful only for a
* running domain.
*
* Similarly to virConnectListAllDomains, @flags can contain various flags to
* filter the list of domains to provide stats for.
@ -11020,9 +11024,13 @@ virConnectGetAllDomainStats(virConnectPtr conn,
*
* Specifying VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS as @flags makes
* the function return error in case some of the stat types in @stats were
* not recognized by the daemon.
* not recognized by the daemon. However, even with this flag, a hypervisor
* may omit individual fields within a known group if the information is not
* available; as an extreme example, a supported group may produce zero
* fields for offline domains if the statistics are meaningful only for a
* running domain.
*
* Note that any of the domain list filtering flags in @flags will be rejected
* Note that any of the domain list filtering flags in @flags may be rejected
* by this function.
*
* Returns the count of returned statistics structures on success, -1 on error.