an article on booting tablets (#18505)

Co-authored-by: Ilnaz Nizametdinov <i.nizametdinov@gmail.com>
Co-authored-by: anton-bobkov <anton-bobkov@ydb.tech>

4 files changed, 103 insertions, 3 deletions

diff --git a/ydb/docs/ru/core/contributor/hive-booting.md b/ydb/docs/ru/core/contributor/hive-booting.md
new file mode 100644
index 00000000000..8f60ace53db
--- /dev/null
+++ b/ydb/docs/ru/core/contributor/hive-booting.md
@@ -0,0 +1,94 @@
+# Запуск таблеток
+
+В данной статье описывается процесс запуска [таблеток](../concepts/glossary.md#tablet) со стороны [Hive](../concepts/glossary.md#hive). Hive принимает решение о запуске таблетки в различных ситуациях:
+
+* Таблетка только что была создана.
+* Утрачена связь с узлом, на котором была запущена таблетка.
+* Узел, на котором была запущена таблетка, прислал сообщение о том, что она прекратила работу (например, из-за потери связи с дисковой подсистемой кластера).
+* При перевозе таблетки в рамках [автобалансировки](hive.md#autobalancing).
+
+В любой из этих ситуаций происходит следующее:
+
+1. Таблетка добавляется в [очередь на запуск](#bootqueue).
+1. При обработке очереди для неё [выбирается подходящий узел](#findbestnode).
+1. На  узел отправляется команда о [запуске таблетки](#booting).
+
+## Очередь {#bootqueue}
+
+Очередь на запуск, или *Boot queue*, хранится в памяти Hive и является приоритетной. Приоритет таблетки определяется следующими факторами:
+
+1. [Тип таблетки](../concepts/glossary.md#tablet-types) — системные таблетки имеют более высокий приоритет, чем пользовательские.
+1. [Метрики потребления ресурсов](hive.md#resources) — таблетки с бóльшим потреблением имеют бóльший приоритет.
+1. Таблетки, которые часто перезапускаются, имеют пониженный приоритет.
+
+При обработке очереди за раз обрабатывается ограниченное количество таблеток (`max_boot_batch_size` в [конфигурации](../reference/configuration/hive.md#boot)). Это нужно для того, чтобы при запуске большого числа таблеток Hive не переставал на долгое время отвечать на другие запросы.
+
+Если при обработке очередной таблетки оказывается, что её нельзя запустить ни на одном из узлов, то эта таблетка откладывается в отдельную очередь *Wait queue*. Когда доступность узла меняется (подключается новый узел, или с узла снимается ограничение в [Hive UI](../reference/embedded-ui/hive.md)), Hive возвращается к этим таблеткам и при обработке очереди на запуск чередует таблетки из Boot Queue и таблетки из Wait Queue.
+
+```mermaid
+stateDiagram-v2
+  [*] --> BQ: Нужно запустить таблетку
+  BQ --> PBQ
+  PBQ --> Running
+  PBQ --> WQ: При отсутствии подходящего узла
+  WQ --> PBQ: При появлении доступного узла
+  BQ: Boot queue
+  WQ: Wait queue
+  PBQ: Обработка очереди
+  Running: Запуск таблетки
+```
+
+{% note warning %}
+
+Одновременный запуск множества таблеток может создавать повышенную нагрузку на узел. Поэтому максимальное число одновременно запускаемых таблеток на одном узле ограничено значением `max_tablets_scheduled` из [конфигурации](../reference/configuration/hive.md#boot). При этом, если один из узлов упирается в это ограничение, Hive останавливает запуск новых таблеток и на других узлах тоже, чтобы это не повлияло на равномерность распределения. Это поведение можно регулировать с помощью параметра [`boot_strategy`](../reference/configuration/hive.md#boot).
+
+{% endnote %}
+
+## Выбор узла {#findbestnode}
+
+Существуют строгие ограничения на то, на каких узлах разрешено запускать таблетку: не каждый узел может запускать каждый тип таблеток; таблетки некоторой базы данных могут быть запущены только на узлах этой базы данных. Дополнительно при **перевозе** таблеток не рассматриваются перегруженные узлы.
+
+1. Из всех подходящих узлов отбираются узлы с максимальным приоритетом. Приоритет определяется исходя из датацентра, в котором находится узел. Явно указать приоритеты датацентров можно в подсекции [`default_tablet_preference`](../reference/configuration/hive.md#boot) в конфигурации. Для [координаторов](../concepts/glossary.md#coordinator) и [медиаторов](../concepts/glossary.md#mediator) приоритеты определяются динамически так, чтобы по возможности поддерживать их в одном датацентре. Дополнительно, если таблетка завершает работу с ошибкой на некотором узле, на следующий запуск этой таблетки приоритет этого узла понижается.
+
+1. Для узлов с максимальным приоритетом считается целевая метрика, которая почти совпадает с метрикой [Node usage](hive.md#node-usage). Она отличается тем, что учитываются только те ресурсы, которые потребляет данная таблетка, а также наличием штрафа за количество таблеток того же [объекта схемы](../concepts/glossary.md#schema-object).
+
+1. Наконец, на основе этой метрики делается выбор узла. Алгоритм выбора на этом этапе определяется параметром `node_select_strategy` в конфигурации. По умолчанию выбирается случайный узел из 7% узлов с минимальным значением метрики.
+
+Ниже приведена иллюстрация процесса.
+
+```mermaid
+block-beta
+    columns 6
+    Node11("Node 1\nDC: dc-1\nallowed") Node12("Node 2\nDC: dc-2\nallowed") Node13("Node 3\nDC: dc-2\nmarked down") Node14("Node 4\nDC: dc-2\nallowed") Node15("Node 5\nDC: dc-3\noverloaded") Node16("Node 6\nDC: dc-3\nallowed")
+    Arrow1<["Step 1"]>(down):6
+    Node21("Node 1\nDC: dc-1\nPriority:0") Node22("Node 2\nDC: dc-2\nPriority: 1") space Node24("Node 4\nDC: dc-2\nPriority: 1") space Node26("Node 6\nDC: dc-3\nPriority: 0")
+    Arrow2<["Step 2"]>(down):6
+    space Node32("Node 2\nDC: dc-2\nUsage: 60%") space Node34("Node 4\nDC: dc-2\nUsage: 30%") space:2
+    Arrow3<["Step 3"]>(down):6
+    Pick["Pick Node 4"]:6
+
+    classDef dc1 fill:#edc0c0;
+    classDef dc2 fill:#dac8be;
+    classDef dc3 fill:#fff8c2;
+    class Node11 dc1
+    class Node21 dc1
+    class Node12 dc2
+    class Node22 dc2
+    class Node32 dc2
+    class Node13 dc2
+    class Node14 dc2
+    class Node24 dc2
+    class Node34 dc2
+    class Node15 dc3
+    class Node16 dc3
+    class Node26 dc3
+```
+
+## Процесс запуска {#booting}
+
+На каждом узле запущен сервис [Local](../concepts/glossary.md#local), отвечающий за взаимодействие с Hive. При запуске таблетки Hive отправляет в Local нужного узла команду старта таблетки, содержащую всю необходимую для запуска информацию: [TabletID](../concepts/glossary.md#tabletid), [поколение](../concepts/glossary.md#tablet-generation), [историю каналов](general-schema.md#history) и режим запуска ([лидер](../concepts/glossary.md#tablet-leader) или [подписчик](../concepts/glossary.md#tablet-follower)). После того, как таблетка запускается, Local сообщает об этом в Hive. С этого момента таблетка считается запущенной с точки зрения Hive и остаётся такой, пока:
+
+* Local не сообщит об остановке её работы;
+* связь с Local не будет нарушена.
+
+В этих ситуациях вновь начнётся процесс запуска уже для следующего поколения таблетки.
diff --git a/ydb/docs/ru/core/contributor/hive.md b/ydb/docs/ru/core/contributor/hive.md
index c1911206f03..66341999d37 100644
--- a/ydb/docs/ru/core/contributor/hive.md
+++ b/ydb/docs/ru/core/contributor/hive.md
@@ -4,6 +4,8 @@ Hive — таблетка, отвечающая за управление дру
 
 Создание и удаление таблеток инициируется таблеткой [SchemeShard](../concepts/glossary.md#scheme-shard). При создании таблетки Hive присваивает ей уникальный TabletId, заполняет [TabletStorageInfo](general-schema.md#history), выбирает наиболее подходящий узел и отправляет на него команду на запуск таблетки. В некоторых нестандартных ситуациях отдельная таблетка может прервать работу, тогда узел, на котором она была запущена, отправляет сообщение в Hive. Также Hive предполагает, что если связь с некоторым узлом потеряна, то запущенные на нём таблетки прекратили работу. В таких случаях Hive перезапускает таблетки на других узлах с увеличением поколения.
 
+Логика запуска таблеток подробно описана в статье [{#T}](hive-booting.md).
+
 В кластере {{ ydb-short-name }} есть корневой Hive, который отвечает за [системные таблетки](../concepts/glossary.md#tablet-types) всех баз данных кластера. Hive конкретной базы данных, в свою очередь, отвечает за таблетки, обслуживающие пользовательскую нагрузку этой базы. Все узлы кластера регистрируются в корневом Hive, а в Hive конкретной базы регистрируются только вычислительные узлы этой базы. При регистрации узел сообщает в Hive, какие типы таблеток и в каком количестве могут быть на нём запущены.
 
 ## Метрики потребления ресурсов {#resources}
@@ -15,7 +17,7 @@ Hive — таблетка, отвечающая за управление дру
 1. *Network* — генерируемый таблеткой объём трафика.
 1. *Counter* — фиктивный ресурс, используемый для реализации равномерного распределения в штуках. Если у таблетки ненулевое значение потребления любого другого ресурса, то её значение Counter равно 0, иначе оно равно 1. Таким образом, Counter применяется для любых таблеток, для которых нет данных о реальном потреблении, а также для таблеток, для которых учёт реального потребления отключён: по умолчанию это только таблетки [колоночных таблиц](../concepts/datamodel/table.md#column-oriented-tables).{#counter}
 
-Дополнительно для определения перегруженных узлов используются метрики потребления ресурсов узла целиком: потребление оперативной памяти и ресурсов процессора в пулах акторной системы. Эти значения переводятся в относительную величину (число от 0 до 1), и их максимум используется как значение общего потребления ресурсов узла — *Node usage*. Также для всех метрик на стороне Hive применяется агрегация по окну, чтобы учитывать всплески нагрузки.
+Дополнительно для определения перегруженных узлов используются метрики потребления ресурсов узла целиком: потребление оперативной памяти и ресурсов процессора в пулах акторной системы. Эти значения переводятся в относительную величину (число от 0 до 1), и их максимум используется как значение общего потребления ресурсов узла — *Node usage*. Также для всех метрик на стороне Hive применяется агрегация по окну, чтобы учитывать всплески нагрузки. {#node-usage}
 
 Информация о ресурсах используется при выборе узла для таблетки: к примеру, если про некоторую таблетку известно только её потребление CPU, то будет выбран узел из числа наименее загруженных по CPU. Если известно несколько ресурсов, то используется максимум из их относительных потреблений.
 
@@ -53,3 +55,4 @@ $\mathrm{MaxUsage}$ и $\mathrm{MinUsage}$ — максимум и миниму�
 
 - [Настройка Hive](../reference/configuration/hive.md)
 - [Hive web-viewer](../reference/embedded-ui/hive.md)
+- [Запуск таблеток](hive-booting.md)
diff --git a/ydb/docs/ru/core/contributor/toc_i.yaml b/ydb/docs/ru/core/contributor/toc_i.yaml
index 72e9158480c..556e8e91a4a 100644
--- a/ydb/docs/ru/core/contributor/toc_i.yaml
+++ b/ydb/docs/ru/core/contributor/toc_i.yaml
@@ -22,6 +22,9 @@ items:
       href: localdb-uncommitted-txs.md
   - name: Hive
     href: hive.md
+    items:
+     - name: Запуск таблеток
+       href: hive-booting.md
   - name: DataShard
     items:
     - name: Локи и видимость изменений в транзакциях
diff --git a/ydb/docs/ru/core/reference/configuration/hive.md b/ydb/docs/ru/core/reference/configuration/hive.md
index 69c6ad81b90..66f19902778 100644
--- a/ydb/docs/ru/core/reference/configuration/hive.md
+++ b/ydb/docs/ru/core/reference/configuration/hive.md
@@ -4,12 +4,12 @@
 
 ## Опции запуска таблеток {#boot}
 
-С помощью этих опций можно регулировать с какой скоростью запускаются таблетки и как для них выбираются узлы.
+С помощью этих опций можно регулировать с какой скоростью [запускаются таблетки](../../contributor/hive-booting.md) и как для них [выбираются узлы](../../contributor/hive-booting.md#findbestnode).
 
 #|
 || Название параметра в конфигурации | Название параметра в Hive web-viewer | Формат | Описание | Значение по умолчанию ||
 || `max_tablets_scheduled` | MaxTabletsScheduled | Целое число | Максимальное число таблеток, одновременно находящихся в процессе старта на одном узле. | 100 ||
-|| `max_boot_batch_size` | MaxBootBatchSize | Целое число | Максимальное число таблеток из очереди запуска Hive, обрабатываемых за раз. | 1000 ||
+|| `max_boot_batch_size` | MaxBootBatchSize | Целое число | Максимальное число таблеток из [очереди запуска](../../contributor/hive-booting.md#bootqueue) Hive, обрабатываемых за раз. | 1000 ||
 || `node_select_strategy` | NodeSelectStrategy | Перечисление | Стратегия выбора узла для запуска таблетки. Возможные варианты:
 
 - `HIVE_NODE_SELECT_STRATEGY_WEIGHTED_RANDOM` — взвешенно-случайный выбор на основе потребления;