----- Original Message -----
From: "Peter Krempa" <pkrempa@redhat.com> To: libvir-list@redhat.com Cc: eblake@redhat.com, berrange@redhat.com, fromani@redhat.com, "Peter Krempa" <pkrempa@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