[libvirt] [RFC PATCH 18/19] qapi: Include a warning in the response to a deprecated command

[Daniel P. Berrangé]

On Thu, Oct 24, 2019 at 02:34:57PM +0200, Markus Armbruster wrote:
> Looks like this
> 
>     ---> {"execute": "query-cpus"}
>     <--- {"return": [...], "warnings": [{"class": "CommandNotFound", "desc": "command is deprecated"}]}
> 
> Management applications may want to log such warnings.
> 
> This commit is not for merging as is, because
> 
> * docs/interop/qmp-spec.txt needs an update for the new success
>   response member "warnings".
> 
> * I'd like to see a prospective user before I extend the QMP protocol.
>   If you have specific plans to put them to use, let me know.

Thinking about libvirt's usage of QMP

 - A public API call may result in many QMP commands being run.
 - Public APIs don't have any convenient way to report deprecated
   usage synchronously at runtime.
 - The set of QMP comamnds used by libvirt is a private impl
   detail that a mgmt app shouldn't know about

Some (most) deprecations will be things targetted at libvirt
developers, where libvirt just needs fixing to use some new
alternative instead.

Other deprecations where there's no replacement provided by QEMU
are things where an application might need to be told to stop
using the feature. From libvirt's public API POV the feature
likely won't be deprecated, only the specific usage of that
feature with the QEMU driver. eg consider QEMU decides to
stop POSTCOPY migration for some reason. Its deprecated from
POV of QEMU & QMP commands. If Xen or ESX support POSTCOPY
though, its not deprecated from libvirt's API POV. In many
ways this becomes a capabilities reporting problem between
libvirt & the application. Libvirt needs to tell the app which
features they can use, given their curent open libvirt connection
and VM instance(s).

So, either way, I don't think the QMP deprecations are something
we would want to expose to applications 'as is', since they're
either not something an app dev can fix, or they need rephrasing
in terms of the libvirt API/config feature the app is using, or
translating into a way for libvirt to expose capabilities to apps.

Libvirt could potentially log the deprecation warning in the per
QEMU VM log file. If end users see such log messages they'll
probably file support tickets / bug reports against libvirt and/or
the mgmt app, which will alert their maintainers to the fact. THis
could be useful if the maintainers missed the QEMU documentation
update listing the deprecation. It could be annoying if libvirt
knows it is deprecated though, and intentionally is still using
it in this particular version, with plans already present to fix
it in future.   So if libvirt does log the deprecations to the
VM log file, we'll probably want to /not/ log certain deprecations
that we're intentionally ignoring (temporarily).

In theory libvirt could see the deprecation reply and take
different action, but I don't much like that idea. It is too
late becasue we've already run the command, and its providing
a second way to deal with capabilities. We should be able to
query/probe the right way to invoke commands upfront, so that
we avoid using deprecated stuff in the first place.

> * The same warning should be included in a deprecated event.
> 
> * Emitting the same warning over and over again might be annoying or
>   slow.  Perhaps warning just once would be better.

If written to a log file, any single deprecation definitely
needs to be limited to once only per QEMU process lifetime.
Once a libvirt/qemu pair is deployed on a host it may be a
long time before an upgrade is done that pulls in the new
libvirt to avoid the deprecation. So we don't want to be
spamming logs of an otherwise fully functional VM.

In summary, it is probably reasonable to include this info in the QMP
command reply, but don't expect much to be done with it beyond possibly
writing it to a log file.

Regards,
Daniel
-- 
|: 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 :|