Руководство по администрированию

В руководстве администратора описаны сценарии эксплуатации и администрирования Tarantool Queue Enterprise, функциональность MQ (далее по тексту – TQE(MQ)).

• Введение
• Сценарии использования

TQE(MQ) состоит из двух компонентов:

• модуль API – предоставляет интерфейс для взаимодействия с очередью посредством gRPC-протокола;
• ядро – выполняет функцию хранилища и представляет собой кластерное приложение на Tarantool.

Сценарии использования в данном руководстве разделены согласно компонентам TQE(MQ).

Сценарии охватывают следующие роли пользователей TQE(MQ):

• инженер по эксплуатации;
• администратор.

Инженер по эксплуатации выполняет следующие сценарии:

• Проверка статусов компонентов TQE(MQ)
• Получение метрик компонентов TQE (MQ)

Администратор выполняет следующие сценарии:

• Установка компонентов TQE(MQ)
• Конфигурация компонентов TQE(MQ)
• Резервное копирование

Проверка статуса ядра выполняется с помощью команды:

 
$ curl localhost:8081/health

В случае штатного режима работы ядра возвращаемый ответ:

 
app is OK

Проверка статуса модуля API выполняется с помощью команды:

 
$ curl localhost:18184/readyz

В случае штатного режима работы модуля API возвращаемый ответ:

 
{    "consumer-tarantool": "OK",    "producer-tarantool": "OK",    "started": "OK"}

Где:

• started обязательное значение. Указывает на статус работы модуля API. Принимает значения "OK" или текст ошибки.
• consumer-tarantool необязательное значение. Указывает на статус подключения сервиса подписки на сообщения к ядру TQE(MQ). Принимает значения "OK" или текст ошибки.
• producer-tarantool необязательное значение. Указывает на статус подключения сервиса публикации сообщений к ядру TQE(MQ). Принимает значения "OK" или текст ошибки.

Встроенный инструментарий TQE(MQ) предоставляет метрики для оценки процесса работы с сообщениями в очередях.

Эти метрики предоставляют диагностическую информацию для использования в стороннем программном обеспечении.

Метрики ядра TQE(MQ) соответствуют стандартному набору метрик tarantool. С перечнем метрик можно ознакомиться здесь

В дополнение реализованы метрики, специфичные для TQE(MQ):

• mqee_tnt_duplicates_total – счетчик дубликатов

Метрики ядра TQE(MQ) доступны по адресу (endpoint):

 
$ curl localhost:8081/metrics

Ожидаемый ответ содержит перечень метрик, отражающих текущее состояние очереди сообщений TQE(MQ). Пример частичного вывода метрик ядра:

 
# HELP tnt_vinyl_disk_index_size Amount of index stored in files# TYPE tnt_vinyl_disk_index_size gaugetnt_vinyl_disk_index_size{alias="app"} 0# HELP tnt_read_only Is instance read only# TYPE tnt_read_only gaugetnt_read_only{alias="app"} 0# HELP tnt_vinyl_disk_data_size Amount of data stored in files# TYPE tnt_vinyl_disk_data_size gaugetnt_vinyl_disk_data_size{alias="app"} 0...

Полный список метрик компонента ядра приведен в документе Справочники.

Метрики модуля API доступны по адресу (endpoint):

 
$ curl localhost:18184/metrics

Ожидаемый ответ содержит перечень метрик, отражающих текущее состояние модуля API. Пример частичного вывода метрик модуля API:

 
# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.# TYPE go_gc_duration_seconds summarygo_gc_duration_seconds{quantile="0"} 5.3002e-05go_gc_duration_seconds{quantile="0.25"} 7.574e-05go_gc_duration_seconds{quantile="0.5"} 9.047e-05go_gc_duration_seconds{quantile="0.75"} 0.000111856go_gc_duration_seconds{quantile="1"} 0.000338263go_gc_duration_seconds_sum 1.305067544go_gc_duration_seconds_count 11608...

Полный список метрик компонента модуля API приведен в документе Справочники.

Установка компонентов TQE(MQ) выполняется с помощью инсталлятора Ansible Tarantool Enterprise (ATE). Подготовка ATE к работе и процедуры установки компонентов TQE(MQ) описаны в документации ATE.

Конфигурация компонентов TQE(MQ) включает в себя раздельные настройки для ядра и для модуля API. Настройки описываются в формате YAML.

Конфигурацию выполняют сначала для ядра, а затем для модуля API.

Конфигурация ядра состоит из нескольких секций, описываемых далее.

Конфигурация ядра происходит стандартными средствами Tarantool 3: с помощью обновления файла конфигурации или конфигурации в etcd/Tarantool Config Storage. Подробнее про конфигурацию в Tarantool 3 можно прочитать здесь

Основная конфигурация очереди задается на уровне ролей app.roles.api и app.roles.queue, например:

 
roles_cfg:  app.roles.queue:    queues: ["queue1", "queue2"]

YAML-файл конфигурации модуля API имеет несколько секций. Полный перечень настроек представлен в следующем примере:

 
app_name: MESSAGE_QUEUE_EE_APIapp_version: testcore_host: 0.0.0.0core_port: 18184grpc_host: 0.0.0.0grpc_port: 18182producer:  enabled: true  tarantool:    user: user    pass: pass    queues:      queue:        connections:          routers:            - "localhost:3301"consumer:  enabled: true  polling_timeout: 500ms  tarantool:    user: user    pass: pass    queues:      queue:        connections:          storage-1:            - "localhost:3301"log:  file: log.jsonl  format: json  level: info

Для резервного копирования данных TQE(MQ) необходимо выполнить процедуру бэкапа ядра (кластерного приложения) c помощью инсталлятора Ansible Tarantool Enterprise.

Так как объем памяти, доступный для хранения сообщений, ограничен местом на диске, может возникнуть потребность удаления ненужных сообщений. Для периодической очистки очереди сообщений TQE(MQ) использует модуль expirationd. Соблюдение условий для удаления сообщений контролируется функцией удержания сообщений (data retention).

Функция удержания сообщений работает в соответствии с установленной политикой (policy) очистки ненужных сообщений. Политика может быть включена (policy: cleanup) или отключена (policy: disabled). Во включенном состоянии политика удаляет сообщения в зависимости от установленных параметров:

• time - допустимое время жизни сообщения в очереди в секундах. Значение 0 или отсутствие параметра отключает проверку, сообщения могут жить в очереди "бесконечно" долго.
• length - допустимая длина очереди. Значение 0 или отсутствие параметра отключает проверку, очередь становится "бесконечно" длинной.
• consumers_required - включает очистку по прочитанным сообщениям. При включенной очистке политика сравнивает указанное значение с количеством персистентных подписчиков:
  • Если количество персистентных подписчиков превышает или совпадает со значением сonsumers_required, то сообщение будет удалено только после того, как его прочтут все персистентные подписчики.
  • Если количество персистентных подписчиков ниже значения сonsumers_required, то сообщение не будет удалено очисткой по прочитанным сообщениям.
  • При consumers_required: 0 и каком-то количестве персистентных подписчиков очистка будет ждать, пока все персистентные подписчики прочтут сообщение.
  • При consumers_required: 0 и без персистентных подписчиков очистка считает все сообщения прочитанными и удаляет их сразу.

Политика очистки ненужных сообщений и смежные параметры настраиваются в секции retention в роли app.roles.queue. Секцию retention можно настраивать как на глобальном уровне, так и на уровне отдельной очереди. При наличии разницы в параметрах, приоритетной считается настройка отдельной очереди. Подробнее о настройках секции retention смотрите в документации по expirationd.

По умолчанию конфигурация для всех очередей выглядит так:

 
roles_cfg:  app.roles.queue:    retention:      time: 3153600000 # Допустимое время жизни сообщений всех очередей в секундах.      length: 0 # Проверка на максимальную длину очереди не выполняется      policy: cleanup # Политика очистки включена.      options: # Конфигурационные параметры для expirationd.start.        iteration_delay: 0 # Максимальное время в секундах для fiber.sleep между итерациями.

Переопределить конфигурацию для определенной очереди можно указав секцию retention с отличными значениями параметров в секции конфигурации конкретной очереди example_queue:

 
roles_cfg:  app.roles.queue:    queues:      - name: example_queue        retention:          time: 100 # Допустимое время жизни сообщений конкретной очереди в секундах.          length: 1000 # Максимальная длина очереди указана.          policy: cleanup # Политика очистки включена.          consumers_required: 2 # Количество постоянных подписчиков, после прочтения которыми сообщение может быть удалено.          options:            tuples_per_iteration: 512

Следующий пример конфигурации позволяет:

• Hастроить глобальное время удержания сообщений по всем очередям в 120 секунд и указать максимальную длину очереди в 1024 сообщения;
• Для очереди input:
  • Переопределить время удержания в 60 секунд;
  • Увеличить максимальную длину очереди до 2048 сообщений;
• Для вызова expirationd.start:
  • Указать опцию full_scan_time;
• Для очереди output:
  • Отключить очистку очереди от устаревших сообщений.

В подобной конфигурации секция роли app.roles.queue будет выглядеть так:

 
roles_cfg:  app.roles.queue:    retention:      time: 120      length: 1024    queues:      - name: input        retention:          time: 60          length: 2048          options:            full_scan_time: 1024      - name: output        retention:          policy: disabled # Политика очистки отключена.

Получение сообщений в TQE(MQ) возможно только при наличии подписки.

Для получения подписки, выполните запрос SubscriptionRequest без указания consume_id.

Также вы можете получить персистентную подписку. Система хранит состояние персистентной подписки и данные о прочитанных сообщениях, что позволяет возобновлять чтение сообщений с последней сохраненной позиции при переподключении.

Для получения персистентной подписки, выполните запрос SubscriptionRequest с указанием параметра consume_id.

С каждым сообщением персистентным подписчикам приходит значение параметра cursor, соответствующее позиции сообщения в очереди. Значение cursor критически важно при восстановлении состояния подписки после отключения.

Восстановить состояние подписки можно при переподключении. Для этого после отключения нужно выполнить запрос SubscriptionRequest с теми же значениями параметров queue, routing_key, sharding_key, consume_id, которые были использованы при инициализации подписки. В запрос обязательно нужно включить параметр cursor, который был использован непосредственно перед отключением.

При совпадении параметров в запросе с данными системы, подписка восстанавливается и сообщения отправляются с последней сохраненной позиции. Если же любой параметр не соотвтетствует данным из хранилища, то система вернет в ответе ошибку.

При разрыве соединения можно повторно инициировать подписку, передав свой consume_id. Сервер автоматически восстановит состояние подписки из хранилища и возобновит чтение с последней известной позиции.

После перезапуска сервер теряет состояние в памяти. Вы должны переподключиться и отправить запрос SubscriptionRequest , включающий consume_id и cursor последнего полученного сообщения. Сервер автоматически восстановит состояние из персистентного хранилища и возобновит передачу сообщений.

При перезапуске реплики gRPC-сервер автоматически обнаруживает сбой, выбирает другую доступную реплику и возобновляет обработку запросов с последней известной позиции.

После переключения на новую мастер-реплику gRPC-сервер автоматически устанавливает соединение и проверяет состояние подписок. Для персистентных подписок их состояние полностью восстанавливается на новой реплике.