From 20ee4ed75802e984732cbe6551c586563b48c326 Mon Sep 17 00:00:00 2001 From: Vitaliy Filippov Date: Tue, 1 Feb 2022 22:46:13 +0300 Subject: [PATCH] Update some parameter docs --- docs/params/common.yml | 2 +- .../{layout-client.yml => layout-cluster.yml} | 94 +++++++++---------- docs/params/layout-osd.yml | 52 ++++++++-- docs/params/monitor.yml | 2 +- docs/params/network.yml | 23 ++++- docs/params/osd.yml | 20 ++-- 6 files changed, 121 insertions(+), 72 deletions(-) rename docs/params/{layout-client.yml => layout-cluster.yml} (76%) diff --git a/docs/params/common.yml b/docs/params/common.yml index fd759914..46a004d8 100644 --- a/docs/params/common.yml +++ b/docs/params/common.yml @@ -22,7 +22,7 @@ type: string default: "/vitastor" info: | - Prefix for all keys in etcd Vitastor uses. You can change prefix and, for + Prefix for all keys in etcd used by Vitastor. You can change prefix and, for example, use a single etcd cluster for multiple Vitastor clusters. info_ru: | Префикс для ключей etcd, которые использует Vitastor. Вы можете задать другой diff --git a/docs/params/layout-client.yml b/docs/params/layout-cluster.yml similarity index 76% rename from docs/params/layout-client.yml rename to docs/params/layout-cluster.yml index db6fc867..5fbd27d4 100644 --- a/docs/params/layout-client.yml +++ b/docs/params/layout-cluster.yml @@ -6,80 +6,45 @@ subdivided in Vitastor. One of current main settings in Vitastor, affects memory usage, write amplification and I/O load distribution effectiveness. - Block size is fixed for the whole Vitastor cluster i.e. two different block - sizes can't be used in a single Vitastor cluster. Also you must not change - block size after initializing an OSD because even if you succeed you'll - destroy your data. - Recommended default block size is 128 KB for SSD and 4 MB for HDD. In fact, it's possible to use 4 MB for SSD too - it will lower memory usage, but - may increase average WA and reduce linear performance. SSD and HDD OSDs - with different block size can currently coexist in one etcd instance only - within separate Vitastor clusters with different etcd_prefix'es. + may increase average WA and reduce linear performance. + + OSDs with different block sizes (for example, SSD and SSD+HDD OSDs) can + currently coexist in one etcd instance only within separate Vitastor + clusters with different etcd_prefix'es. + + Also block size can't be changed after OSD initialization without losing + data. You must always specify block_size in etcd in /vitastor/config/global if you change it so all clients can know about it. OSD memory usage is roughly (SIZE / BLOCK * 68 bytes) which is roughly - 544 MB per 1 TB of used disk space with default 128 KB block size. + 544 MB per 1 TB of used disk space with the default 128 KB block size. info_ru: | Размер объектов (блоков данных), на которые делятся физические и виртуальные диски в Vitastor. Одна из ключевых на данный момент настроек, влияет на потребление памяти, объём избыточной записи (write amplification) и эффективность распределения нагрузки по OSD. - Размер блока фиксируется на уровне всего кластера Vitastor, т.е. разные - размеры блока не могут сосуществовать в одном кластере. Также размер блока - нельзя менять после инициализации OSD - даже если у вас получится, вы - уничтожите сохранённые на OSD данные. - Рекомендуемые по умолчанию размеры блока - 128 килобайт для SSD и 4 мегабайта для HDD. В принципе, для SSD можно тоже использовать 4 мегабайта, это понизит использование памяти, но ухудшит распределение нагрузки и в - среднем увеличит WA. SSD и HDD с разными размерами блока на данный момент - могут сосуществовать в рамках одного etcd только в виде двух независимых + среднем увеличит WA. + + OSD с разными размерами блока (например, SSD и SSD+HDD OSD) на данный + момент могут сосуществовать в рамках одного etcd только в виде двух независимых кластеров Vitastor с разными etcd_prefix. + Также размер блока нельзя менять после инициализации OSD без потери данных. + Если вы меняете размер блока, обязательно прописывайте его в etcd в /vitastor/config/global, дабы все клиенты его знали. Потребление памяти OSD составляет примерно (РАЗМЕР / БЛОК * 68 байт), т.е. примерно 544 МБ памяти на 1 ТБ занятого места на диске при стандартном 128 КБ блоке. -- name: disk_alignment - type: int - default: 4096 - info: | - Required physical disk write alignment. Most current SSD and HDD drives - use 4 KB physical sectors even if they report 512 byte logical sector - size, so 4 KB is a good default setting. - - Note, however, that physical sector size also affects WA, because with block - devices it's impossible to write anything smaller than a block. So, when - Vitastor has to write a single metadata entry that's only about 32 bytes in - size, it actually has to write the whole 4 KB sector. - - Because of this it can actually be beneficial to use SSDs which work well - with 512 byte sectors and use 512 byte disk_alignment, journal_block_size - and meta_block_size. But the only SSD that may fit into this category is - Intel Optane (probably, not tested yet). - info_ru: | - Требуемое выравнивание записи на физические диски. Почти все современные - SSD и HDD диски используют 4 КБ физические секторы, даже если показывают - логический размер сектора 512 байт, поэтому 4 КБ - хорошее значение по - умолчанию. - - Однако стоит понимать, что физический размер сектора тоже влияет на - избыточную запись (WA), потому что ничего меньше блока (сектора) на блочное - устройство записать невозможно. Таким образом, когда Vitastor-у нужно - записать на диск всего лишь одну 32-байтную запись метаданных, фактически - приходится перезаписывать 4 КБ сектор целиком. - - Поэтому, на самом деле, может быть выгодно найти SSD, хорошо работающие с - меньшими, 512-байтными, блоками и использовать 512-байтные disk_alignment, - journal_block_size и meta_block_size. Однако единственные SSD, которые - теоретически могут попасть в эту категорию - это Intel Optane (но и это - пока не проверялось автором). - name: bitmap_granularity type: int default: 4096 @@ -88,11 +53,26 @@ of disk_alignment. It's called bitmap granularity because Vitastor tracks an allocation bitmap for each object containing 2 bits per each (bitmap_granularity) bytes. + + This parameter can't be changed after OSD initialization without losing + data. Also it's fixed for the whole Vitastor cluster i.e. two different + values can't be used in a single Vitastor cluster. + + Clients MUST be aware of this parameter value, so put it into etcd key + /vitastor/config/global if you change it for any reason. info_ru: | Требуемое выравнивание записи на виртуальные диски (размер их "сектора"). Должен быть кратен disk_alignment. Называется гранулярностью битовой карты потому, что Vitastor хранит битовую карту для каждого объекта, содержащую по 2 бита на каждые (bitmap_granularity) байт. + + Данный параметр нельзя менять после инициализации OSD без потери данных. + Также он фиксирован для всего кластера Vitastor, т.е. разные значения + не могут сосуществовать в одном кластере. + + Клиенты ДОЛЖНЫ знать правильное значение этого параметра, так что если вы + его меняете, обязательно прописывайте изменённое значение в etcd в ключ + /vitastor/config/global. - name: immediate_commit type: string default: false @@ -134,6 +114,11 @@ SSD cache or "media-cache" - for example, a lot of Seagate EXOS drives have it (they have internal SSD cache even though it's not stated in datasheets). + This parameter must be set both in etcd in /vitastor/config/global and in + OSD command line or configuration. Setting it to "all" or "small" requires + enabling disable_journal_fsync and disable_meta_fsync, setting it to "all" + also requires enabling disable_data_fsync. + TLDR: For optimal performance, set immediate_commit to "all" if you only use SSDs with supercapacitor-based power loss protection (nonvolatile write-through cache) for both data and journals in the whole Vitastor @@ -183,6 +168,11 @@ многих дисках Seagate EXOS (у них есть внутренний SSD-кэш, хотя это и не указано в спецификациях). + Данный параметр нужно указывать и в etcd в /vitastor/config/global, и в + командной строке или конфигурации OSD. Значения "all" и "small" требуют + включения disable_journal_fsync и disable_meta_fsync, значение "all" также + требует включения disable_data_fsync. + Итого, вкратце: для оптимальной производительности установите immediate_commit в значение "all", если вы используете в кластере только SSD с суперконденсаторами и для данных, и для журналов. Если вы используете @@ -198,9 +188,13 @@ additional fsync and committing the data. Also note that the client always holds a copy of uncommitted data in memory so this setting also affects RAM usage of clients. + + This parameter doesn't affect OSDs themselves. info_ru: | При работе без immediate_commit=all - это лимит объёма "грязных" (не зафиксированных fsync-ом) данных, при достижении которого клиент будет принудительно вызывать fsync и фиксировать данные. Также стоит иметь в виду, что в этом случае до момента fsync клиент хранит копию незафиксированных данных в памяти, то есть, настройка влияет на потребление памяти клиентами. + + Параметр не влияет на сами OSD. diff --git a/docs/params/layout-osd.yml b/docs/params/layout-osd.yml index 5f3537dc..57a63e07 100644 --- a/docs/params/layout-osd.yml +++ b/docs/params/layout-osd.yml @@ -4,14 +4,14 @@ Path to the block device to use for data. It's highly recommendded to use stable paths for all device names: `/dev/disk/by-partuuid/xxx...` instead of just `/dev/sda` or `/dev/nvme0n1` to not mess up after server restart. - For testing purposes, files can also be used instead of block devices, but - that's not for a production environment, of course. + Files can also be used instead of block devices, but this is implemented + only for testing purposes and not for production. info_ru: | Путь к диску (блочному устройству) для хранения данных. Крайне рекомендуется использовать стабильные пути: `/dev/disk/by-partuuid/xxx...` вместо простых `/dev/sda` или `/dev/nvme0n1`, чтобы пути не могли спутаться после - перезагрузки сервера. В целях тестирования вместо устройств также разрешено - использовать и простые файлы, но делать так в боевой среде не следует. + перезагрузки сервера. Также вместо блочных устройств можно указывать файлы, + но это реализовано только для тестирования, а не для боевой среды. - name: meta_device type: string info: | @@ -130,7 +130,7 @@ Same as disable_data_fsync, but for the metadata device. If the metadata device is not set or if the data device is used for the metadata the option is ignored and disable_data_fsync value is used instead of it. - info: | + info_ru: | То же, что disable_data_fsync, но для устройства метаданных. Если устройство метаданных не задано или если оно равно устройству данных, значение опции игнорируется и вместо него используется значение опции disable_data_fsync. @@ -143,7 +143,7 @@ option is ignored and disable_meta_fsync value is used instead of it. If the same device is used for data, metadata and journal the option is also ignored and disable_data_fsync value is used instead of it. - info: | + info_ru: | То же, что disable_data_fsync, но для устройства журнала. Если устройство журнала не задано или если оно равно устройству метаданных, значение опции игнорируется и вместо него используется значение опции disable_meta_fsync. @@ -163,3 +163,43 @@ другими OSD с помощью flock(). Так делать не рекомендуется, но теоретически вы можете это использовать, чтобы запускать несколько OSD на одном устройстве с разными смещениями и без использования разделов. +- name: disk_alignment + type: int + default: 4096 + info: | + Required physical disk write alignment. Most current SSD and HDD drives + use 4 KB physical sectors even if they report 512 byte logical sector + size, so 4 KB is a good default setting. + + Note, however, that physical sector size also affects WA, because with block + devices it's impossible to write anything smaller than a block. So, when + Vitastor has to write a single metadata entry that's only about 32 bytes in + size, it actually has to write the whole 4 KB sector. + + Because of this it can actually be beneficial to use SSDs which work well + with 512 byte sectors and use 512 byte disk_alignment, journal_block_size + and meta_block_size. But the only SSD that may fit into this category is + Intel Optane (probably, not tested yet). + + Clients don't need to be aware of disk_alignment, so it's not required to + put a modified value into etcd key /vitastor/config/global. + info_ru: | + Требуемое выравнивание записи на физические диски. Почти все современные + SSD и HDD диски используют 4 КБ физические секторы, даже если показывают + логический размер сектора 512 байт, поэтому 4 КБ - хорошее значение по + умолчанию. + + Однако стоит понимать, что физический размер сектора тоже влияет на + избыточную запись (WA), потому что ничего меньше блока (сектора) на блочное + устройство записать невозможно. Таким образом, когда Vitastor-у нужно + записать на диск всего лишь одну 32-байтную запись метаданных, фактически + приходится перезаписывать 4 КБ сектор целиком. + + Поэтому, на самом деле, может быть выгодно найти SSD, хорошо работающие с + меньшими, 512-байтными, блоками и использовать 512-байтные disk_alignment, + journal_block_size и meta_block_size. Однако единственные SSD, которые + теоретически могут попасть в эту категорию - это Intel Optane (но и это + пока не проверялось автором). + + Клиентам не обязательно знать про disk_alignment, так что помещать значение + этого параметра в etcd в /vitastor/config/global не нужно. diff --git a/docs/params/monitor.yml b/docs/params/monitor.yml index a2c3e4c0..06f6a649 100644 --- a/docs/params/monitor.yml +++ b/docs/params/monitor.yml @@ -43,7 +43,7 @@ на другие OSD и таким образом восстановить избыточность хранения. - name: placement_levels type: json - default: '{"host":100,"osd":101}' + default: '`{"host":100,"osd":101}`' info: | Levels for the placement tree. You can define arbitrary tree levels by defining them in this parameter. The configuration parameter value should diff --git a/docs/params/network.yml b/docs/params/network.yml index d75045de..8ccf1818 100644 --- a/docs/params/network.yml +++ b/docs/params/network.yml @@ -34,20 +34,33 @@ type: bool default: true info: | - Try to use RDMA for communication if it's available. - Disable if you don't want Vitastor to use RDMA. + Try to use RDMA for communication if it's available. Disable if you don't + want Vitastor to use RDMA. RDMA increases the performance, but TCP-only + clients can still talk to an RDMA-enabled cluster, so you don't need to + make sure that all clients support RDMA when enabling it. info_ru: | Пытаться использовать RDMA для связи при наличии доступных устройств. Отключите, если вы не хотите, чтобы Vitastor использовал RDMA. + RDMA улучшает производительность, но + Клиенты и клиентов and TCP-only clients in the cluster at the + same time - TCP-only clients are still able to use an RDMA-enabled cluster. - name: rdma_device type: string info: | RDMA device name to use for Vitastor OSD communications (for example, - "rocep5s0f0"). Run `ibv_devinfo -v` as root to list available RDMA devices. + "rocep5s0f0"). Please note that Vitastor RDMA requires Implicit On-Demand + Paging (Implicit ODP) and Scatter/Gather (SG) support from the RDMA device + to work. For example, Mellanox ConnectX-3 and older adapters don't have + Implicit ODP, so they're unsupported by Vitastor. Run `ibv_devinfo -v` as + root to list available RDMA devices and their features. info_ru: | Название RDMA-устройства для связи с Vitastor OSD (например, "rocep5s0f0"). - Запустите `ibv_devinfo -v` под суперпользователем, чтобы посмотреть список - доступных RDMA-устройств и их параметры. + Имейте в виду, что поддержка RDMA в Vitastor требует функций устройства + Implicit On-Demand Paging (Implicit ODP) и Scatter/Gather (SG). Например, + адаптеры Mellanox ConnectX-3 и более старые не поддерживают Implicit ODP и + потому не поддерживаются в Vitastor. Запустите `ibv_devinfo -v` от имени + суперпользователя, чтобы посмотреть список доступных RDMA-устройств, их + параметры и возможности. - name: rdma_port_num type: int default: 1 diff --git a/docs/params/osd.yml b/docs/params/osd.yml index 06a2a563..a7180071 100644 --- a/docs/params/osd.yml +++ b/docs/params/osd.yml @@ -4,13 +4,13 @@ info: | Interval at which OSDs report their state to etcd. Affects OSD lease time and thus the failover speed. Lease time is equal to this parameter value - plus max_etcd_attempts*etcd_quick_timeout because it should be guaranteed + plus max_etcd_attempts * etcd_quick_timeout because it should be guaranteed that every OSD always refreshes its lease in time. info_ru: | Интервал, с которым OSD обновляет своё состояние в etcd. Значение параметра влияет на время резервации (lease) OSD и поэтому на скорость переключения при падении OSD. Время lease равняется значению этого параметра плюс - max_etcd_attempts*etcd_quick_timeout. + max_etcd_attempts * etcd_quick_timeout. - name: run_primary type: bool default: true @@ -245,15 +245,17 @@ info: | Enable this option for SSDs like Intel D3-S4510 and D3-S4610 which REALLY don't like when a program overwrites the same sector multiple times in a - row and slow down significantly (from 20000+ iops to ~3000 iops). When + row and slow down significantly (from 25000+ iops to ~3000 iops). When this option is set, Vitastor will always move to the next sector of the journal after writing it instead of possibly overwriting it the second time. info_ru: | - Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-4610, которые ОЧЕНЬ - не любят, когда ПО перезаписывает один и тот же сектор несколько раз подряд - и сильно замедляются (с 20000 и более iops до 3000). Когда данная опция - установлена, Vitastor всегда переходит к следующему сектор журнала после - записи вместо потенциально повторной перезаписи того же самого сектора. + Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-S4610, которые + ОЧЕНЬ не любят, когда ПО перезаписывает один и тот же сектор несколько раз + подряд. Такие SSD при многократной перезаписи одного и того же сектора + сильно замедляются - условно, с 25000 и более iops до 3000 iops. Когда + данная опция установлена, Vitastor всегда переходит к следующему сектору + журнала после записи вместо потенциально повторной перезаписи того же + самого сектора. - name: throttle_small_writes type: bool default: false @@ -319,7 +321,7 @@ равным внутреннему параллелизму ваших устройств данных (1 для HDD, 4-8 для SSD). - name: throttle_threshold_us - type: usec + type: us default: 50 info: | Minimal computed delay to be applied to throttled operations. Usually