[libvirt] [PATCH v5 03/20] backup: Document nuances between different state capture APIs

[Eric Blake]

On 3/12/19 12:59 PM, John Ferlan wrote:
> 
> 
> On 3/7/19 12:47 AM, Eric Blake wrote:
>> Upcoming patches will add support for incremental backups via
>> a new API; but first, we need a landing page that gives an
>> overview of capturing various pieces of guest state, and which
>> APIs are best suited to which tasks.
>>
>> Signed-off-by: Eric Blake <eblake at redhat.com>
>>
>> ---

>> +    <p>
>> +      The information here is primarily geared towards capturing the
>> +      state of an active domain. Capturing the state of an inactive
>> +      domain essentially amounts to copying the contents of guest
>> +      disks, followed by a fresh boot with disks restored to that
>> +      state. Some of the topics presented below may relate to inactive
>> +      state collection, but it is not the primary focus of this page.
> 
> Perhaps the last sentence is redundant or unnecessary, IDC.

I don't think it hurts to drop it.


>> +    <dl>
>> +      <dt>Duration</dt>
>> +      <dd>Capturing state can be a lengthy process, so while the
>> +        captured state ideally represents an atomic point in time
>> +        correpsonding to something the guest was actually executing,
> 
> corresponding

Fixed.


>> +
>> +    <h2><a id="apis">State capture APIs</a></h2>
>> +    <p>With those definitions, the following libvirt APIs related to
>> +      state capture have these properties:</p>
>> +    <dl>
>> +      <dt>virDomainManagedSave</dt>
> 
> Do you think it'd be worthwhile to modify to:
> 
> <code><a
> href="html/libvirt-libvirt-domain.html#virDomainManagedSave">virDomainManagedSave</a></code>

Yes, making links is worthwhile. I'll do that...

> 
> Since this and the next two following don't have links yet, I think
> rather than do any sort of split, can we move this to after the
> virDomainBackup* API's are introduced? It's been great to help lay the
> groundwork though.
> 
>> +      <dd>This API does not actually capture guest state, rather it
>> +        makes it possible to track which portions of guest disks have
>> +        changed between a checkpoint and the current live execution of
>> +        the guest.  However, while it is possible use this API to
>> +        create checkpoints in isolation, it is more typical to create
>> +        a checkpoint as a side-effect of starting a new incremental
>> +        backup with <code>virDomainBackupBegin()</code>, since a
>> +        second incremental backup is most useful when using the
>> +        checkpoint created during the first.  <!--See also
>> +        the <a href="formatcheckpoint.html">XML details</a> used with
>> +        this command.--></dd>
> 
> Making this patch later in the series removes the need for this too.
> 

and yes, I can make this shuffle in the series.


>> +    <p>2. Direct backup
>> +      <pre>
>> +virDomainFSFreeze()
>> +virDomainBackupBegin()
>> +virDomainFSThaw()
>> +wait for push mode event, or pull data over NBD # most time spent here
>> +virDomainBackeupEnd()
> 
> virDomainBackupEnd

Indeed.

> 
> Reviewed-by: John Ferlan <jferlan at redhat.com>

Thanks.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20190313/bf51e0ce/attachment-0001.sig>