> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Вспомогательный дочерний процесс, который принимает на себя удар Linux OOM killer раньше сервера ClickHouse, давая серверу возможность снизить нагрузку и продолжить работу.

# OOM-канарейка

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Экспериментальная возможность. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">Подробнее.</a></u>
        </div>;
};

<ExperimentalBadge />

<Note>
  OOM-канарейка является экспериментальной и по умолчанию отключена. Её поведение может меняться
  между версиями ClickHouse до завершения валидации в продакшне.
</Note>

<div id="overview">
  ## Обзор
</div>

Когда у хоста или cgroup памяти заканчивается память, OOM-killer в Linux
завершает процесс с помощью `SIGKILL` — обычно самого крупного потребителя,
которым на выделенном хосте является сам `clickhouse-server`. В результате
вместо шанса на восстановление сервер целиком выходит из строя.

OOM-канарейка меняет то, кто погибает первым. Она запускает небольшой
*жертвенный* дочерний процесс, который делает себя наиболее привлекательной
целью для OOM, чтобы ядро убило его, а не сервер. Затем сервер обнаруживает
его завершение, подтверждает, что причиной был OOM, и сбрасывает давление
на память, чтобы выжить.

Канарейка не увеличивает никакой лимит памяти и не заменяет корректно настроенные
ограничения (см. [Оверкоммит памяти](/docs/ru/concepts/features/configuration/settings/memory-overcommit) и
`max_server_memory_usage`). Это последний рубеж защиты: за небольшой,
фиксированный объём памяти она даёт шанс пережить резкий всплеск потребления памяти.

<div id="how-it-works">
  ## Как это работает
</div>

Канарейка — это отдельный процесс `clickhouse oom-canary`. Он устанавливает для себя
`oom_score_adj` на максимум (`1000`), чтобы ядро выбрало его первой целью, затем
выделяет `oom_canary_size` байт (по умолчанию 100 МБ), обращается к этой памяти и вызывает `mlock`,
чтобы его резидентный объём памяти был реальным. Этот процесс автоматически завершается, если сервер останавливается.

На сервере поток мониторинга следит за канарейкой (через `pidfd`) и реагирует, когда
она завершается:

* Завершена сигналом `SIGKILL` **при наличии** признаков OOM в cgroup → выполнить реакцию на OOM, затем
  заново запустить новую канарейку.
* Завершена **без** признаков OOM (например, при ручном `kill -9`) или завершилась
  из-за временного сбоя → только перезапуск, без реакции.
* Постоянная ошибка инициализации или остановка сервера → канарейка отключается сама.

Признаки OOM берутся только из счётчика `oom_kill` в `memory.events.local` cgroup v2.
Это намеренно ограничено текущей cgroup: иерархические или общесистемные счётчики могут
увеличиваться из-за несвязанных процессов и вызывать ложные срабатывания.

При подтверждённом OOM реакция выполняет следующие независимые шаги: записывает сообщение `FATAL`
в журнал, очищает арены аллокатора (jemalloc), по возможности отменяет все выполняющиеся
запросы, отменяет все слияния и мутации и ставит событие в очередь
[`system.crash_log`](/docs/ru/reference/system-tables/crash_log). Системные журналы не
сбрасываются на диск синхронно, потому что принудительный I/O при нехватке памяти может только ухудшить ситуацию.

<div id="requirements">
  ## Требования
</div>

* **Linux ≥ 5.3.** Монитор управляет канарейкой через `pidfd_open`; на более старых ядрах
  канарейка отключается при запуске. На платформах, отличных от Linux, это не даёт никакого эффекта.
* **cgroup v2 с `memory.events.local`** для реакции на OOM. Без этого
  канарейка всё равно перезапускается после `SIGKILL`, но не может подтвердить OOM, поэтому
  реакция не запускается (при запуске в журнал записывается предупреждение).
* **Привилегия `mlock` (необязательно).** Чтобы заблокировать память канарейки,
  требуется `CAP_IPC_LOCK` или достаточный `RLIMIT_MEMLOCK`; если это не удаётся, канарейка записывает
  предупреждение, а её память может быть выгружена в swap, что снижает её эффективность как цели OOM.

<Warning>
  **memory.oom.group**

  Если для cgroup сервера в cgroup v2 включён `memory.oom.group`, ядро
  при OOM завершает всю cgroup как единое целое — сервер завершается вместе с
  канарейкой, и реакция не запускается. В этом
  режиме канарейка не может защитить сервер; при запуске в журнал записывается предупреждение.
</Warning>

<div id="configuration">
  ## Конфигурация
</div>

Работа канарейки управляется [настройками сервера](/docs/ru/reference/settings/server-settings/settings),
которые задаются как элементы верхнего уровня конфигурации сервера и применяются после перезапуска.

| Setting                              | Default              | Description                                                                                                                                                                                                                       |
| ------------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `oom_canary_enable`                  | `false`              | Включить OOM-канарейку.                                                                                                                                                                                                           |
| `oom_canary_size`                    | `104857600` (100 MB) | Количество байтов, которое канарейка выделяет и использует. Чем больше значение, тем более вероятной целью при OOM она становится.                                                                                                |
| `oom_canary_relaunch`                | `true`               | Перезапускать канарейку после её завершения (если это не постоянный сбой инициализации и не штатная остановка) с учётом указанных ниже ограничений.                                                                               |
| `oom_canary_max_rapid_relaunches`    | `10`                 | Максимальное число последовательных *быстрых* перезапусков до отключения автоперезапуска, чтобы избежать постоянных циклов перезапуска. Счётчик сбрасывается, если канарейка проработает дольше `oom_canary_max_backoff_seconds`. |
| `oom_canary_initial_backoff_seconds` | `1`                  | Начальная задержка между перезапусками; каждый раз удваивается до максимального значения.                                                                                                                                         |
| `oom_canary_max_backoff_seconds`     | `60`                 | Максимальная задержка между перезапусками.                                                                                                                                                                                        |

```xml theme={null}
<clickhouse>
    <oom_canary_enable>1</oom_canary_enable>
    <oom_canary_size>104857600</oom_canary_size>
</clickhouse>
```

<div id="observability">
  ## Обсервабилити
</div>

Подтверждённый OOM создаёт строку в
[`system.crash_log`](/docs/ru/reference/system-tables/crash_log) с `signal = 9` и
`signal_description`, где упоминается `OOM Canary`:

```sql theme={null}
SELECT event_time, signal, signal_description
FROM system.crash_log
WHERE signal = 9 AND signal_description LIKE '%OOM Canary%'
ORDER BY event_time DESC;
```

Жизненный цикл канарейки и каждый этап реакции на OOM также записываются в журнал сервера.