Add documentation for the write-back cache

2023-10-27 01:26:26 +03:00
parent 294a754c9e
commit 6fd2cf5df6
14 changed files with 346 additions and 50 deletions
@@ -0,0 +1,103 @@
+[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Параметры клиентского кода
+
+-----
+
+[Read in English](client.en.md)
+
+# Параметры клиентского кода
+
+Данные параметры применяются только к клиентам Vitastor (QEMU, fio, NBD) и
+затрагивают логику их работы с кластером.
+
+- [client_max_dirty_bytes](#client_max_dirty_bytes)
+- [client_max_dirty_ops](#client_max_dirty_ops)
+- [client_enable_writeback](#client_enable_writeback)
+- [client_max_buffered_bytes](#client_max_buffered_bytes)
+- [client_max_buffered_ops](#client_max_buffered_ops)
+- [client_max_writeback_iodepth](#client_max_writeback_iodepth)
+
+## client_max_dirty_bytes
+
+- Тип: целое число
+- Значение по умолчанию: 33554432
+- Можно менять на лету: да
+
+При работе без [immediate_commit](layout-cluster.ru.md#immediate_commit)=all - это лимит объёма "грязных" (не
+зафиксированных fsync-ом) данных, при достижении которого клиент будет
+принудительно вызывать fsync и фиксировать данные. Также стоит иметь в виду,
+что в этом случае до момента fsync клиент хранит копию незафиксированных
+данных в памяти, то есть, настройка влияет на потребление памяти клиентами.
+
+## client_max_dirty_ops
+
+- Тип: целое число
+- Значение по умолчанию: 1024
+- Можно менять на лету: да
+
+Аналогично client_max_dirty_bytes, но ограничивает количество
+незафиксированных операций записи вместо их общего объёма.
+
+## client_enable_writeback
+
+- Тип: булево (да/нет)
+- Значение по умолчанию: false
+- Можно менять на лету: да
+
+Данный параметр разрешает включать буферизацию записи в памяти. Буферизация
+означает, что операции записи отправляются на кластер Vitastor не сразу, а
+могут небольшое время накапливаться в памяти и сбрасываться сразу пакетами,
+до тех пор, пока либо не будет превышен лимит неотправленных записей, либо
+пока клиент не вызовет fsync.
+
+Буферизация значительно повышает производительность некоторых приложений,
+например, CrystalDiskMark в Windows (ха-ха :-D), но также и любых других,
+которые пишут на диск неоптимально: либо последовательно, но мелкими блоками
+(например, по 4 кб), либо случайно, но без параллелизма и без fsync - то
+есть, например, отправляя 128 операций записи в разные места диска, но не
+все сразу с помощью асинхронного I/O, а по одной.
+
+В QEMU с буферизацией записи можно ожидать показателя примерно 22000
+операций случайной записи в секунду в 1 поток и с глубиной очереди 1 (T1Q1)
+без fsync, почти вне зависимости от того, насколько хороши ваши диски - эта
+цифра упирается в сам QEMU. Без буферизации рекорд пока что - 9900 операций
+в секунду, но на железе похуже может быть и поменьше, например, 5000 операций
+в секунду.
+
+При этом, даже если данный параметр включён, буферизация не включается, если
+явно не разрешена клиентом, т.к. если клиент не знает, что запросы записи
+буферизуются, это может приводить к потере данных. Поэтому в старых версиях
+клиентских драйверов буферизация записи не включается вообще, в новых
+версиях QEMU-драйвера включается только если разрешена опцией диска
+`-blockdev cache.direct=false`, а в fio - только если нет опция `-direct=1`.
+В NBD и NFS драйверах буферизация записи разрешена по умолчанию.
+
+Можно обойти и это ограничение с помощью параметра `client_writeback_allowed`,
+но делать так не надо, если только вы не уверены в том, что делаете, на все
+100%. :-)
+
+## client_max_buffered_bytes
+
+- Тип: целое число
+- Значение по умолчанию: 33554432
+- Можно менять на лету: да
+
+Максимальный общий размер буферизованных записей, при достижении которого
+начинается процесс сброса данных на сервер.
+
+## client_max_buffered_ops
+
+- Тип: целое число
+- Значение по умолчанию: 1024
+- Можно менять на лету: да
+
+Максимальное количество буферизованных записей, при достижении которого
+начинается процесс сброса данных на сервер. При этом несколько
+последовательных изменённых областей здесь считаются 1 записью.
+
+## client_max_writeback_iodepth
+
+- Тип: целое число
+- Значение по умолчанию: 256
+- Можно менять на лету: да
+
+Максимальное число параллельных операций записи при сбросе буферов на сервер.