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

[Markus Armbruster]

Daniel P. Berrangé <berrange at redhat.com> writes:

> 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.

Based on what we've deprecated so far: most, for a large value of
"most".

> 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).

Makes sense.

> 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.

Makes sense, too.

> 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).

Makes sense, too.

Logging the complete QMP traffic can be invaluable when troubleshooting,
and is unlikely to make users report the warnings to libvirt developers.
But that's a different log / a higher debug level.

> In theory libvirt could see the deprecation reply and take
> different action, but I don't much like that idea. It is too

That way is madness :)

> 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.

PATCH 15 makes deprecation visible in introspection.  Like all of this
series, it's limited to commands and events.  Extending to arguments and
return values feels feasible, and I'm willing to do the work.

Argument *values* are a different ballgame.  Schema support for "this
argument is deprecated" is straightforward (tack feature "deprecated" to
it).  Support for "this argument value is deprecated" is not (except for
enumerations, where we can tack feature "deprecated" to the enumeration
value).  Same for return values, combinations of arguments, and so
forth.  Not sure how relevant these are in practice.

I'm not sure how useful the "deprecated" feature will be for guiding
decisions on which interface to use.  I imagine there's typically a list
of interfaces libvirt can use, ordered by "desirability", and the most
desirable interface known to work gets used.  If $new_way is workable,
you use it, else you fall back to $old_way.  Whether $old_way is
deprecated is immaterial.

The "deprecated" feature could be used for dynamic checking, i.e. check
the commands sent to QEMU against the output of query-qmp-schema.  But
that merely duplicates the check QEMU does when it receives it.

Static checking would be more interesting, if we can pull it off.

>> * 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.

Understood.

Thanks!