hive docs

ydb/docs/ru/core/concepts/glossary.md

@@ -355,11 +355,11 @@
 
 ### Типы таблеток {#tablet-types}
 
-[Таблетки](#tablet) можно рассматривать как фреймворк для создания надёжных компонентов, работающих в распределённой системе. Многие компоненты {{ ydb-short-name }} реализованы с использованием этого фреймворка, они перечислены ниже.
+[Таблетки](#tablet) можно рассматривать как фреймворк для создания надёжных компонентов, работающих в распределённой системе. Многие компоненты {{ ydb-short-name }} — как системные, так и работающие с пользовательскими данными — реализованы с использованием этого фреймворка, основные из них перечислены ниже.
 
 #### Scheme shard {#scheme-shard}
 
-**Scheme shard** или **SchemeShard** — это таблетка, которая хранит схему базы данных, включая метаданные пользовательских [таблиц](#table), [топиков](#topic) и т.д.
+**Scheme shard** или **SchemeShard** — это системная таблетка, которая хранит схему базы данных, включая метаданные пользовательских [таблиц](#table), [топиков](#topic) и т.д.
 
 Кроме того, существует **корневой scheme shard**, который хранит информацию о базах данных, созданных в кластере.
 
@@ -589,4 +589,4 @@ MiniKQL — это язык низкого уровня. Конечные пол
 
 ### KiKiMR {#kikimr}
 
-**KiKiMR** — это устаревшее название {{ ydb-short-name }}, использовавшееся до того, как он стал [продуктом с открытым исходным кодом](https://github.com/ydb-platform/ydb) (open source). Оно всё ещё может встречаться в исходном коде, старых статьях и видео и т.д.
+**KiKiMR** — это устаревшее название {{ ydb-short-name }}, использовавшееся до того, как он стал [продуктом с открытым исходным кодом](https://github.com/ydb-platform/ydb) (open source). Оно всё ещё может встречаться в исходном коде, старых статьях и видео и т.д.

ydb/docs/ru/core/contributor/general-schema.md

@@ -19,7 +19,9 @@
 
 ## Таблетки {#tablets}
 
-На каждом узле выполняются специальные микросервисы, которые называются *таблетками*. Каждая таблетка имеет определённый тип и идентификатор и является singleton'ом, что означает, что в каждый момент времени во всём кластере может работать только одна таблетка с конкретным идентификатором. Таблетка может запускаться на любом из подходящих для неё узлов. Важной характеристикой таблетки является её поколение — *Generation* — которое увеличивается при каждом следующем запуске. Стоит отметить, что в силу распределённости системы и наличия различного рода проблем, например, сетевого партиционирования, может сложиться ситуация, когда одна и та же таблетка будет фактически выполняться на двух разных узлах одновременно. Однако distributed storage гарантирует, что только одна из них сможет успешно завершить операции, изменяющие её состояние, и при этом поколение, в котором выполнена каждая успешная операция, не будет убывать со временем.
+На каждом узле выполняются специальные микросервисы, которые называются [таблетками](../concepts/glossary.md#tablet). Каждая таблетка имеет определённый тип и идентификатор и является singleton'ом, что означает, что в каждый момент времени во всём кластере может работать только одна таблетка с конкретным идентификатором. Таблетка может запускаться на любом из подходящих для неё узлов. Важной характеристикой таблетки является её поколение — [Generation](../concepts/glossary.md#tablet-generation) — которое увеличивается при каждом следующем запуске. Стоит отметить, что в силу распределённости системы и наличия различного рода проблем, например, сетевого партиционирования, может сложиться ситуация, когда одна и та же таблетка будет фактически выполняться на двух разных узлах одновременно. Однако distributed storage гарантирует, что только одна из них сможет успешно завершить операции, изменяющие её состояние, и при этом поколение, в котором выполнена каждая успешная операция, не будет убывать со временем.
+
+Для [системных таблеток](../concepts/glossary.md#tablet-types) кластера узел, на котором запускается таблетка, выбирается с помощью механизма Bootstrapper, реализующего [распределённый консенсус](https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D1%81%D0%B5%D0%BD%D1%81%D1%83%D1%81_%D0%B2_%D1%80%D0%B0%D1%81%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D1%91%D0%BD%D0%BD%D1%8B%D1%85_%D0%B2%D1%8B%D1%87%D0%B8%D1%81%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F%D1%85). Пользовательскими таблетками управляет специальная таблетка [Hive](hive.md). Hive следит за тем, что акутальное поколение каждой таблетки запущено ровно на одном узле, распределяет таблетки между узлами и [каналы](../concepts/glossary.md#channel) таблеток между группами хранения.
 
 Узнать, на каком узле выполняется таблетка в актуальном поколении, можно через сервис *StateStorage*. Для отправки сообщений в таблетку существует специальный набор библиотек, который называется *tablet pipe*. С его помощью, зная идентификатор целевой таблетки, можно легко послать ей нужное сообщение.
 
@@ -45,12 +47,12 @@
 
 ### История каналов в таблетке {#history}
 
-Как уже говорилось, каждая группа имеет фиксированный объём данных, которые в неё могут помещаться, а также делит полосу пропускания и число операций в секунду между всеми потребителями. Нагрузка на таблетки может меняться, и в результате может сложиться так, что группа станет перегруженной. Для этого вводится понятие истории, которое позволяет для каждой таблетки, зная Channel и Generation блоба, определить, в какую группу записан данный блоб.
+Как уже говорилось, каждая группа имеет фиксированный объём данных, которые в неё могут помещаться, а также делит полосу пропускания и число операций в секунду между всеми потребителями. Нагрузка на таблетки может меняться, и в результате может сложиться так, что группа станет перегруженной и возникнет необходимость использовать для записи другую группу. Для этого вводится понятие истории, которое позволяет для каждой таблетки, зная Channel и Generation блоба, определить, в какую группу записан данный блоб.
 
 Иллюстрация работы этого механизма приведена ниже:
 
 ![История каналов](_assets/Slide_blob.svg)
 
 Для каждого канала в структуре TTabletStorageInfo содержится подструктура TTabletChannelInfo, которая содержит диапазоны поколений и номер группы, соответствующий каждому диапазону. Диапазоны строго примыкают друг к другу, последний диапазон открыт. Номера групп могут пересекаться в разных диапазонах и даже между разными каналами — это не запрещено и достаточно часто встречается.
 
-При выполнении записи блоба таблетка выбирает самый последний диапазон для соответствующего канала, так как запись всегда идёт от имени текущего поколения таблетки. При выполнении чтения номер группы извлекается исходя из BlobId.Generation читаемого блоба.
+При выполнении записи блоба таблетка выбирает самый последний диапазон для соответствующего канала, так как запись всегда идёт от имени текущего поколения таблетки. При выполнении чтения номер группы извлекается исходя из BlobId.Generation читаемого блоба.

ydb/docs/ru/core/contributor/hive.md

@@ -0,0 +1,36 @@
+# Hive
+
+Hive — таблетка, отвечающая за управление другими таблетками. В кластере {{ ydb-short-name }} есть корневой Hive, который отвечает за [системные таблетки](../concepts/glossary.md#tablet-types) всех баз данных кластера. Hive конкретной базы данных в свою очередь отвечает за таблетки, обслуживающие пользовательскую нагрузку этой базы данных. Все узлы кластера регистрируются в корневом Hive, а в Hive конкретной базы регистрируются только вычислительные узлы этой базы. При регистрации узел сообщает в Hive, таблетки каких типов и в каких количествах могут быть на нём запущены.
+
+Создание и удаление таблеток инициируется таблеткой [SchemeShard](../concepts/glossary.md#scheme-shard). При создании таблетки Hive присваивает ей уникальный TabletId, заполняет [TabletStorageInfo](general-schema.md#history), выбирает наиболее подходящий узел и отправляет на него команду поднять таблетку. В некоторых нестандартных ситуациях отдельная таблетка может прервать работу, тогда узел, на котором она была запущена, отправляет сообщение в Hive. Также Hive предполагает, что если связь с некоторым узлом потеряна, то запущенные на нём таблетки прекратили работу. В таких ситуациях Hive запускает таблетки на других узалах с увеличением поколения.
+
+## Метрики потребления ресурсов
+
+Для распределения таблеток по узлам Hive учитывает потребление ресурсов. Для каждой таблетки учитываются потребления 4 ресурсов:
+
+1. *CPU* — потребление процессора, считается как число микросекунд, потраченных на работу таблетки за последнюю секунду и для визуализации переводится в проценты ядра.
+1. *Memory* — потребление таблеткой оперативной памяти.
+1. *Network* — генерируемый таблеткой объём трафика.
+1. *Counter* — фиктивный ресурс, используемый для реализации равномерного распределения в штуках. Применяется для любых таблеток, для которых нет данных по трём другим ресурсам, а также для таблеток колоночных таблиц. Если у таблетки есть этот ресурс, то его значение всегда равно 1.
+
+Дополнительно для определения перегруженных узлов используются метрики потребления ресурсов узла целиком: потребление оперативной памяти, и ресурсов процессора в пулах акторной системы. Эти значения переводятся в относительную величину (число от 0 до 1), и их максимум используется как значение общего потребления ресурсов узла *Node usage*. Также для всех метрик на стороне Hive используется аггрегация на окне, чтобы учитывать всплески нагрузки.
+
+## Автобалансировка
+
+В определённые моменты Hive может запустить процесс автобалансировки, перемещающий таблетки между узлами для улучшения распределения нагрузки. Далее перечислены ситуации, в которых это происходит.
+
+### Дисбаланс потребления ресурсов
+
+Для оценки сбалансированности потребления используется метрика *Scatter*, вычисляемая отдельно для каждого ресурса по формуле:
+
+$$\mathrm{Scatter} = \frac{\mathrm{MaxUsage} - \mathrm{MinUsage}}{\mathrm{MaxUsage}},$$
+
+где $\mathrm{MaxUsage}$ и $\mathrm{MinUsage}$ — соответственно максимум и минимум по потреблению данного ресурса среди всех узлов. Для нормировки потребления на каждом узле используется число доступных ресурсов на узле, которое может различаться между узлами. При низких нагрузках эта величина может сильно колебаться. Чтобы этого избежать, при вычислении $\mathrm{Scatter}$ считается, что потребление ресурса не может быть ниже 30%. Если Scatter превышает порог, запускается балансировка.
+
+### Перегруженность узла
+
+Наличие сильно загруженного узла может негативно сказываться на работе {{ ydb-short-name }}: загруженность по CPU приводит к голоданию и увеличению задержки, а загруженность по памяти может привести к падению узла по out-of-memory. Балансировка запускается, если самый загруженный узел имеет загрузку больше 90%, а наименее загруженный — меньше 70%.
+
+### Равномерное распределение конкретного объекта
+
+Для таблеток, которые используют ресурс Counter, также отслеживается равномерность распределения таблеток каждого объекта (каждой таблицы), с помощью метрики *ObjectImbalance*, аналогичной описанной выше Scatter. При рестартах узлов равномерность может нарушаться, и тогда запускается балансировка.

ydb/docs/ru/core/contributor/toc_i.yaml

@@ -15,6 +15,8 @@ items:
     items:
     - name: Персистентные незакомиченные изменения
       href: localdb-uncommitted-txs.md
+  - name: Hive
+    href: hive.md
   - name: DataShard
     items:
     - name: Локи и видимость изменений в транзакциях