From af0844f2962ed3e1ad5710c44db08e8c04323720 Mon Sep 17 00:00:00 2001 From: Oleg Doronin Date: Tue, 24 Sep 2024 10:45:53 +0200 Subject: Resource Pools and Resource Classifiers documentation (ru version) (#7649) Co-authored-by: Ivan Blinkov --- ydb/docs/presets.yaml | 2 + ydb/docs/ru/core/_assets/resource_pool.drawio | 133 +++++++++++ ydb/docs/ru/core/_assets/resource_pool.png | Bin 0 -> 44301 bytes ydb/docs/ru/core/_assets/resources_weight.drawio | 158 ++++++++++++++ ydb/docs/ru/core/_assets/resources_weight.png | Bin 0 -> 151477 bytes .../core/concepts/_includes/index/how_it_works.md | 4 + ydb/docs/ru/core/concepts/_includes/limits-ydb.md | 8 + ydb/docs/ru/core/concepts/glossary.md | 10 +- ydb/docs/ru/core/dev/index.md | 1 + .../ru/core/dev/resource-consumption-management.md | 243 +++++++++++++++++++++ ydb/docs/ru/core/dev/toc_p.yaml | 2 + .../core/reference/observability/metrics/index.md | 10 + .../resource_pool_classifier_parameters.md | 3 + .../syntax/_includes/resource_pool_parameters.md | 7 + .../syntax/alter-resource-pool-classifier.md | 55 +++++ .../yql-core/syntax/alter-resource-pool.md | 55 +++++ .../syntax/create-resource-pool-classifier.md | 53 +++++ .../yql-core/syntax/create-resource-pool.md | 59 +++++ .../syntax/drop-resource-pool-classifier.md | 35 +++ .../yql-core/syntax/drop-resource-pool.md | 35 +++ .../core/yql/reference/yql-core/syntax/toc_i.yaml | 6 + 21 files changed, 878 insertions(+), 1 deletion(-) create mode 100644 ydb/docs/ru/core/_assets/resource_pool.drawio create mode 100644 ydb/docs/ru/core/_assets/resource_pool.png create mode 100644 ydb/docs/ru/core/_assets/resources_weight.drawio create mode 100644 ydb/docs/ru/core/_assets/resources_weight.png create mode 100644 ydb/docs/ru/core/dev/resource-consumption-management.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_classifier_parameters.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_parameters.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool-classifier.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool-classifier.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool-classifier.md create mode 100644 ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool.md diff --git a/ydb/docs/presets.yaml b/ydb/docs/presets.yaml index cc8ab528941..ab6179fcc33 100644 --- a/ydb/docs/presets.yaml +++ b/ydb/docs/presets.yaml @@ -19,6 +19,8 @@ default: feature_federated_queries: true # feature_topic_settings_reset: true # feature_logbroker: true + feature_resource_pool: true + feature_resource_pool_classifier: true feature_view: true feature_async_replication: true ydb: YDB diff --git a/ydb/docs/ru/core/_assets/resource_pool.drawio b/ydb/docs/ru/core/_assets/resource_pool.drawio new file mode 100644 index 00000000000..ee6a7d7da6a --- /dev/null +++ b/ydb/docs/ru/core/_assets/resource_pool.drawio @@ -0,0 +1,133 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/ydb/docs/ru/core/_assets/resource_pool.png b/ydb/docs/ru/core/_assets/resource_pool.png new file mode 100644 index 00000000000..c9e530f67f5 Binary files /dev/null and b/ydb/docs/ru/core/_assets/resource_pool.png differ diff --git a/ydb/docs/ru/core/_assets/resources_weight.drawio b/ydb/docs/ru/core/_assets/resources_weight.drawio new file mode 100644 index 00000000000..9fe02ceb6cf --- /dev/null +++ b/ydb/docs/ru/core/_assets/resources_weight.drawio @@ -0,0 +1,158 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/ydb/docs/ru/core/_assets/resources_weight.png b/ydb/docs/ru/core/_assets/resources_weight.png new file mode 100644 index 00000000000..6e84265c170 Binary files /dev/null and b/ydb/docs/ru/core/_assets/resources_weight.png differ diff --git a/ydb/docs/ru/core/concepts/_includes/index/how_it_works.md b/ydb/docs/ru/core/concepts/_includes/index/how_it_works.md index 25ddf2e5942..8bdfcdaeb1c 100644 --- a/ydb/docs/ru/core/concepts/_includes/index/how_it_works.md +++ b/ydb/docs/ru/core/concepts/_includes/index/how_it_works.md @@ -60,3 +60,7 @@ Data shard также автоматически разделяются при ![DSProxy](https://storage.yandexcloud.net/ydb-www-prod-site-assets/howitworks/proxy%202.png) Геораспределенная и отказоустойчивая конфигурация {{ ydb-short-name }} обычно охватывает 3 датацентра или зоны доступности (Availability Zone - AZ). Когда {{ ydb-short-name }} записывает данные на 3 зоны доступности, он не отправляет запросы на явно некорректные диски и продолжает работать без прерываний даже если одна зона доступности и диск в другой зоне доступности потеряны. + +### Управление ресурсами баз данных {#db-resources} + +По умолчанию выделяемые каждой базе данных вычислительные ресурсы используются всеми запросами к ней на равных условиях, без каких-либо ограничений. Если требуется разделить ресурсы внутри одной базы данных, то в {{ ydb-short-name }} существуют [пулы ресурсов](../../glossary.md#resource-pool) и [классификаторы пулов ресурсов](../../glossary.md#resource-pool-classifier). Один из типовых сценариев применения такой функциональности — это разделение контуров онлайн-вычислений и фоновой аналитики. Подробнее о ней можно узнать в статье [{#T}](../../../dev/resource-consumption-management.md). \ No newline at end of file diff --git a/ydb/docs/ru/core/concepts/_includes/limits-ydb.md b/ydb/docs/ru/core/concepts/_includes/limits-ydb.md index 96a9344970e..1be079bbe72 100644 --- a/ydb/docs/ru/core/concepts/_includes/limits-ydb.md +++ b/ydb/docs/ru/core/concepts/_includes/limits-ydb.md @@ -64,3 +64,11 @@ | Параметр | Значение | | :--- | :--- | | Максимальный размер передаваемого сообщения | 12 Мб | + +## Ограничения пулов ресурсов {#resource_pool} + +| Параметр | Значение | +| :--- | :--- | +| Максимальное число классификаторов пулов ресурсов | 1000 | + +Ограничения на число ресурсов накладываются ограничениями на число схемных объектов. Эти ограничения можно найти [выше](limits-ydb.md#schema-object). diff --git a/ydb/docs/ru/core/concepts/glossary.md b/ydb/docs/ru/core/concepts/glossary.md index 3f79c812527..0afe66cd7af 100644 --- a/ydb/docs/ru/core/concepts/glossary.md +++ b/ydb/docs/ru/core/concepts/glossary.md @@ -210,6 +210,14 @@ **Объект-реплика** — «зеркальная копия» реплицируемого объекта, автоматически созданная экземпляром асинхронной репликации. Как правило, доступен только для чтения. +#### Пул ресурсов {#resource-pool} + +**Пул ресурсов** или **resource pool** — объект схемы, который описывает ограничения, накладываемые на ресурсы (CPU, RAM и т.п.) доступные для выполнения запросов в этом пуле ресурсов. Запрос всегда выполняется в каком-то пуле ресурсов. По умолчанию все запросы выполняются в пуле ресурсов с именем `default`, который не накладывает каких-либо ограничений. Подробнее об использовании пулов ресурсов можно узнать в статье [{#T}](../dev/resource-consumption-management.md). + +#### Классификатор пулов ресурсов {#resource-pool-classifier} + +**Классификатор пулов ресурсов** или **resource pool classifier** — объект, предназначенный для управления распределением запросов между [пулами ресурсов](#resource-pool). Он описывает правила, по которым для каждого запроса выбирается пул ресурсов. Эти классификаторы глобальны для всей [базы данных](#database) и применяются ко всем запросам, поступающим в неё. Подробнее об их использовании можно узнать в статье [{#T}](../dev/resource-consumption-management.md). + ### YQL {#yql} **YQL ({{ ydb-short-name }} Query Language)** — это высокоуровневый язык для работы с системой. Он является диалектом [ANSI SQL](https://en.wikipedia.org/wiki/SQL). Существует много материалов, посвящённых YQL, включая [туториал](../dev/yql-tutorial/index.md), [справочник](../yql/reference/syntax/index.md) и [рецепты](../recipes/yql/index.md). @@ -577,4 +585,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). Оно всё ещё может встречаться в исходном коде, старых статьях и видео и т.д. \ No newline at end of file diff --git a/ydb/docs/ru/core/dev/index.md b/ydb/docs/ru/core/dev/index.md index 4f5ec5992d8..d831b93fbd4 100644 --- a/ydb/docs/ru/core/dev/index.md +++ b/ydb/docs/ru/core/dev/index.md @@ -17,6 +17,7 @@ - [{#T}](system-views.md) - [{#T}](cdc.md) - [{#T}](custom-attributes.md) +- [{#T}](resource-consumption-management.md) - Справка: - [{#T}](../yql/reference/index.md) diff --git a/ydb/docs/ru/core/dev/resource-consumption-management.md b/ydb/docs/ru/core/dev/resource-consumption-management.md new file mode 100644 index 00000000000..48ec13c3750 --- /dev/null +++ b/ydb/docs/ru/core/dev/resource-consumption-management.md @@ -0,0 +1,243 @@ +# Workload Manager — управление потреблением ресурсов + +[Пулы ресурсов](../concepts/glossary.md#resource-pool) позволяют изолировать ресурсы [баз данных](../concepts/glossary.md#database) между выполняемыми запросами или же настраивать стратегии распределения ресурсов в случае переподписки (запроса большего объёма ресурсов, чем доступно в системе). Все пулы ресурсов являются равноправными, без какой-либо иерархии, и влияют друг на друга только при общем дефиците ресурсов. + +Например, одним из типовых сценариев изоляции ресурсов является разделение двух классов потребителей: + +1. Регулярный роботный процесс, который раз в сутки строит отчёт. +2. Аналитики, которые выполняют ad hoc запросы. + +{% note warning %} + +Представленная функциональность для управления потреблением ресурсами находится в стадии Preview. + +{% endnote %} + +## Создание пула ресурсов + +В примере ниже приведён синтаксис для создания отдельного пула ресурсов с именем "olap", в котором будут выполняться аналитические запросы: + +```yql +CREATE RESOURCE POOL olap WITH ( + CONCURRENT_QUERY_LIMIT=10, + QUEUE_SIZE=1000, + DATABASE_LOAD_CPU_THRESHOLD=80, + RESOURCES_WEIGHT=100, + QUERY_CPU_LIMIT_PERCENT_PER_NODE=50, + TOTAL_CPU_LIMIT_PERCENT_PER_NODE=70 +) +``` + +Ознакомиться с полным перечнем параметров пулов ресурсов можно в справке по [{#T}](../yql/reference/syntax/create-resource-pool.md#parameters). Часть параметров является глобальными для всей базы данных (например, `CONCURRENT_QUERY_LIMIT`, `QUEUE_SIZE`, `DATABASE_LOAD_CPU_THRESHOLD`), а другие — применяются только к одному вычислительному узлу (например, `QUERY_CPU_LIMIT_PERCENT_PER_NODE`, `TOTAL_CPU_LIMIT_PERCENT_PER_NODE`, `QUERY_MEMORY_LIMIT_PERCENT_PER_NODE`). Между всеми пулами может разделяться CPU в случае переподписки на одном вычислительном узле с помощью `RESOURCES_WEIGHT`. + +![resource_pools](../_assets/resource_pool.png) + +Рассмотрим на примере выше, что на самом деле означают эти параметры и как они будут влиять на распределение ресурсов. Допустим, в базе данных {{ ydb-short-name }} выделено $10$ узлов по $10 vCPU$. В сумме в такой базе данных $100 vCPU$. Тогда на каждом узле для пула ресурсов с именем `olap` будет выделено: + +$\frac{10 vCPU \cdot TOTAL\_CPU\_LIMIT\_PERCENT\_PER\_NODE}{100} = 10 vCPU \cdot 0.7 = 7 vCPU$ + +В сумме, при равномерном распределении ресурсов на всю базу данных, пулу ресурсов будет выделено: + +$7 vCPU \cdot 10 \text{ (nodes)} = 70 vCPU$ + +На один запрос в этом пуле ресурсов будет выделено: + +$\frac{10 vCPU \cdot TOTAL\_CPU\_LIMIT\_PERCENT\_PER\_NODE}{100} \cdot \frac{QUERY\_CPU\_LIMIT\_PERCENT\_PER\_NODE}{100} = 10 vCPU \cdot 0.7 \cdot 0.5 = 3.5 vCPU$ + +### Как работает CONCURRENT_QUERY_LIMIT и QUEUE_SIZE {#concurrent_query_limit} + +Допустим, в пуле ресурсов `olap` уже выполняются 9 запросов. При поступлении нового запроса он сразу начнёт выполняться параллельно с другими 9-ю запросами. Теперь в пуле будет работать 10 запросов. Если в пул поступит 11-й запрос, он не начнёт выполняться, а будет помещён в очередь ожидания. Когда хотя бы один из 10 выполняющихся запросов завершится, 11-й запрос будет извлечён из очереди и начнёт выполняться. + +Если в очереди уже находится $QUEUE\_SIZE = 1000$ запросов, то при отправке 1001-го запроса клиент сразу же получит в ответ ошибку, и этот запрос не будет выполнен. Пример ошибки: + +```text +Issues: +
: Error: Request was rejected, number of local pending requests is 20, number of global delayed/running requests is 0, sum of them is larger than allowed limit 1 (including concurrent query limit 1) for pool olap +
: Error: Query failed during adding/waiting in workload pool olap +``` + +На число параллельно выполняемых запросов влияет не только `CONCURRENT_QUERY_LIMIT`, но и `DATABASE_LOAD_CPU_THRESHOLD`. + +### Как работает DATABASE_LOAD_CPU_THRESHOLD {#database_load_cpu_threshold} + +Когда запрос поступает в пул ресурсов, для которого установлен `DATABASE_LOAD_CPU_THRESHOLD`, сразу резервируется 10% от доступного CPU на узле, исходя из предположения, что запрос как минимум потребует такой объём ресурсов. Затем каждые 10 секунд происходит перерасчёт потребляемых ресурсов по всей базе данных, что позволяет уточнить первоначальную 10%-ную оценку. Это означает, что если на узел кластера одновременно поступит более 10 запросов, то не более 10 запросов будут запущены на выполнение, а остальные будут ожидать уточнения фактического потребления CPU. + +Как и в случае `CONCURRENT_QUERY_LIMIT`, при превышении указанного порога нагрузки запросы отправляются в очередь ожидания. + +### Распределение ресурсов в соответствии с RESOURCES_WEIGHT {#resources_weight} + +![resource_pools](../_assets/resources_weight.png) + +Параметр `RESOURCES_WEIGHT` начинает работать только в случае переподписки и при наличии более одного пула ресурсов в системе. В текущей реализации `RESOURCES_WEIGHT` влияет только на распределение ресурсов `vCPU`. Когда в пуле ресурсов появляются запросы, он начинает участвовать в распределении ресурсов. Для этого в пулах происходит перерасчёт лимитов согласно алгоритму [Max-min fairness](https://en.wikipedia.org/wiki/Max-min_fairness). Само перераспределение ресурсов выполняется на каждом вычислительном узле индивидуально, как показано на рисунке выше. + +Допустим, у нас есть узел в системе с доступными $10 vCPU$. Установлены ограничения: + +- $TOTAL\_CPU\_LIMIT\_PERCENT\_PER\_NODE = 30$, +- $QUERY\_CPU\_LIMIT\_PERCENT\_PER\_NODE = 50$. + +В этом случае у пула ресурсов будет ограничение $3 vCPU$ на узел и $1.5 vCPU$ на один запрос в этом пуле (рисунок *a*). Если в системе существует 4 таких пула, и все они пытаются использовать максимальные ресурсы, это составит $12 vCPU$, что превышает предел доступных ресурсов на узле ($10 vCPU$). В этом случае начинают действовать `RESOURCES_WEIGHT`, и каждому пулу будет выделено по $2.5 vCPU$ (рисунок *b*). + +Если необходимо увеличить выделяемые ресурсы для конкретного пула, можно изменить его вес, например, на 200. Тогда этот пул получит $3 vCPU$, а остальные пулы поделят поровну оставшиеся $7 vCPU$, что составит $\frac{7}{3} vCPU$ на каждый пул (рисунок *c*). + +{% note warning %} + +Текущий алгоритм распределения ресурсов может быть изменен в будущем без поддержки обратной совместимости. + +{% endnote %} + +## Пул ресурсов по умолчанию + +Даже если ни одного пула ресурсов не было создано, в системе всегда существует пул ресурсов `default`, который не может быть удалён. Любой запрос, выполняющийся в системе, всегда принадлежит какому-либо пулу — ситуации, когда запрос не привязан ни к одному пулу ресурсов, не бывает. По умолчанию настройки пула ресурсов `default` выглядят следующим образом: + +```yql +CREATE RESOURCE POOL default WITH ( + CONCURRENT_QUERY_LIMIT=-1, + QUEUE_SIZE=-1, + DATABASE_LOAD_CPU_THRESHOLD=-1, + RESOURCES_WEIGHT=-1, + QUERY_MEMORY_LIMIT_PERCENT_PER_NODE=-1, + QUERY_CPU_LIMIT_PERCENT_PER_NODE=-1, + TOTAL_CPU_LIMIT_PERCENT_PER_NODE=-1 +) +``` + +Это означает, что в пуле ресурсов `default` не применяются никакие ограничения: он функционирует независимо от других пулов и не имеет ограничений на потребляемые ресурсы. В пуле ресурсов `default` можно изменять параметры с помощью запроса [{#T}](../yql/reference/syntax/alter-resource-pool.md), за исключением параметров `CONCURRENT_QUERY_LIMIT`, `DATABASE_LOAD_CPU_THRESHOLD` и `QUEUE_SIZE`. Это ограничение введено намеренно, чтобы минимизировать риски, связанные с некорректной настройкой пула ресурсов по умолчанию. + +## Управление ACL пула ресурсов + +Для создания, изменения или удаления пула ресурсов необходимо выдать права доступа в соответствии с разрешениями, описанными в справке по [{#T}](../yql/reference/syntax/create-resource-pool.md). Например, для создания пулов ресурсов нужно иметь разрешение `CREATE TABLE` на директорию `.metadata/workload_manager/pools`, которое можно выдать запросом следующего вида: + +```yql +GRANT CREATE TABLE ON `.metadata/workload_manager/pools` TO user1; +``` + +## Создание классификатора пула ресурсов + +[Классификаторы пулов ресурсов](../concepts/glossary.md#resource-pool-classifier) позволяют задавать правила, по которым запросы будут распределяться между пулами ресурсов. В примере ниже приведён классификатор пула ресурсов, который отправляет запросы от всех пользователей в пул ресурсов с именем `olap`: + +```yql +CREATE RESOURCE POOL CLASSIFIER olap_classifier +WITH ( + RESOURCE_POOL = 'olap', + MEMBER_NAME = 'all-users@well-known' +); +``` + +- `RESOURCE_POOL` — имя пула ресурсов, в который будет отправлен запрос, удовлетворяющий требованиям, заданным в классификаторе пула ресурсов. +- `MEMBER_NAME` — группа пользователей или пользователь, запросы которых будут отправлены в указанный пул ресурсов. + +## Управление ACL классификатора пула ресурсов + +Ограничений на использование классификатора пула ресурсов нет — они глобальны для всей базы данных и доступны всем пользователям. Для создания, удаления или изменения классификатора пула ресурсов необходимо иметь разрешение `ALL` на всю базу данных, которое можно выдать запросом вида: + +```yql +GRANT ALL ON `/my_db` TO user1; +``` + +Для использования классификатора пула ресурсов у пользователя должен быть доступ к пулу ресурсов, на который ссылается данный классификатор. + +## Порядок выбора классификатора пула ресурсов в случае конфликтов + +```yql +CREATE RESOURCE POOL CLASSIFIER olap1_classifier +WITH ( + RESOURCE_POOL = 'olap1', + MEMBER_NAME = 'user1@domain' +); + +CREATE RESOURCE POOL CLASSIFIER olap2_classifier +WITH ( + RESOURCE_POOL = 'olap2', + MEMBER_NAME = 'user1@domain' +); +``` + +Допустим, имеются два классификатора пулов ресурсов с конфликтующими условиями, и пользователь `user1@domain` подходит под оба пула ресурсов: `olap1` и `olap2`. Если до этого в системе не существовало ни одного классификатора, то для `olap1` устанавливается `RANK=1000`, а для `olap2` — `RANK=2000`. Классификаторы пулов ресурсов с меньшим значением `RANK` имеют более высокий приоритет. В данном примере, так как у `olap1` более приоритетный `RANK`, чем у `olap2`, будет выбран именно он. + +Также можно самостоятельно задавать `RANK` для классификаторов пулов ресурсов при создании с помощью синтаксической конструкции [{#T}](../yql/reference/syntax/create-resource-pool-classifier.md), либо изменять `RANK` для существующих классификаторов пулов ресурсов с помощью [{#T}](../yql/reference/syntax/alter-resource-pool-classifier.md). + +В системе не может существовать два классификатора с одинаковым значением `RANK`, что позволяет однозначно определить, какой пул ресурсов будет выбран в случае конфликтующих условий. + +## Пример приоритетного пула ресурсов + +Рассмотрим пример задачи распределения ресурсов между командой аналитиков и условным директором (CEO). Для CEO важно иметь приоритет над вычислительными ресурсами, которые используются для аналитических задач, однако полезно обеспечить возможность команде аналитиков утилизировать больше ресурсов кластера в те периоды времени, когда CEO не использует ресурсы. Конфигурация для этого сценария может выглядеть следующим образом: + +```yql +CREATE RESOURCE POOL olap WITH ( + CONCURRENT_QUERY_LIMIT=20, + QUEUE_SIZE=100, + DATABASE_LOAD_CPU_THRESHOLD=80, + RESOURCES_WEIGHT=20, + QUERY_CPU_LIMIT_PERCENT_PER_NODE=80, + TOTAL_CPU_LIMIT_PERCENT_PER_NODE=100 +); + +CREATE RESOURCE POOL the_ceo WITH ( + CONCURRENT_QUERY_LIMIT=20, + QUEUE_SIZE=100, + RESOURCES_WEIGHT=100, + QUERY_CPU_LIMIT_PERCENT_PER_NODE=100, + TOTAL_CPU_LIMIT_PERCENT_PER_NODE=100 +); +``` + +В примере выше создаются два пула ресурсов: `olap` для команды аналитиков и `the_ceo` для CEO. + +- **Пул ресурсов `olap`**: + + - Имеет вес 20. + - Ограничение на запускаемые запросы при перегрузке базы данных составляет 80% доступных ресурсов. + +- **Пул ресурсов `the_ceo`**: + + - Имеет больший вес — 80. + - Не имеет ограничений на запускаемые запросы при перегрузке. + +Вес 80 для `the_ceo` фактически означает, что при конкуренции за ресурсы пул `the_ceo` будет получать приоритет в 4 раза больше, чем пул `olap`. Если в оба пула поступают запросы, система пересчитает лимиты, и для `olap` лимит `TOTAL_CPU_LIMIT_PERCENT_PER_NODE` будет сокращён до 20%, а для `the_ceo` — увеличен до 80%. Это перераспределение ресурсов основано на весах, как описано [выше](#resources_weight). + +## Диагностика + +### План запроса + +Подробную информацию о планах запросов можно найти на странице [структура планов запросов](../yql/query_plans.md). Для получения информации об используемом пуле ресурсов необходимо запустить команду с получением статистики в формате `json-unicode`. Пример команды: + +```bash +ydb -p sql -s 'select 1' --stats full --format json-unicode +``` + +В теле плана запроса, полученного с помощью приведённой выше команды, можно найти полезные атрибуты для диагностики работы с пулом ресурсов. Пример такой информации: + +```json +"Node Type" : "Query", +"Stats" : { + "TotalDurationUs": 28795, + "ProcessCpuTimeUs": 45, + "Compilation": { + "FromCache": false, + "CpuTimeUs": 7280, + "DurationUs": 21700 + }, + "ResourcePoolId": "default", + "QueuedTimeUs": 0 +}, +"PlanNodeType" : "Query" +``` + +Полезные атрибуты: + +- `TotalDurationUs` — общее время выполнения запроса, включая время ожидания в очереди. +- `ResourcePoolId` — имя пула ресурсов, к которому был привязан запрос. +- `QueuedTimeUs` — общее время ожидания запроса в очереди. + +### Метрики + +Информацию о метриках пулов ресурсов можно найти в [справке по метрикам](../reference/observability/metrics/index.md#resource_pools). + +## См. также + +* [{#T}](../yql/reference/syntax/create-resource-pool.md) +* [{#T}](../yql/reference/syntax/alter-resource-pool.md) +* [{#T}](../yql/reference/syntax/drop-resource-pool.md) +* [{#T}](../yql/reference/syntax/create-resource-pool-classifier.md) +* [{#T}](../yql/reference/syntax/alter-resource-pool-classifier.md) +* [{#T}](../yql/reference/syntax/drop-resource-pool-classifier.md) diff --git a/ydb/docs/ru/core/dev/toc_p.yaml b/ydb/docs/ru/core/dev/toc_p.yaml index add8bb052d9..c850c49faf2 100644 --- a/ydb/docs/ru/core/dev/toc_p.yaml +++ b/ydb/docs/ru/core/dev/toc_p.yaml @@ -34,3 +34,5 @@ items: href: terraform.md - name: Пользовательские атрибуты href: custom-attributes.md +- name: Управление потреблением ресурсов + href: resource-consumption-management.md diff --git a/ydb/docs/ru/core/reference/observability/metrics/index.md b/ydb/docs/ru/core/reference/observability/metrics/index.md index a70274a9497..00388f17bb0 100644 --- a/ydb/docs/ru/core/reference/observability/metrics/index.md +++ b/ydb/docs/ru/core/reference/observability/metrics/index.md @@ -188,3 +188,13 @@ `topic.partition.write.bytes_per_hour_max`
`GAUGE`, байты | Максимальное количество байт, записанное за последний час, по всем партициям.
Метки:
- _topic_ – название топика. `topic.partition.write.bytes_per_minute_max`
`GAUGE`, байты | Максимальное количество байт, записанное за последнюю минуту, по всем партициям.
Метки:
- _topic_ – название топика. `topic.partition.write.idle_milliseconds_max`
`GAUGE`, миллисекунды | Максимальное время простоя партиции на запись.
Метки:
- _topic_ – название топика. + +## Метрики пулов ресурсов {#resource_pools} + +Имя метрики
Тип, единицы измерения | Описание
Метки +----- | ----- +`kqp.workload_manager.CpuQuotaManager.AverageLoadPercentage`
`RATE`, штуки | Средняя загрузка базы данных, по этой метрики работает `DATABASE_LOAD_CPU_THRESHOLD`. +`kqp.workload_manager.InFlightLimit`
`GAUGE`, штуки | Лимит на число одновременно работающих запросов. +`kqp.workload_manager.GlobalInFly`
`GAUGE`, штуки | Текущее число одновременно работающих запросов. Отображаются только для пулов с включенным `CONCURRENT_QUERY_LIMIT` или `DATABASE_LOAD_CPU_THRESHOLD`. +`kqp.workload_manager.QueueSizeLimit`
`GAUGE`, штуки | Размер очереди запросов, ожидающих выполнения. +`kqp.workload_manager.GlobalDelayedRequests`
`GAUGE`, штуки | Количество запросов, ожидающих в очереди на выполнение. Отображаются только для пулов с включенным `CONCURRENT_QUERY_LIMIT` или `DATABASE_LOAD_CPU_THRESHOLD`. \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_classifier_parameters.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_classifier_parameters.md new file mode 100644 index 00000000000..8601ae1968c --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_classifier_parameters.md @@ -0,0 +1,3 @@ +* `RANK` (Int64) — опциональное поле, задающее порядок выбора классификатора пула ресурсов. Если значение не указано, берётся максимальный существующий `RANK` и к нему прибавляется 1000. Допустимые значения: уникальное число в диапазоне $[0, 2^{63}-1]$. +* `RESOURCE_POOL` (String) — обязательное поле, задающее имя пула ресурсов, в который будут отправлены запросы, удовлетворяющие критериям классификатора. +* `MEMBER_NAME` (String) — опциональное поле, определяющее, какой пользователь или группа пользователей будут отправлены в указанный пул ресурсов. Если поле не указано, классификатор игнорирует `MEMBER_NAME`, и классификация осуществляется по другим признакам. \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_parameters.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_parameters.md new file mode 100644 index 00000000000..4739c90250c --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/resource_pool_parameters.md @@ -0,0 +1,7 @@ +* `CONCURRENT_QUERY_LIMIT` (Int32) — опциональное поле, задающее количество параллельно выполняющихся запросов в пуле ресурсов. Если значение `-1`, то ограничений нет. Значение по умолчанию: `-1`. Допустимые значения: $-1, [0, 2^{31}-1]$. +* `QUEUE_SIZE` (Int32) — опциональное поле, определяющее размер очереди ожидания. Всего в системе может находиться не более чем $CONCURRENT\_QUERY\_LIMIT + QUEUE\_SIZE$ запросов одновременно. Если значение `-1`, ограничений нет. Значение по умолчанию: `-1`. Допустимые значения: $-1, [0, 2^{31}-1]$. +* `DATABASE_LOAD_CPU_THRESHOLD` (Int32) — опциональное поле, задающее порог загрузки CPU всей базы данных, после которого запросы не отправляются на выполнение и остаются в очереди. Если значение `-1`, ограничений нет. Значение по умолчанию: `-1`. Допустимые значения: $-1, [0, 100]$. +* `QUERY_MEMORY_LIMIT_PERCENT_PER_NODE` (Double) — опциональное поле, определяющее процент доступной памяти на узле, который может использовать запрос в данном пуле ресурсов. Если значение `-1`, действует ограничение на общую доступную память между всеми запросами. Значение по умолчанию: `-1`. Допустимые значения: $-1, [0, 100]$. +* `TOTAL_CPU_LIMIT_PERCENT_PER_NODE` (Double) — опциональное поле, задающее процент доступного CPU, который могут использовать все запросы на узле в данном пуле ресурсов. Если значение `-1`, ограничений нет. Значение по умолчанию: `-1`. Допустимые значения: $-1, [0, 100]$. +* `QUERY_CPU_LIMIT_PERCENT_PER_NODE` (Double) — опциональное поле, определяющее процент доступного CPU на узле для одного запроса в пуле ресурсов. Если значение `-1`, ограничений нет. Значение по умолчанию: `-1`. Допустимые значения: $-1, [0, 100]$. +* `RESOURCE_WEIGHT` (Int32) — опциональное поле, задающее веса для распределения ресурсов между пулами. Если значение `-1`, веса не используются. Значение по умолчанию: `-1`. Допустимые значения: $-1, [0, 2^{31}-1]$. \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool-classifier.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool-classifier.md new file mode 100644 index 00000000000..38f231e80f6 --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool-classifier.md @@ -0,0 +1,55 @@ +# ALTER RESOURCE POOL CLASSIFIER + +`ALTER RESOURCE POOL CLASSIFIER` изменяет определение [классификатора пула ресурсов](../../../concepts/glossary.md#resource-pool-classifier.md). + +## Синтаксис + +### Изменение параметров + +Синтаксис для изменения любого параметра классификатора пула ресурсов выглядит следующим образом: + +```yql +ALTER RESOURCE POOL CLASSIFIER SET ( = ); +``` + +`` — имя параметра, `` — его новое значение. + +Например, такая команда изменит пользователя, для которого применяется правило: + +```yql +ALTER RESOURCE POOL CLASSIFIER olap_classifier SET (MEMBER_NAME = "user2@domain"); +``` + +### Сброс параметров + +Команда для сброса параметра классификатора пула ресурсов выглядит следующим образом: + +```yql +ALTER RESOURCE POOL CLASSIFIER RESET (); +``` + +`` — имя параметра. + +Например, такая команда сбросит настройку `MEMBER_NAME`: + +```yql +ALTER RESOURCE POOL CLASSIFIER olap_classifier RESET (MEMBER_NAME); +``` + +## Разрешения + +Требуется [разрешение](grant.md#permissions-list) `ALL` на базу данных, пример выдачи такого разрешения: + +```yql +GRANT 'ALL' ON `/my_db` TO `user1@domain`; +``` + +## Параметры + +{% include [x](_includes/resource_pool_classifier_parameters.md) %} + +## См. также + +* [{#T}](../../../dev/resource-consumption-management.md) +* [{#T}](create-resource-pool-classifier.md) +* [{#T}](drop-resource-pool-classifier.md) \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool.md new file mode 100644 index 00000000000..df1aeb77e91 --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-resource-pool.md @@ -0,0 +1,55 @@ +# ALTER RESOURCE POOL + +`ALTER RESOURCE POOL` изменяет определение [пула ресурсов](../../../concepts/glossary.md#resource-pool.md). + +## Синтаксис + +### Изменение параметров + +Синтаксис для изменения любого параметра пула ресурсов выглядит следующим образом: + +```yql +ALTER RESOURCE POOL SET ( = ); +``` + +`` — имя параметра, `` — его новое значение. + +Например, такая команда включит ограничение на число параллельных запросов, равное 100: + +```yql +ALTER RESOURCE POOL olap SET (CONCURRENT_QUERY_LIMIT = "100"); +``` + +### Сброс параметров + +Команда для сброса параметра пула ресурсов выглядит следующим образом: + +```yql +ALTER RESOURCE POOL RESET (); +``` + +`````` — имя параметра. + +Например, такая команда сбросит настройки `TOTAL_CPU_LIMIT_PERCENT_PER_NODE` для пула ресурсов: + +```yql +ALTER RESOURCE POOL olap RESET (TOTAL_CPU_LIMIT_PERCENT_PER_NODE); +``` + +## Разрешения + +Требуется [разрешение](grant.md#permissions-list) `ALTER SCHEMA` на пул ресурсов в директории `.metadata/workload_manager/pools`, пример выдачи такого разрешения: + +```yql +GRANT 'ALTER SCHEMA' ON `.metadata/workload_manager/pools/olap_pool` TO `user1@domain`; +``` + +## Параметры + +{% include [x](_includes/resource_pool_parameters.md) %} + +## См. также + +* [{#T}](../../../dev/resource-consumption-management.md) +* [{#T}](create-resource-pool.md) +* [{#T}](drop-resource-pool.md) \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool-classifier.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool-classifier.md new file mode 100644 index 00000000000..bd433e71176 --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool-classifier.md @@ -0,0 +1,53 @@ +# CREATE RESOURCE POOL CLASSIFIER + +`CREATE RESOURCE POOL CLASSIFIER` создаёт [пул классификаторов ресурсов](../../../../concepts/gloassary#resource-pool-classifier.md). + +## Синтаксис + +```yql +CREATE RESOURCE POOL CLASSIFIER +WITH ( [= ] [, ... ] ) +``` + +- `name` — имя создаваемого классификатора пула ресурсов. Должно быть уникальным. Имя не должно содержать символы, запрещённые для схемных объектов. +- `WITH ( [= ] [, ... ] )` — позволяет задавать значения параметров, определяющих поведение классификатора пула ресурсов. + +### Параметры + +{% include [x](_includes/resource_pool_classifier_parameters.md) %} + +## Замечания {#remarks} + +Если в DDL для создания классификатора пула ресурсов не указан `RANK`, то по умолчанию ему будет присвоено значение $RANK = MAX(existing\_ranks) + 1000$. Все значения `RANK` должны быть уникальными, чтобы обеспечить строго детерминированный порядок выбора пула ресурсов в случае конфликтующих условий. Такое поведение выбрано для возможности добавлять новые классификаторы пулов ресурсов между уже существующими. + +Также возможно наличие классификатора, который ссылается на несуществующий пул ресурсов или к которому у пользователя нет доступа. В таком случае такие классификаторы будут пропускаться. + +С ограничениями на число классификаторов можно ознакомиться на странице [ограничений](../../../../concepts/limits-ydb#resource_pool). + +## Разрешения + +Требуется [разрешение](../yql/reference/syntax/grant#permissions-list) `ALL` на базу данных + +Пример выдачи такого разрешения: + +```yql +GRANT 'ALL' ON `/my_db` TO `user1@domain`; +``` + +## Примеры {#examples} + +```yql +CREATE RESOURCE POOL CLASSIFIER olap_classifier WITH ( + RANK=1000, + RESOURCE_POOL="olap", + MEMBER_NAME="user1@domain" +) +``` + +В примере выше создаётся классификатор пула ресурсов с именем `olap_classifier`, который направляет запросы от пользователя `user1@domain` в пул ресурсов с именем `olap`. Запросы от всех остальных пользователей будут отправляться в пул ресурсов `default`, при условии, что других классификаторов пулов ресурсов не существует. + +## См. также + +* [{#T}](../../../dev/resource-consumption-management.md) +* [{#T}](alter-resource-pool-classifier.md) +* [{#T}](drop-resource-pool-classifier.md) diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool.md new file mode 100644 index 00000000000..45e95ea76ab --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create-resource-pool.md @@ -0,0 +1,59 @@ +# CREATE RESOURCE POOL + +`CREATE RESOURCE POOL` создаёт [пул ресурсов](../../../concepts/glossary.md#resource-pool.md). + +## Синтаксис + +```yql +CREATE RESOURCE POOL +WITH ( [= ] [, ... ] ) +``` + +* `name` - имя создаваемого пула ресурсов. Должно быть уникально. Не допускается запись в виде пути (т.е. не должно содержать `/`). +* `WITH ( [= ] [, ... ] )` позволяет задать значения параметров, определяющих поведение пула ресурсов. + +### Параметры {#parameters} + +{% include [x](_includes/resource_pool_parameters.md) %} + +## Замечания {#remark} + +Запросы всегда выполняются в каком-либо пуле ресурсов. По умолчанию все запросы отправляются в пул ресурсов `default`, который создаётся автоматически и не может быть удалён — он всегда присутствует в системе. + +Если для параметра `CONCURRENT_QUERY_LIMIT` установить значение 0, то все запросы, отправленные в этот пул, будут немедленно завершены со статусом `PRECONDITION_FAILED`. + +## Разрешения + +Требуется [разрешение](../yql/reference/syntax/grant#permissions-list) `CREATE TABLE` на директорию `.metadata/workload_manager/pools`, пример выдачи такого разрешения: + +```yql +GRANT 'CREATE TABLE' ON `.metadata/workload_manager/pools` TO `user1@domain`; +``` + +## Примеры {#examples} + +```yql +CREATE RESOURCE POOL olap WITH ( + CONCURRENT_QUERY_LIMIT=20, + QUEUE_SIZE=1000, + DATABASE_LOAD_CPU_THRESHOLD=80, + RESOURCE_WEIGHT=100, + QUERY_MEMORY_LIMIT_PERCENT_PER_NODE=80, + TOTAL_CPU_LIMIT_PERCENT_PER_NODE=70 +) +``` + +В примере выше создаётся пул ресурсов со следующими ограничениями: + +- Максимальное число параллельных запросов — 20. +- Максимальный размер очереди ожидания — 1000. +- При достижении загрузки базы данных в 80%, запросы перестают запускаться параллельно. +- Каждый запрос в пуле может потребить не более 80% доступной памяти на узле. Если запрос превысит этот лимит, он будет завершён со статусом `OVERLOADED`. +- Общее ограничение на доступный CPU для всех запросов в пуле на узле составляет 70%. +- Пул ресурсов имеет вес 100, который начинает работать только в случае переподписки. + +## См. также + +* [{#T}](../../../dev/resource-consumption-management.md) +* [{#T}](alter-resource-pool.md) +* [{#T}](drop-resource-pool.md) \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool-classifier.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool-classifier.md new file mode 100644 index 00000000000..717c8a3471d --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool-classifier.md @@ -0,0 +1,35 @@ +# DROP RESOURCE POOL CLASSIFIER + +`DROP RESOURCE POOL CLASSIFIER` удаляет [классификатор пулов ресурсов](../../../../concepts/gloassary#resource-pool-classifier). + +## Синтаксис + +```yql +DROP RESOURCE POOL CLASSIFIER +``` + +### Параметры + +* `name` - имя классификатора пула ресурсов, подлежащего удалению. + +## Разрешения + +Требуется [разрешение](../yql/reference/syntax/grant#permissions-list) `ALL` на базу данных, пример выдачи такого разрешения: + +```yql +GRANT 'ALL' ON `/my_db` TO `user1@domain`; +``` + +## Примеры + +Следующая команда удалит классификатор пула ресурсов с именем "olap_classifier": + +```yql +DROP RESOURCE POOL CLASSIFIER olap_classifier; +``` + +## См. также + +* [{#T}](../../../dev/resource-consumption-management.md) +* [{#T}](create-resource-pool-classifier.md) +* [{#T}](alter-resource-pool-classifier.md) \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool.md new file mode 100644 index 00000000000..906f81dbac5 --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop-resource-pool.md @@ -0,0 +1,35 @@ +# DROP RESOURCE POOL + +`DROP RESOURCE POOL` удаляет [пул ресурсов](../../../../concepts/gloassary#resource-pool). + +## Синтаксис + +```yql +DROP RESOURCE POOL +``` + +### Параметры + +* `name` - имя пула ресурсов, подлежащего удалению. + +## Разрешения + +Требуется [разрешение](../yql/reference/syntax/grant#permissions-list) `REMOVE SCHEMA` до пула в директории `.metadata/workload_manager/pools`, пример выдачи такого разрешения: + +```yql +GRANT 'REMOVE SCHEMA`' ON `.metadata/workload_manager/pools` TO `user1@domain`; +``` + +## Примеры + +Следующая команда удалит пул ресурсов с именем "olap": + +```yql +DROP RESOURCE POOL olap; +``` + +## См. также + +* [{#T}](../../../dev/resource-consumption-management.md) +* [{#T}](create-resource-pool.md) +* [{#T}](alter-resource-pool.md) \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml b/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml index af293a2baf8..911e1b304f4 100644 --- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml @@ -7,6 +7,8 @@ items: - { name: ALTER GROUP, href: alter-group.md, when: feature_user_and_group } - { name: ALTER TABLE, include: { mode: link, path: alter_table/toc_p.yaml }, when: feature_map_tables } - { name: ALTER VIEW, href: alter-view.md, when: feature_view } +- { name: ALTER RESOURCE POOL, href: alter-resource-pool.md, when: feature_resource_pool } +- { name: ALTER RESOURCE POOL CLASSIFIER, href: alter-resource-pool-classifier.md, when: feature_resource_pool_classifier } - { name: ALTER TOPIC, href: alter-topic.md, when: feature_topic_control_plane } - { name: ALTER USER, href: alter-user.md, when: feature_user_and_group } - { name: ANALYZE, href: analyze.md, when: backend_name == "YDB" } @@ -18,6 +20,8 @@ items: - { name: CREATE OBJECT TYPE SECRET_ACCESS, href: create-object-type-secret-access.md, when: feature_federated_queries} - { name: CREATE TABLE, include: { mode: link, path: create_table/toc_p.yaml } } - { name: CREATE VIEW, href: create-view.md, when: feature_view } +- { name: CREATE RESOURCE POOL, href: create-resource-pool.md, when: feature_resource_pool } +- { name: CREATE RESOURCE POOL CLASSIFIER, href: create-resource-pool-classifier.md, when: feature_resource_pool_classifier } - { name: CREATE TOPIC, href: create-topic.md, when: feature_topic_control_plane } - { name: CREATE USER, href: create-user.md, when: feature_user_and_group } - { name: COMMIT, href: commit.md } @@ -32,6 +36,8 @@ items: - { name: DROP OBJECT TYPE SECRET_ACCESS, href: drop-object-type-secret-access.md, when: feature_federated_queries} - { name: DROP TABLE, href: drop_table.md } - { name: DROP VIEW, href: drop-view.md, when: feature_view } +- { name: DROP RESOURCE POOL, href: drop-resource-pool.md, when: feature_resource_pool } +- { name: DROP RESOURCE POOL CLASSIFIER, href: drop-resource-pool-classifier.md, when: feature_resource_pool_classifier } - { name: DROP TOPIC, href: drop-topic.md, when: feature_topic_control_plane } - { name: DROP USER, href: drop-user.md, when: feature_user_and_group } - { name: GRANT, href: grant.md, when: feature_user_and_group } -- cgit v1.3