Improvements of SQS documentations (#44820)

Co-authored-by: sintjuri <[email protected]>

9 files changed, 100 insertions, 34 deletions

diff --git a/ydb/docs/ru/core/concepts/datamodel/topic.md b/ydb/docs/ru/core/concepts/datamodel/topic.md
index cb853b4ad55..79c561ab464 100644
--- a/ydb/docs/ru/core/concepts/datamodel/topic.md
+++ b/ydb/docs/ru/core/concepts/datamodel/topic.md
@@ -174,7 +174,7 @@
 
 Разделяемый (общий) читатель в {{ ydb-short-name }} — это модель чтения из топика, когда за читателем закрепляется одно или несколько сообщений из топика, а не партиция топика целиком. Это позволяет одну партицию обрабатывать одновременно большим количеством потребителей.
 
-Типичный пример использования — обмен сообщениями между микросервисами. Читать из топика с использованием разделяемого (общего) читателя можно по протоколу [SQS](../../reference/sqs-api/index.md).
+Типичный пример использования — обмен сообщениями между микросервисами. Читать из топика с использованием разделяемого (общего) читателя можно по протоколу [Amazon SQS](../../reference/sqs-api/index.md).
 
 Сообщение за потребителем закрепляется на некоторое время. Если за это время потребитель не сообщил об окончании обработки сообщения и не продлил его время обработки, то это значит, что потребитель не смог обработать сообщение, и сообщение становится доступным для чтения и будет вычитано еще раз. Время обработки настраивается в параметрах читателя, но может быть задано и для каждого запроса на чтение сообщений.
 
@@ -190,15 +190,7 @@
 
 При помещении сообщения в очередь можно указать задержку перед тем, как сообщение будет отдано на обработку в первый раз. Порядок сообщений определяется временем добавления сообщения в топик — если чтение осуществляется с сохранением порядка сообщений, то отложенное сообщение приостановит выдачу на обработку всех последующих сообщений с таким же message-group-id.
 
-### Особенность реализации {#shared-consumer-implementation}
-
-Для каждой пары «разделяемый (общий) читатель — партиция топика» сервер поддерживает собственное состояние обработки сообщений. Состояние состоит из непрерывного блока сообщений из партиции топика — инфлайта. Первым сообщением инфлайта является сообщение, которое ещё не обработано, находится в обработке или ждёт перемещения в DLQ. Если первое сообщение успешно обработано, то начало блока перемещается на следующее сообщение. Сообщения для обработки отдаются только из сообщений, находящихся в инфлайте.
-
-В инфлайте одной партиции может находиться до 48000 сообщений. Это означает, что если из одной партиции читает большое количество потребителей (больше 48000), то сообщения для обработки будут получать не более 48000 потребителей, даже если в партиции сообщений больше. Увеличение количества партиций в топике увеличивает общий размер инфлайта — общий инфлайт топика равен количеству партиций, умноженному на 48000 сообщений. Если необходимо обрабатывать большое количество сообщений одновременно, то следует увеличить количество партиций топика.
-
-Если топик состоит из нескольких партиций, то запросы на чтение равномерно распределяются по всем партициям. Может случиться ситуация, что запрос попадёт в партицию, в которой отсутствуют сообщения. В этом случае потребитель получит ответ, что сообщений для обработки нет. Если в партиции долгое время нет сообщений для обработки, то она исключается из распределения запросов на чтение. Партиция вернётся в распределение сразу, как только в ней появятся сообщения для обработки.
-
-Для разделяемых (общих) читателей с сохранением порядка сообщений это означает, что если в партицию будет записано подряд большое количество сообщений из одной message-group-id (больше 48000 сообщений), то весь инфлайт займут сообщения из одной message-group-id, и сообщения из других групп выдаваться не будут, пока в инфлайте не появятся сообщения из других групп.
+См. также [{#T}](../../dev/shared-consumer-internals.md).
 
 ### Позиция чтения {#consumer-offset}
 
@@ -237,7 +229,9 @@
 
 Для работы с топиками используется {{ ydb-short-name }} SDK (см. [Работа с топиками](../../reference/ydb-sdk/topic.md)).
 
-Также ограниченно поддержан протокол Kafka API версии 3.4.0. (см. [Работа с Kafka API](../../reference/kafka-api/index.md)).
+Также ограниченно поддержаны протоколы Kafka API версии 3.4.0 (см. [{#T}](../../reference/kafka-api/index.md)) и Amazon SQS API (см. [{#T}](../../reference/sqs-api/index.md)).
+
+С одним топиком работа может вестись одновременно по нескольким протоколам. Например, запись может осуществляться с использованием Topic API, а чтение — с использованием Amazon SQS API, и наоборот.
 
 ## Транзакции с участием топиков {#topic-transactions}
 
diff --git a/ydb/docs/ru/core/dev/shared-consumer-internals.md b/ydb/docs/ru/core/dev/shared-consumer-internals.md
new file mode 100644
index 00000000000..d8c43261874
--- /dev/null
+++ b/ydb/docs/ru/core/dev/shared-consumer-internals.md
@@ -0,0 +1,49 @@
+# Разделяемый читатель топика: устройство и ограничения
+
+[Разделяемый (общий) читатель](../concepts/datamodel/topic.md#shared-consumer) — модель чтения из [топика](../concepts/datamodel/topic.md), при которой за потребителем закрепляется одно или несколько сообщений, а не целая партиция. Это позволяет нескольким потребителям параллельно обрабатывать сообщения из одной партиции и использовать топики в роли очередей сообщений. Типичный сценарий — обмен сообщениями между микросервисами; чтение по [Amazon SQS API](../reference/sqs-api/index.md) работает через разделяемый читатель.
+
+Общее описание модели, настройки читателя, политики DLQ и порядка сообщений см. в разделе [Разделяемый (общий) читатель](../concepts/datamodel/topic.md#shared-consumer). В этой статье описано внутреннее устройство механизма: как сервер отслеживает состояние обработки, распределяет запросы на чтение по партициям, какие ограничения следует учитывать при проектировании высоконагруженных очередей и какое потребление ресурсов создаёт инфлайт.
+
+## Особенность реализации {#shared-consumer-implementation}
+
+Для каждой пары «разделяемый (общий) читатель — партиция топика» сервер поддерживает собственное состояние обработки сообщений. Состояние состоит из непрерывного блока сообщений из партиции топика — инфлайта. Первым сообщением инфлайта является сообщение, которое ещё не обработано, находится в обработке или ждёт перемещения в DLQ. Если первое сообщение успешно обработано, то начало блока перемещается на следующее сообщение. Сообщения для обработки отдаются только из сообщений, находящихся в инфлайте.
+
+В инфлайте одной партиции может находиться до 120000 сообщений. Это означает, что если из одной партиции читает большое количество потребителей (больше 120000), то сообщения для обработки будут получать не более 120000 потребителей, даже если в партиции сообщений больше. Увеличение количества партиций в топике увеличивает общий размер инфлайта — общий инфлайт топика равен количеству партиций, умноженному на 120000 сообщений. Если необходимо обрабатывать большое количество сообщений одновременно, то следует увеличить количество партиций топика.
+
+Если топик состоит из нескольких партиций, то запросы на чтение равномерно распределяются по всем партициям. Может случиться ситуация, что запрос попадёт в партицию, в которой отсутствуют сообщения. В этом случае потребитель получит ответ, что сообщений для обработки нет. Если в партиции долгое время нет сообщений для обработки, то она исключается из распределения запросов на чтение. Партиция вернётся в распределение сразу, как только в ней появятся сообщения для обработки.
+
+Для разделяемых (общих) читателей с сохранением порядка сообщений это означает, что если в партицию будет записано подряд большое количество сообщений из одной message-group-id (больше 120000 сообщений), то весь инфлайт займут сообщения из одной message-group-id, и сообщения из других групп выдаваться не будут, пока в инфлайте не появятся сообщения из других групп.
+
+## Честные очереди {#fair-queues}
+
+При выдаче сообщений на чтение сервер учитывает `message-group-id` сообщений, находящихся в инфлайте. Стараясь отдавать сообщения из разных групп, сервер распределяет нагрузку между писателями более равномерно.
+
+Это позволяет сглаживать пики от отдельных писателей: если один писатель отправляет в очередь гораздо больше сообщений, чем остальные, обработка сообщений от «малых» писателей получает приоритет и не блокируется потоком от одного источника.
+
+Для [FIFO-очередей](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html) и разделяемых читателей с сохранением порядка сообщений при этом гарантируется порядок сообщений внутри одного `message-group-id`: потребитель всегда получает сообщения группы в том порядке, в котором они были записаны.
+
+## Потребление ресурсов {#resource-usage}
+
+Состояние инфлайта потребляет ресурсы оперативной памяти и диска. На каждое сообщение в инфлайте сервер хранит служебную информацию объёмом около 32 байт — это не тело сообщения, а метаданные о его статусе обработки.
+
+### Оперативная память
+
+Весь инфлайт хранится в памяти сервера. Для оценки потребления памяти удобно считать от миллиона сообщений: **1 млн сообщений в инфлайте ≈ 32 МБ** оперативной памяти.
+
+Например, топик с 10 партициями и одним разделяемым читателем при полностью заполненном инфлайте (120000 сообщений на партицию) удерживает до 1,2 млн сообщений в инфлайте — около **38 МБ** памяти только на служебное состояние. На одну пару «разделяемый (общий) читатель — партиция» при максимальном инфлайте приходится около **3,8 МБ**. Если на топике несколько разделяемых читателей, потребление памяти умножается на их количество.
+
+При проектировании учитывайте:
+
+- чем больше партиций и читателей, тем выше потолок потребления памяти;
+- чем дольше сообщения находятся в обработке (большое время обработки сообщения, медленные потребители), тем дольше они остаются в инфлайте и занимают память;
+- увеличение числа партиций расширяет параллелизм, но одновременно увеличивает суммарный объём инфлайта.
+
+### Диск
+
+На диске также сохраняется информация о статусе сообщений — от **32 байта на сообщение**. Хранение состоит из двух частей:
+
+1. **Снапшот** — периодически записывается полное состояние всех сообщений в инфлайте.
+2. **Журнал изменений** — сервер обрабатывает ожидающие запросы на чтение пачками и при обработке каждой пачки дописывает в журнал изменения статусов сообщений.
+
+Следовательно, высокая частота чтения и большой инфлайт увеличивают объём дисковых записей. При планировании ёмкости кластера закладывайте ресурсы диска наряду с оперативной памятью — особенно для топиков с большим числом партиций, несколькими разделяемыми читателями и длительным временем обработки сообщений.
+
diff --git a/ydb/docs/ru/core/dev/toc_p.yaml b/ydb/docs/ru/core/dev/toc_p.yaml
index f8acddd8076..fb0a264c747 100644
--- a/ydb/docs/ru/core/dev/toc_p.yaml
+++ b/ydb/docs/ru/core/dev/toc_p.yaml
@@ -53,6 +53,8 @@ items:
   href: system-views.md
 - name: Change Data Capture
   href: cdc.md
+- name: Устройство и ограничения разделяемого читателя топика
+  href: shared-consumer-internals.md
 - name: Terraform
   href: terraform.md
 - name: Пользовательские атрибуты
diff --git a/ydb/docs/ru/core/reference/sqs-api/_includes/examples_prerequisites.md b/ydb/docs/ru/core/reference/sqs-api/_includes/examples_prerequisites.md
index 767affa9268..1ea61883e0d 100644
--- a/ydb/docs/ru/core/reference/sqs-api/_includes/examples_prerequisites.md
+++ b/ydb/docs/ru/core/reference/sqs-api/_includes/examples_prerequisites.md
@@ -1,3 +1,3 @@
-Перед выполнением примеров настройте доступ к SQS API (в Open Source-версии — отключите требование аутентификации, см. раздел про [аутентификацию](../auth.md)).
+Перед выполнением примеров настройте доступ к Amazon SQS API (в Open Source-версии — отключите требование аутентификации, см. раздел про [аутентификацию](../auth.md)).
 
 Если вы используете AWS CLI, убедитесь, что он не требует настроенных AWS‑креденшалов: либо добавьте `--no-sign-request` к командам, либо задайте любые значения `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`.
diff --git a/ydb/docs/ru/core/reference/sqs-api/_includes/limitations.md b/ydb/docs/ru/core/reference/sqs-api/_includes/limitations.md
index 0275e1f348c..5253f73c15b 100644
--- a/ydb/docs/ru/core/reference/sqs-api/_includes/limitations.md
+++ b/ydb/docs/ru/core/reference/sqs-api/_includes/limitations.md
@@ -1,5 +1,5 @@
 {% note info %}
 
-Работа с топиками по SQS-протоколу поддерживается только для [Amazon JSON protocol](https://docs.amazonaws.cn/en_us/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-json-faqs.html).
+Работа с топиками по Amazon SQS-протоколу поддерживается только для [Amazon JSON protocol](https://docs.amazonaws.cn/en_us/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-json-faqs.html).
 
 {% endnote %}
diff --git a/ydb/docs/ru/core/reference/sqs-api/auth.md b/ydb/docs/ru/core/reference/sqs-api/auth.md
index 6811a4519be..7c5bfa21001 100644
--- a/ydb/docs/ru/core/reference/sqs-api/auth.md
+++ b/ydb/docs/ru/core/reference/sqs-api/auth.md
@@ -1,6 +1,6 @@
 # Аутентификация
 
-В Open Source-версии {{ ydb-short-name }} работа с топиками по SQS-протоколу поддерживается только без аутентификации.
+В Open Source-версии {{ ydb-short-name }} работа с топиками по Amazon SQS-протоколу поддерживается только без аутентификации.
 
 ## Настройка кластера
 
diff --git a/ydb/docs/ru/core/reference/sqs-api/examples.md b/ydb/docs/ru/core/reference/sqs-api/examples.md
index cf66decc191..aafa6732cfe 100644
--- a/ydb/docs/ru/core/reference/sqs-api/examples.md
+++ b/ydb/docs/ru/core/reference/sqs-api/examples.md
@@ -1,7 +1,7 @@
-# Примеры работы с топиком через SQS API
+# Примеры работы с топиком через Amazon SQS API
 <!-- markdownlint-disable blanks-around-fences -->
 
-В этой статье приведены примеры работы с [топиками](../../concepts/datamodel/topic.md) с использованием SQS API с помощью [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
+В этой статье приведены примеры работы с [топиками](../../concepts/datamodel/topic.md) с использованием Amazon SQS API с помощью [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
 
 {% include [x](_includes/limitations.md) %}
 
@@ -9,7 +9,7 @@
 
 ## Формирование endpoint для подключения
 
-Endpoint для доступа к SQS API формируется следующим образом:
+Endpoint для доступа к Amazon SQS API формируется следующим образом:
 
 `https://{db-balancer}:{port}/{database}`
 
@@ -25,7 +25,7 @@ Endpoint для доступа к SQS API формируется следующ�
 
 В примерах используется endpoint `https://my_db.balancer.example.com:8443/Root/my_db`. В нём:
 
-- `my_db.balancer.example.com` — DNS-имя балансировщика, по которому доступен SQS-протокол;
+- `my_db.balancer.example.com` — DNS-имя балансировщика, по которому доступен Amazon SQS-протокол;
 - `8443` — сетевой порт;
 - `/Root/my_db` — имя базы данных.
 
@@ -63,7 +63,7 @@ aws --endpoint "$ENDPOINT" \
 
 ## Получение списка топиков
 
-Для получения списка топиков, с которыми возможна работа по SQS протоколу, выполните команду:
+Для получения списка топиков, с которыми возможна работа по протоколу Amazon SQS, выполните команду:
 
 ```shell
 ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"
@@ -71,6 +71,26 @@ ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"
 aws --endpoint "$ENDPOINT" sqs list-queues
 ```
 
+### Получение QueueUrl топика
+
+Чтобы получить `QueueUrl` топика, выполните команду:
+
+```shell
+ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"
+
+aws --endpoint "$ENDPOINT" sqs get-queue-url \
+  --queue-name "my_topic@my_consumer"
+```
+
+Где:
+
+- `{queue_name}` — значение параметра `--queue-name`, имя Amazon SQS-очереди в формате `{topic_name}@{consumer_name}`. Если [разделяемый (общий) читатель](../../concepts/datamodel/topic.md#shared-consumer) имеет имя `ydb-sqs-consumer`, достаточно указать только `{topic_name}`;
+- `{topic_name}` — имя топика с путём от корня базы данных, в которой он создан, например `production/order` (топик `order` в директории `production`);
+- `{consumer_name}` — имя [разделяемого (общего) читателя](../../concepts/datamodel/topic.md#shared-consumer) на топике, например `ydb-sqs-consumer`.
+
+В примере выше `my_topic` — это `{topic_name}`, а `my_consumer` — `{consumer_name}`.
+
+
 ## Запись в топик и чтение из топика
 
 Для операций чтения и записи AWS CLI использует параметр `--queue-url`. Его можно получить через `get-queue-url`.
diff --git a/ydb/docs/ru/core/reference/sqs-api/index.md b/ydb/docs/ru/core/reference/sqs-api/index.md
index 3a72a5771ca..2aef717cedc 100644
--- a/ydb/docs/ru/core/reference/sqs-api/index.md
+++ b/ydb/docs/ru/core/reference/sqs-api/index.md
@@ -1,20 +1,20 @@
-# SQS API
+# Amazon SQS API
 
-{{ ydb-short-name }} поддерживает работу с [топиками](../../concepts/datamodel/topic.md) по протоколу [SQS](https://en.wikipedia.org/wiki/Amazon_Simple_Queue_Service).
+{{ ydb-short-name }} поддерживает работу с [топиками](../../concepts/datamodel/topic.md) по протоколу [Amazon SQS](https://en.wikipedia.org/wiki/Amazon_Simple_Queue_Service).
 
 {% include [x](_includes/limitations.md) %}
 
-С одним топиком работа может вестись одновременно по нескольким протоколам. Например, запись может осуществляться с использованием Topic API, а чтение — с использованием SQS API, и наоборот.
+С одним топиком работа может вестись одновременно по нескольким протоколам. Например, запись может осуществляться с использованием Topic API, а чтение — с использованием Amazon SQS API, и наоборот.
 
-При создании топика командой `CreateQueue` SQS API топик создаётся с включённым [автопартиционированием](../../concepts/datamodel/topic.md#autopartitioning_modes): с одной партицией и автоматической возможностью увеличения до 10 активных партиций. Параметры автопартиционирования можно изменить через [YQL](../../yql/reference/syntax/alter-topic.md) или [YDB CLI](../ydb-cli/topic-alter.md).
+При создании топика командой `CreateQueue` Amazon SQS API топик создаётся с включённым [автопартиционированием](../../concepts/datamodel/topic.md#autopartitioning_modes): с одной партицией и автоматической возможностью увеличения до 10 активных партиций. Параметры автопартиционирования можно изменить через [YQL](../../yql/reference/syntax/alter-topic.md) или [YDB CLI](../ydb-cli/topic-alter.md).
 
-## Чтение по SQS API
+## Чтение по Amazon SQS API
 
-Для чтения по SQS API используется [разделяемый (общий) читатель](../../concepts/datamodel/topic.md#shared-consumer), который должен быть создан на топике до начала чтения по SQS-протоколу. Если топик создаётся командой `CreateQueue` SQS API, автоматически создаётся разделяемый (общий) читатель с именем `ydb-sqs-consumer`.
+Для чтения по Amazon SQS API используется [разделяемый (общий) читатель](../../concepts/datamodel/topic.md#shared-consumer), который должен быть создан на топике до начала чтения по Amazon SQS-протоколу. Если топик создаётся командой `CreateQueue` Amazon SQS API, автоматически создаётся разделяемый (общий) читатель с именем `ydb-sqs-consumer`.
 
-Сообщения, записанные через Topic API, могут быть сжаты алгоритмами [gzip](https://en.wikipedia.org/wiki/Gzip), [lzop](https://en.wikipedia.org/wiki/Lzop) или [zstd](https://en.wikipedia.org/wiki/Zstd). При чтении по SQS-протоколу сервер не разжимает их, а передаёт в виде base64: читатель должен выполнить base64-декодирование, а затем разжатие.
+Сообщения, записанные через Topic API, могут быть сжаты алгоритмами [gzip](https://en.wikipedia.org/wiki/Gzip), [lzop](https://en.wikipedia.org/wiki/Lzop) или [zstd](https://en.wikipedia.org/wiki/Zstd). При чтении по Amazon SQS-протоколу сервер не разжимает их, а передаёт в виде base64: читатель должен выполнить base64-декодирование, а затем разжатие.
 
-Сообщения, записанные через Topic API без сжатия, могут содержать бинарные данные. При чтении по SQS-протоколу сервер также кодирует их в base64 — читатель должен выполнить base64-декодирование.
+Сообщения, записанные через Topic API без сжатия, могут содержать бинарные данные. При чтении по Amazon SQS-протоколу сервер также кодирует их в base64 — читатель должен выполнить base64-декодирование.
 
 Чтобы читатель мог определить алгоритм сжатия, вместе с каждым сообщением отдаётся атрибут `BodyEncoding`. Если атрибут `BodyEncoding` отсутствует, разжимать сообщение не требуется. Возможные значения атрибута: `gzip`, `lzop`, `zstd` или `base64`.
 
@@ -37,11 +37,11 @@
 }
 ```
 
-## Запись по SQS API
+## Запись по Amazon SQS API
 
-При записи в топик по SQS-протоколу сообщения равномерно распределяются по партициям. При этом гарантируется, что все сообщения с одинаковым `MessageGroupId` попадут в одну партицию.
+При записи в топик по Amazon SQS-протоколу сообщения равномерно распределяются по партициям. При этом гарантируется, что все сообщения с одинаковым `MessageGroupId` попадут в одну партицию.
 
-Для записи по SQS-протоколу поддержана дедубликация сообщений по `DeduplicationMessageId`, а если `DeduplicationMessageId` не передан — по содержимому сообщения. Включить дедубликацию по содержимому можно командами `CreateQueue` и `SetQueueAttributes`, указав параметр `ContentBasedDeduplication`.
+Для записи по Amazon SQS-протоколу поддержана дедубликация сообщений по `DeduplicationMessageId`, а если `DeduplicationMessageId` не передан — по содержимому сообщения. Включить дедубликацию по содержимому можно командами `CreateQueue` и `SetQueueAttributes`, указав параметр `ContentBasedDeduplication`.
 
 Дедубликация по содержимому реализована на окне в 5 минут: сообщение с повторяющимся `DeduplicationMessageId` может быть повторно записано через 5 минут или более.
 
@@ -49,6 +49,7 @@
 
 ## Разделы документации
 
-- [Аутентификация](auth.md)
-- [Примеры](examples.md)
-- [Создание очереди с помощью YQL](../../yql/reference/syntax/alter-topic.md#add-consumer)
\ No newline at end of file
+- [{#T}](auth.md)
+- [{#T}](examples.md)
+- [Создание очереди с помощью YQL](../../yql/reference/syntax/alter-topic.md#add-consumer)
+- [{#T}](../../dev/shared-consumer-internals.md)
diff --git a/ydb/docs/ru/core/reference/toc_p.yaml b/ydb/docs/ru/core/reference/toc_p.yaml
index 7a936ad38ec..23d0a48d1d8 100644
--- a/ydb/docs/ru/core/reference/toc_p.yaml
+++ b/ydb/docs/ru/core/reference/toc_p.yaml
@@ -37,7 +37,7 @@ items:
   include:
     mode: link
     path: kafka-api/toc_p.yaml
-- name: SQS API
+- name: Amazon SQS API
   href: sqs-api/index.md
   include:
     mode: link