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

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(a)redhat.com&gt; > > ---

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

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

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

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.

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

Reviewed-by: John Ferlan <jferlan(a)redhat.com&gt;