[libvirt] [RFCv2] Introduce API for retrieving bulk domain stats v2

[Francesco Romani]

----- Original Message -----
> From: "Peter Krempa" <pkrempa at redhat.com>
> To: libvir-list at redhat.com
> Cc: eblake at redhat.com, berrange at redhat.com, fromani at redhat.com, "Peter Krempa" <pkrempa at redhat.com>
> Sent: Thursday, August 21, 2014 3:20:45 PM
> Subject: [RFCv2] Introduce API for retrieving bulk domain stats v2
> 
> I'd like to propose a (hopefully) fairly future-proof API to retrieve
> various statistics for domains.
> 
> The motivation is that management layers that use libvirt usually poll
> libvirt for statistics using various split up APIs we currently provide.
> To get all the necessary stuff, the mgmt app need to issue Ndomains *
> Napis calls and cope with the various returned formats. The APIs I'm
> wanting to introduce here will:
> 
> 1) Return data in a format that we can expand in the future and is
> hierarchical. This version returns the data as typed parameters where
> the fields are constructed as dot-separated strings containing names and
> other stuff in a list of typed params.
> 
> 2) Stats for multiple (all) domains can be queried at once and are
> returned in one call. This will allow to decrease the overhead necessary
> to issue multiple calls per domain multiplied by the count of domains.
> 
> 3) Selectable (bit mask) fields in the returned format. This will allow
> to retrieve only specific stats according to the APPs need.
> 
> Initially the implementation will introduce the option to retrieve
> block, interface  and cpu stats with the possibility to add more in the
> future.
> 
> The stats groups will be enabled using a bit field @stats passed as the
> function argument. A few groups for inspiration:
> 
> VIR_DOMAIN_STATS_STATE
> VIR_DOMAIN_STATS_CPU
> VIR_DOMAIN_STATS_BLOCK
> VIR_DOMAIN_STATS_INTERFACE
> 
> the returned typed params will use the following scheme
> 
> state.state = running
> state.reason = started
> cpu.count = 8
> cpu.0.state = running
> cpu.0.time = 1234

OK for me

> +typedef struct _virDomainStatsRecord virDomainStatsRecord;
> +typedef virDomainStatsRecord *virDomainStatsRecordPtr;
> +struct _virDomainStatsRecord {
> +    virDomainPtr dom;
> +    unsigned int nparams;
> +    virTypedParameterPtr params;
> +};
> +
> +typedef enum {
> +    VIR_DOMAIN_STATS_ALL = (1 << 0), /* return all stats fields
> +                                       implemented in the daemon */
> +    VIR_DOMAIN_STATS_STATE = (1 << 1), /* return domain state */
> +} virDomainStatsTypes;
> +
> +int virConnectGetAllDomainStats(virConnectPtr conn,
> +                                unsigned int stats,
> +                                virDomainStatsRecordPtr **retStats,
> +                                unsigned int flags);
> +
> +int virDomainListGetStats(virDomainPtr *doms,
> +                          unsigned int stats,
> +                          virDomainStatsRecordPtr **retStats,
> +                          unsigned int flags);
> +
> +void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats);
> +

Minor question:
Would it be possible, maybe on a future extension, for the caller to
preallocate the virDomainStatsPtr output records?

Thanks and bests,

-- 
Francesco Romani
RedHat Engineering Virtualization R & D
Phone: 8261328
IRC: fromani