# Kafka

Подключение к брокеру Kafka, параметры обработчиков очередей (Kafka-обработчиков) и продюсера, топики и мониторинг шины. Через Kafka **Webim** выполняет фоновые задачи: обработку сообщений, распределение диалогов, вебхуки каналов, статистику и другие. Сроки актуальности отдельных задач описаны на странице [Тайм-ауты, кэш и фоновые задачи](https://webim.ru/kb/11.0/settings/env/timeouts.html#kafka-tasks), число Kafka-обработчиков, их группы и топики — на странице [Параметры процессов](https://webim.ru/kb/11.0/settings/processes.html#kafka).

Как изменить параметры и применить изменения, описано в разделе [Параметры .env](https://webim.ru/kb/11.0/settings/env/). Все параметры на этой странице необязательные.

## Подключение { #connection }

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `KAFKA_BOOTSTRAP_SERVERS` | Список через запятую | `localhost:9093` | Адреса брокеров Kafka в формате `<хост>:<порт>`, например `kafka1.example.local:9092,kafka2.example.local:9092`. Значение по умолчанию подходит только для среды разработки; в рабочей установке задайте адреса Ваших брокеров. |
| `KAFKA_SECURITY_PROTOCOL` | Выбор из списка | Пусто | Протокол подключения к брокерам: `SASL_PLAINTEXT`, `SASL_SSL` или `SSL`. Пустое значение — подключение без аутентификации и шифрования; параметры `KAFKA_SASL_*` и `KAFKA_SSL_CA_LOCATION` в этом случае не используются. |
| `KAFKA_SASL_MECHANISM` | Выбор из списка | Пусто | Механизм аутентификации SASL: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`, `GSSAPI` или `OAUTHBEARER`. |
| `KAFKA_SASL_USERNAME` | Строка | Пусто | Имя пользователя SASL. |
| `KAFKA_SASL_PASSWORD` | Строка | Пусто | Пароль пользователя SASL. |
| `KAFKA_SSL_CA_LOCATION` | Путь к файлу | Пусто | Путь к сертификату удостоверяющего центра (PEM) для проверки сертификатов брокеров при протоколах `SSL` и `SASL_SSL`. |
| `KAFKA_EAGER_MODE` | Логический | Значение `DEBUG` | Только для разработки: задачи выполняются сразу в вызывающем процессе, без отправки в Kafka. В рабочей установке значение должно быть `False`. |

## Обработчики очередей { #consumers }

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `KAFKA_AUTO_OFFSET_RESET` | Выбор из списка | `earliest` | С какого места обработчик читает топик, если для его группы нет сохранённой позиции: `earliest` — с самого старого сообщения, `latest` — только новые сообщения. |
| `KAFKA_CONSUMER_SESSION_TIMEOUT_MS` | Целое число, миллисекунды | `30000` | Тайм-аут сессии обработчика: если брокер не получает от обработчика сигналов активности дольше этого времени, обработчик исключается из группы, а его разделы передаются другим обработчикам. |
| `KAFKA_CONSUMER_HEARTBEAT_INTERVAL_MS` | Целое число, миллисекунды | `10000` | Интервал отправки сигналов активности брокеру. Должен быть не больше трети `KAFKA_CONSUMER_SESSION_TIMEOUT_MS`. |
| `KAFKA_CONSUMER_POLL_STALL_TIMEOUT_S` | Дробное число, секунды | `600` | Если обработчик не запрашивает новые сообщения дольше этого времени (например, из-за зависшей задачи), процесс обработчика завершается и перезапускается. Должен быть больше `KAFKA_CONSUMER_NO_ASSIGNMENT_TIMEOUT_S`. |
| `KAFKA_CONSUMER_NO_ASSIGNMENT_TIMEOUT_S` | Дробное число, секунды | `300` | Если обработчику дольше этого времени не назначено ни одного раздела, он пытается заново подключиться к группе, а если это не помогает — перезапускается. |
| `KAFKA_CONSUMER_REJOIN_GRACE_S` | Дробное число, секунды | `30` | Время на повторное подключение к группе, после которого процесс обработчика перезапускается. |
| `KAFKA_CONSUMER_WATCHDOG_INTERVAL_S` | Дробное число, секунды | `30` | Интервал проверок работоспособности обработчика. |
| `KAFKA_CONSUMER_POLL_TIMEOUT_SECONDS` | Дробное число, секунды | `1.0` | Максимальное время ожидания новых сообщений в одном запросе к брокеру. |
| `KAFKA_CONSUMER_RETRY_DELAYS_SECONDS` | Список чисел через запятую, секунды | `0.1,0.3,0.5` | Задержки между попытками обработать сообщение после ошибки. Число значений — число попыток; последнее значение не используется: после последней неудачной попытки сообщение отправляется в топик недоставленных сообщений (DLQ).<br>Список не может быть пустым, иначе **Webim** не запускается. Сумма задержек должна быть намного меньше `KAFKA_CONSUMER_SESSION_TIMEOUT_MS`. |
| `KAFKA_RETRY_BUDGET_ENABLED` | Логический | `True` | Ограничение доли повторных попыток обработки. При массовом сбое повторные попытки не умножают нагрузку: когда бюджет исчерпан, сообщения сразу отправляются в DLQ. |
| `KAFKA_RETRY_BUDGET_TOKEN_RATIO` | Дробное число | `0.2` | Пополнение бюджета повторных попыток: каждое обработанное сообщение добавляет указанное число единиц, каждая повторная попытка расходует одну. Значение `0.2` допускает повторные попытки примерно для 20 % сообщений. |
| `KAFKA_RETRY_BUDGET_MAX_TOKENS` | Дробное число | `100.0` | Максимальный размер бюджета повторных попыток. |
| `KAFKA_WORKER_OPEN_FILES_LIMIT` | Целое число | `65536` | Мягкий лимит числа открытых файлов, который обработчик устанавливает себе при запуске. |
| `KAFKA_TASK_STATS_DISABLED` | Строка | Не задано | Значение `1` отключает сбор статистики времени выполнения задач в обработчиках: запись сводок в журнал и отправку метрик в Prometheus Pushgateway. |

## Продюсер { #producer }

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `KAFKA_SHUTDOWN_FLUSH_TIMEOUT` | Дробное число, секунды | `25.0` | Сколько процесс при остановке ждёт доставки накопленных сообщений в брокер. Должно быть меньше времени, которое supervisor или Kubernetes даёт процессу на завершение. |
| `KAFKA_SHUTDOWN_FLUSH_TIMEOUT_ATEXIT` | Дробное число, секунды | `8.0` | То же для процессов без штатной процедуры остановки: планировщика периодических задач и служебных команд. |
| `KAFKA_PRODUCER_WATCHDOG_ENABLED` | Логический | `True` | Автоматическое пересоздание клиента Kafka, который перестал доставлять сообщения. |
| `KAFKA_PRODUCER_STALL_TIMEOUT_MINUTES` | Целое число, минуты | `5` | Через сколько времени после первой неудачной доставки, если с тех пор не было ни одной успешной, клиент считается зависшим и пересоздаётся. |
| `KAFKA_PRODUCER_WATCHDOG_INTERVAL_SECONDS` | Целое число, секунды | `30` | Интервал проверки работоспособности клиента. |

## Топики { #topics }

Топики создаются при установке и обновлении **Webim**.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `KAFKA_TOPIC_PREFIX` | Строка | Пусто | Префикс имён топиков по умолчанию. Позволяет нескольким установкам использовать один кластер Kafka. Префикс нужно добавить и к именам топиков в параметрах запуска Kafka-обработчиков (см. [Параметры процессов](https://webim.ru/kb/11.0/settings/processes.html#kafka-options)). |
| `KAFKA_TOPIC_PARTITIONS_MAX` | Целое число | `0` | Максимальное число разделов топика. Числа разделов по умолчанию рассчитаны на десятки обработчиков (до 96 у `general-tasks`); на небольших установках значение можно ограничить, например `8`. `0` — без ограничения. |
| `KAFKA_TOPIC_RETENTION_DEFAULT_DAYS` | Целое число, дни | `7` | Срок хранения сообщений в большинстве топиков. |
| `KAFKA_TOPIC_RETENTION_SHORT_DAYS` | Целое число, дни | `1` | Срок хранения сообщений в служебных топиках с короткоживущими задачами. |
| `KAFKA_TOPIC_RETENTION_DLQ_DAYS` | Целое число, дни | `30` | Срок хранения сообщений в топиках недоставленных сообщений (DLQ). |
| `KAFKA_TOPIC_RETENTION_AUTO_ASSIGN_HOURS` | Целое число, часы | `6` | Срок хранения сообщений в топике автоматического назначения диалогов. |

!!! Note "N.B."

    Параметры `KAFKA_TOPIC_RETENTION_*` действуют только при создании топика: у существующих топиков срок хранения не меняется. Чтобы изменить срок хранения в существующем топике, измените его параметр `retention.ms` средствами Kafka, например командой `kafka-configs --alter`.

    Число разделов проверяется и у существующих топиков: если разделов меньше, чем предусмотрено в **Webim** с учётом `KAFKA_TOPIC_PARTITIONS_MAX`, при установке и обновлении **Webim** их число увеличивается. Уменьшить число разделов существующего топика нельзя.

## Имена топиков { #topic-names }

Имена по умолчанию начинаются с префикса `KAFKA_TOPIC_PREFIX`.

!!! Warning "Имена топиков"

    Меняйте имена топиков только при первоначальной установке и только вместе с параметрами запуска Kafka-обработчиков (`--topics` и `--dlq-topic`, см. [Параметры процессов](https://webim.ru/kb/11.0/settings/processes.html#kafka-options)) в конфигурации supervisor или в манифестах Kubernetes: обработчики подписываются на топики по точным именам. Задачи, оставшиеся в топиках со старыми именами, не будут обработаны.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `KAFKA_GENERAL_TASKS_TOPIC` | Строка | `general-tasks` | Общие фоновые задачи. |
| `KAFKA_GENERAL_TASKS_DLQ_TOPIC` | Строка | `general-tasks-dlq` | Недоставленные сообщения общих фоновых задач. |
| `KAFKA_DEFAULT_DLQ_TOPIC` | Строка | Значение `KAFKA_GENERAL_TASKS_DLQ_TOPIC` | Топик недоставленных сообщений для обработчиков, в параметрах запуска которых не указан `--dlq-topic`. |
| `KAFKA_INTERACTION_SIGNALS_TOPIC` | Строка | `interaction-signals` | Сигналы о событиях в диалогах. |
| `KAFKA_INTERACTION_SIGNALS_DLQ_TOPIC` | Строка | `interaction-signals-dlq` | Недоставленные сигналы о событиях в диалогах. |
| `KAFKA_INTERACTION_ROUTING_TOPIC` | Строка | `interaction-routing` | Распределение диалогов. |
| `KAFKA_AUTO_ASSIGN_COMMIT_TOPIC` | Строка | `auto-assign-commit` | Подтверждение автоматического назначения диалогов. |
| `KAFKA_TIMEOUT_DISPATCH_TOPIC` | Строка | `timeout-dispatch` | Обработка тайм-аутов диалогов. |
| `KAFKA_WATCHDOG_DISPATCH_TOPIC` | Строка | `watchdog-dispatch` | Срабатывание отложенных задач. |
| `KAFKA_VISITOR_MESSAGES_TOPIC` | Строка | `visitor-messages` | Обработка сообщений посетителей. |
| `KAFKA_VISITOR_MESSAGES_DLQ_TOPIC` | Строка | `visitor-messages-dlq` | Недоставленные сообщения посетителей. |
| `KAFKA_VISIT_SESSION_STREAM_UPDATES_TOPIC` | Строка | `visit-session-stream-updates` | Обновление данных посетителей в РМО. |
| `KAFKA_AGENT_STATUS_BROADCASTS_TOPIC` | Строка | `agent-status-broadcasts` | Рассылка изменений статусов сотрудников. |
| `KAFKA_MODEL_EVENTS_TOPIC` | Строка | `model-events` | События изменения данных. |
| `KAFKA_MODEL_EVENTS_PRIORITY_TOPIC` | Строка | `model-events-priority` | Приоритетные события изменения состояния диалогов. |
| `KAFKA_MODEL_EVENTS_DLQ_TOPIC` | Строка | `model-events-dlq` | Недоставленные события изменения данных. |
| `KAFKA_CHANNEL_WEBHOOKS_TOPIC` | Строка | `channel-webhooks` | Входящие вебхуки каналов. |
| `KAFKA_CHANNEL_OUTBOUND_TOPIC` | Строка | `channel-outbound` | Отправка сообщений в каналы. |
| `KAFKA_BOT_EVENTS_TOPIC` | Строка | `bot-events` | События для ботов. |
| `KAFKA_AI_BOT_TOPIC` | Строка | `ai-bot` | Ответы ИИ-бота. |
| `KAFKA_AI_INGEST_TOPIC` | Строка | `ai-ingest` | Обработка материалов для ИИ-бота. |
| `KAFKA_UI_RESOURCES_TOPIC` | Строка | `ui-resources` | Генерация ресурсов виджета. |
| `KAFKA_STATS_TASKS_TOPIC` | Строка | `stats-tasks` | Задачи статистики. |
| `KAFKA_BI_FACTS_TOPIC` | Строка | `bi-facts` | Выгрузка данных BI-отчётов. |
| `KAFKA_BI_REALTIME_TOPIC` | Строка | `bi-realtime` | Данные BI-отчётов в реальном времени. |
| `KAFKA_ELASTIC_INDEXING_TOPIC` | Строка | `elastic-indexing` | Индексация диалогов в поисковом движке. |
| `KAFKA_ELASTIC_INDEXING_REBUILD_TOPIC` | Строка | `elastic-indexing-rebuild` | Полная переиндексация диалогов. |
| `KAFKA_KB_INDEXING_TOPIC` | Строка | `kb-indexing` | Индексация базы знаний. |
| `KAFKA_JOBS_TOPIC` | Строка | `jobs` | Длительные задачи, например выгрузки. |
| `KAFKA_BROADCASTS_TOPIC` | Строка | `broadcasts` | Рассылки. |
| `KAFKA_SLA_TASKS_TOPIC` | Строка | `sla-tasks` | Задачи политик SLA. |
| `KAFKA_COALESCING_MAINTENANCE_TOPIC` | Строка | Значение `KAFKA_GENERAL_TASKS_TOPIC` | Служебные задачи механизма объединения повторяющихся задач. |
| `KAFKA_CANARY_TOPIC` | Строка | Значение `KAFKA_GENERAL_TASKS_TOPIC` | Топик контрольной задачи, которая проверяет работоспособность шины (см. [Мониторинг шины](#monitoring)). |

## Мониторинг шины { #monitoring }

Результаты проверок выводятся в ответе служебного адреса проверки работоспособности `/health`.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `KAFKA_CONSUMER_LAG_THRESHOLD` | Целое число | `1000` | Отставание группы обработчиков (число необработанных сообщений), при превышении которого проверка работоспособности сообщает о проблеме. |
| `KAFKA_CANARY_ENABLED` | Логический | `True` | Проверка контрольной задачи: планировщик периодически отправляет контрольную задачу, обработчик выполняет её и сохраняет отметку времени. Выключайте, только если планировщик периодических задач не запущен. |
| `KAFKA_CANARY_INTERVAL_SECONDS` | Целое число, секунды | `60` | Интервал отправки контрольной задачи. |
| `KAFKA_CANARY_LAG_THRESHOLD_MINUTES` | Целое число, минуты | `5` | Если контрольная задача не выполнялась дольше этого времени, проверка работоспособности сообщает о проблеме. |
| `KAFKA_CANARY_TTL_HOURS` | Целое число, часы | `24` | Срок хранения отметки о выполнении контрольной задачи. |
| `KAFKA_WORKER_HEARTBEAT_INTERVAL_SECONDS` | Целое число, секунды | `15` | Интервал, с которым обработчики записывают отметку активности своей группы. |
| `KAFKA_WORKER_HEARTBEAT_LAG_THRESHOLD_MINUTES` | Целое число, минуты | `2` | Если отметка активности группы старше этого времени, проверка работоспособности сообщает о проблеме. |
| `KAFKA_WORKER_HEARTBEAT_TTL_HOURS` | Целое число, часы | `6` | Срок хранения отметки активности группы. |
| `KAFKA_DELIVERY_ERROR_THRESHOLD` | Целое число | `0` | Допустимое число ошибок доставки сообщений в брокер за окно `KAFKA_DELIVERY_ERROR_WINDOW_MINUTES`. `0` — проверка работоспособности сообщает о проблеме при любой ошибке доставки. |
| `KAFKA_DELIVERY_ERROR_WINDOW_MINUTES` | Целое число, минуты | `5` | Окно подсчёта ошибок доставки. |
| `KAFKA_DELIVERY_ERROR_BUCKET_MINUTES` | Целое число, минуты | `1` | Шаг подсчёта ошибок доставки внутри окна. |
| `KAFKA_DELIVERY_ERROR_FLUSH_INTERVAL_SECONDS` | Целое число, секунды | `5` | Как часто процесс сохраняет накопленное число ошибок доставки в Redis. |
| `KAFKA_DELIVERY_ERROR_LOG_INTERVAL_SECONDS` | Целое число, секунды | `30` | При серии ошибок доставки первая ошибка сразу записывается в журнал, а дальше — сводка не чаще указанного интервала. |
| `KAFKA_CLIENT_ERROR_LOG_INTERVAL_SECONDS` | Целое число, секунды | `60` | То же для ошибок клиента Kafka, например при недоступности брокера. |
| `KAFKA_EMPTY_GROUP_GRACE_MINUTES` | Целое число, минуты | `3` | Если в обязательной группе обработчиков нет ни одного активного обработчика дольше этого времени, проверка работоспособности сообщает о проблеме. Задержка исключает ложные срабатывания при перезапуске обработчиков. Обязательные группы — группы обработчиков из комплекта поставки (см. [Параметры процессов](https://webim.ru/kb/11.0/settings/processes.html#kafka-groups)). |
| `KAFKA_EMPTY_GROUP_STATE_TTL_HOURS` | Целое число, часы | `6` | Срок хранения сведений о группах без активных обработчиков. |
| `KAFKA_HEALTH_LIST_TOPICS_TIMEOUT_SECONDS` | Дробное число, секунды | `5.0` | Тайм-аут запроса списка топиков при проверке работоспособности. |
| `KAFKA_HEALTH_ADMIN_RESULT_TIMEOUT_SECONDS` | Дробное число, секунды | `10.0` | Тайм-аут административных запросов к Kafka при проверке работоспособности. |
| `KAFKA_ADMIN_LIST_TIMEOUT_SECONDS` | Целое число, секунды | `10` | Тайм-аут запроса списка топиков при создании топиков. |

---

Источник: https://webim.ru/kb/11.0/settings/env/kafka.html
