[PATCH] btrfs-progs: Doc: update autodefrag mount options

[PATCH] btrfs-progs: Doc: update autodefrag mount options

[Qu Wenruo]

This will add the following contents:

- Add how autodefrag works

- More detailed cases which are not sutiable for autodefrag

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 Documentation/ch-mount-options.rst | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/Documentation/ch-mount-options.rst b/Documentation/ch-mount-options.rst
index f4ff0084d00f..f2dd12e6f841 100644
--- a/Documentation/ch-mount-options.rst
+++ b/Documentation/ch-mount-options.rst
@@ -28,9 +28,23 @@ autodefrag, noautodefrag
         (since: 3.0, default: off)
 
         Enable automatic file defragmentation.
-        When enabled, small random writes into files (in a range of tens of kilobytes,
-        currently it's 64KiB) are detected and queued up for the defragmentation process.
-        Not well suited for large database workloads.
+        When enabled, small random writes into files (in a range of tens of
+        kilobytes, currently it's 64KiB for uncompressed write, and 16KiB for
+        compressed write) are detected and queued up for the defragmentation
+        process.
+
+        Then btrfs-cleaner kernel thread will try to defrag all those files.
+        The defragmentation process will scan the whole file from offset 0,
+        finding out mergeable small writes since last modification, and
+        re-dirty suitable targets (small, newer than last modification, mergeable)
+        for next writeback.
+
+        Thus autodefrag, just like regular defrag, will cause extra data write.
+
+        Not suited for heavy random write workload (including database and
+        torrent), as such small random writes can get re-dirtied very
+        frequently, causing amplified data write IO, while the file can still be
+        heavily fragmented by the new writes.
 
         The read latency may increase due to reading the adjacent blocks that make up the
         range for defragmentation, successive write will merge the blocks in the new
-- 
2.35.1

Re: [PATCH] btrfs-progs: Doc: update autodefrag mount options

[Graham Cobb]

On 16/02/2022 11:10, Qu Wenruo wrote:
> This will add the following contents:
> 
> - Add how autodefrag works
> 
> - More detailed cases which are not sutiable for autodefrag

Typo: suitable

> 
> Signed-off-by: Qu Wenruo <wqu@suse.com>
> ---
>  Documentation/ch-mount-options.rst | 20 +++++++++++++++++---
>  1 file changed, 17 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/ch-mount-options.rst b/Documentation/ch-mount-options.rst
> index f4ff0084d00f..f2dd12e6f841 100644
> --- a/Documentation/ch-mount-options.rst
> +++ b/Documentation/ch-mount-options.rst
> @@ -28,9 +28,23 @@ autodefrag, noautodefrag
>          (since: 3.0, default: off)
>  
>          Enable automatic file defragmentation.
> -        When enabled, small random writes into files (in a range of tens of kilobytes,
> -        currently it's 64KiB) are detected and queued up for the defragmentation process.
> -        Not well suited for large database workloads.
> +        When enabled, small random writes into files (in a range of tens of
> +        kilobytes, currently it's 64KiB for uncompressed write, and 16KiB for
> +        compressed write) are detected and queued up for the defragmentation

As I think the target audience for the mount options documentation
includes system admins, not just btrfs kernel developers, I would avoid
the term "compressed write" because of the plans to add a mechanism to
write pre-compressed data which the admin may have heard about and be
confused. How about something like:

"currently it's 64KiB for writes to uncompressed files, and 16KiB for
compressed files"

Sure, this is hand-waving over the precise decisions the kernel makes
but anyone who cares about that will check the actual code anyway.

> +        process.
> +
> +        Then btrfs-cleaner kernel thread will try to defrag all those files.
> +        The defragmentation process will scan the whole file from offset 0,
> +        finding out mergeable small writes since last modification, and
> +        re-dirty suitable targets (small, newer than last modification, mergeable)
> +        for next writeback.
> +
> +        Thus autodefrag, just like regular defrag, will cause extra data write.

Typo: "writes"

> +
> +        Not suited for heavy random write workload (including database and
> +        torrent), as such small random writes can get re-dirtied very
> +        frequently, causing amplified data write IO, while the file can still be
> +        heavily fragmented by the new writes.
>  
>          The read latency may increase due to reading the adjacent blocks that make up the
>          range for defragmentation, successive write will merge the blocks in the new

Graham

Re: [PATCH] btrfs-progs: Doc: update autodefrag mount options

[Qu Wenruo]

On 2022/2/16 19:33, Graham Cobb wrote:
> On 16/02/2022 11:10, Qu Wenruo wrote:
>> This will add the following contents:
>>
>> - Add how autodefrag works
>>
>> - More detailed cases which are not sutiable for autodefrag
>
> Typo: suitable

Why my git hooks didn't warn me...

Anyway, really appreciate the typo catch and feedback on such docs, as
you know I'm really bad at writing docs...

>
>>
>> Signed-off-by: Qu Wenruo <wqu@suse.com>
>> ---
>>   Documentation/ch-mount-options.rst | 20 +++++++++++++++++---
>>   1 file changed, 17 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/ch-mount-options.rst b/Documentation/ch-mount-options.rst
>> index f4ff0084d00f..f2dd12e6f841 100644
>> --- a/Documentation/ch-mount-options.rst
>> +++ b/Documentation/ch-mount-options.rst
>> @@ -28,9 +28,23 @@ autodefrag, noautodefrag
>>           (since: 3.0, default: off)
>>
>>           Enable automatic file defragmentation.
>> -        When enabled, small random writes into files (in a range of tens of kilobytes,
>> -        currently it's 64KiB) are detected and queued up for the defragmentation process.
>> -        Not well suited for large database workloads.
>> +        When enabled, small random writes into files (in a range of tens of
>> +        kilobytes, currently it's 64KiB for uncompressed write, and 16KiB for
>> +        compressed write) are detected and queued up for the defragmentation
>
> As I think the target audience for the mount options documentation
> includes system admins, not just btrfs kernel developers, I would avoid
> the term "compressed write" because of the plans to add a mechanism to
> write pre-compressed data which the admin may have heard about and be
> confused. How about something like:
>
> "currently it's 64KiB for writes to uncompressed files, and 16KiB for
> compressed files"

Something similar is also considered, but one of my concern is for the
"compressed files" expression, won't end users get confused with regular
compressed files like .tar.gz, not the btrfs term for compressed file
extents.

Any better or official expression specific for those btrfs compressed
file extents?

>
> Sure, this is hand-waving over the precise decisions the kernel makes
> but anyone who cares about that will check the actual code anyway.

Well, I'm pretty sure that almost none of the autodefrag users are
reading the kernel code, that's why I put some simplified comment into
this part. :)

Thanks,
Qu

>
>> +        process.
>> +
>> +        Then btrfs-cleaner kernel thread will try to defrag all those files.
>> +        The defragmentation process will scan the whole file from offset 0,
>> +        finding out mergeable small writes since last modification, and
>> +        re-dirty suitable targets (small, newer than last modification, mergeable)
>> +        for next writeback.
>> +
>> +        Thus autodefrag, just like regular defrag, will cause extra data write.
>
> Typo: "writes"
>
>> +
>> +        Not suited for heavy random write workload (including database and
>> +        torrent), as such small random writes can get re-dirtied very
>> +        frequently, causing amplified data write IO, while the file can still be
>> +        heavily fragmented by the new writes.
>>
>>           The read latency may increase due to reading the adjacent blocks that make up the
>>           range for defragmentation, successive write will merge the blocks in the new
>
> Graham