[pbs-devel] [PATCH v2 proxmox-backup 2/2] docs: deduplicate background details for garbage collection

[Christian Ebner]

On 11/14/24 10:39, Gabriel Goller wrote:
> On 13.11.2024 16:55, Christian Ebner wrote:
>> diff --git a/docs/maintenance.rst b/docs/maintenance.rst
>> index e8a26d69c..bba3feff4 100644
>> --- a/docs/maintenance.rst
>> +++ b/docs/maintenance.rst
>> @@ -197,6 +197,8 @@ It's recommended to setup a schedule to ensure 
>> that unused space is cleaned up
>> periodically. For most setups a weekly schedule provides a good 
>> interval to
>> start.
>>
>> +.. _gc_background:
>> +
>> GC Background
>> ^^^^^^^^^^^^^
>>
>> @@ -222,17 +224,31 @@ datastore or interfering with other backups.
>> The garbage collection (GC) process is performed per datastore and is 
>> split
>> into two phases:
>>
>> -- Phase one: Mark
>> -  All index files are read, and the access time of the referred chunk 
>> files is
>> -  updated.
>> -
>> -- Phase two: Sweep
>> -  The task iterates over all chunks, checks their file access time, 
>> and if it
>> -  is older than the cutoff time (i.e., the time when GC started, plus 
>> some
>> -  headroom for safety and Linux file system behavior), the task knows 
>> that the
>> -  chunk was neither referred to in any backup index nor part of any 
>> currently
>> -  running backup that has no index to scan for. As such, the chunk 
>> can be
>> -  safely deleted.
>> +- Phase one (Mark):
>> +
>> +  All index files are read, and the access time (``atime``) of the 
>> referenced
>> +  chunk files is updated.
>> +
>> +- Phase two (Sweep):
>> +
>> +  The task iterates over all chunks and checks their file access time 
>> against a
>> +  cutoff time. The cutoff time is given by either the oldest backup 
>> writer
>> +  instance, if present, or 24 hours and 5 minutes after the start of 
>> garbage
>> +  collection.
>> +
> 
>> +  Garbage collection can consider chunk files with access time older 
>> than the
> 
> s/can consider/considers/

Acked!

> It always considers chunks with atime older than cutoff to be dangling
> afaik.

This part here is referring to the second phase, so cleaning up the 
chunks. Or what do you mean here by dangling?
> 
>> +  cutoff time to be neither referenced by any backup snapshot's 
>> index, nor part
>> +  of any currently running backup job. Therefore, these chunks can 
>> safeley be
>> +  deleted.
> 
> s/safeley/safely/

Acked!

> 
>> +
>> +  Chunks within the grace period will not be deleted and logged at 
>> the end of
>> +  the garbage collection task as *Pending removals*.
>> +
>> +.. note:: The grace period for backup chunk removal is not arbitrary, 
>> but stems
>> +   from the fact that filesystems are typically mounted with the 
>> ``relatime``
>> +   option by default. This results in better performance by only 
>> updating the
>> +   ``atime`` property if a file has been modified since the last 
>> access or the
>> +   last access has been at least 24 hours ago.
>>
>> Manually Starting GC
>> ^^^^^^^^^^^^^^^^^^^^
> 
> Otherwise this is great!
Thx, will fold in your comments and send a new version