[libvirt] [RFC PATCH 2/2] lib: Add note that bulk stats API queries may overrun RPC buffers

[Daniel P. Berrange]

On Mon, May 22, 2017 at 06:00:13PM +0200, Peter Krempa wrote:
> Hint that the users should limit the number of VMs queried in the bulk
> stats API.
> ---
>  src/libvirt-domain.c | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
> index 310b91b37..b01f2705c 100644
> --- a/src/libvirt-domain.c
> +++ b/src/libvirt-domain.c
> @@ -11315,6 +11315,10 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
>   * VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF and/or
>   * VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER for all other states.
>   *
> + * Note that this API is prone to exceeding maximum RPC message size on hosts
> + * with lots of VMs so it's suggested to use virDomainListGetStats with a
> + * reasonable list of VMs as the argument.
> + *
>   * Returns the count of returned statistics structures on success, -1 on error.
>   * The requested data are returned in the @retStats parameter. The returned
>   * array should be freed by the caller. See virDomainStatsRecordListFree.
> @@ -11386,6 +11390,9 @@ virConnectGetAllDomainStats(virConnectPtr conn,
>   * Note that any of the domain list filtering flags in @flags may be rejected
>   * by this function.
>   *
> + * Note that this API is prone to exceeding maximum RPC message size on hosts
> + * with lots of VMs so it's suggested to limit the number of VMs queried.

With the way this is worded, applications have no guidance on what is a
sensible max number of VMs they can safely use, so I don't think it is
particularly useful, except as a way to say "we told you so" when apps
report a bug.

I'd be inclined to explicitly put a limit of 100 VMs[1] in the API, and
document that hard limit, so apps immediately know to write their code
to chunk in 100 VM blocks.

Regards,
Daniel

[1] 100 is entirely arbitrary for this email - we'd actually pick a number
    based on what we reasonably expect to fit in the RPC message size.
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|