> ## 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.

> Un processus enfant sacrifié qui attire le Linux OOM killer avant le ClickHouse server, laissant ainsi au serveur le temps d'alléger sa charge et de survivre.

# OOM canary

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>
            Fonctionnalité expérimentale. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">En savoir plus.</a></u>
        </div>;
};

<ExperimentalBadge />

<Note>
  L’OOM canary est expérimental et désactivé par défaut. Son comportement peut évoluer
  d’une version de ClickHouse à l’autre jusqu’à la fin de la validation en production.
</Note>

<div id="overview">
  ## Vue d’ensemble
</div>

Lorsqu’un hôte ou un cgroup mémoire tombe à court de mémoire, le killer OOM
(out-of-memory) de Linux termine un processus avec `SIGKILL` — généralement le plus gros consommateur, qui,
sur un hôte dédié, est `clickhouse-server` lui-même. On perd alors l’ensemble du serveur
au lieu de lui laisser une chance de se rétablir.

L’OOM canary change l’ordre des victimes. Il exécute un petit processus enfant
*sacrificiel* qui se rend lui-même prioritaire pour l’OOM killer, afin que le noyau le tue
à la place du serveur. Le serveur détecte alors sa mort, confirme qu’il s’agissait d’un événement OOM,
puis réduit la pression mémoire pour pouvoir survivre.

Le canary n’augmente aucune limite mémoire et ne remplace pas des
limites correctement définies (voir [Memory overcommit](/docs/fr/concepts/features/configuration/settings/memory-overcommit) et
`max_server_memory_usage`). Il constitue une dernière ligne de défense qui échange une petite quantité
fixe de mémoire contre une chance de survivre à un pic de consommation mémoire.

<div id="how-it-works">
  ## Comment cela fonctionne
</div>

Le canary est un processus `clickhouse oom-canary` distinct. Il définit son propre
`oom_score_adj` au maximum (`1000`) pour que le noyau le cible en premier, puis
alloue, touche et applique `mlock` à `oom_canary_size` octets (100 Mo par défaut) afin que
sa mémoire résidente soit bien réelle. Il est automatiquement tué si le serveur s'arrête.

Dans le serveur, un thread de surveillance observe le canary (via `pidfd`) et réagit lorsqu'il
meurt :

* Tué par `SIGKILL` **avec** preuve d'OOM au niveau du cgroup → exécuter la réponse OOM, puis
  relancer un nouveau canary.
* Tué **sans** preuve d'OOM (par exemple, un `kill -9` manuel), ou arrêté
  après une défaillance transitoire → relance uniquement, sans réponse.
* Échec permanent de l'initialisation, ou arrêt du serveur → le canary se désactive.

La preuve d'OOM provient uniquement du compteur `oom_kill` de `memory.events.local` du cgroup v2.
Elle est volontairement locale au cgroup : des compteurs hiérarchiques ou à l'échelle de l'hôte peuvent
être incrémentés par des processus sans rapport et déclencheraient de fausses réponses.

Lorsqu'un OOM est confirmé, la réponse exécute ces étapes indépendantes : consigner un message `FATAL`,
purger les arènes de l'allocator (jemalloc), annuler dans la mesure du possible toutes les
queries en cours d'exécution, annuler tous les merges et mutations, et mettre en
file d'attente un événement dans
[`system.crash_log`](/docs/fr/reference/system-tables/crash_log). Les log système ne sont pas
vidés de manière synchrone, car forcer des E/S sous pression mémoire peut aggraver
la situation.

<div id="requirements">
  ## Exigences
</div>

* **Linux ≥ 5.3.** Le moniteur détient le canari via `pidfd_open` ; sur les noyaux plus anciens,
  le canari se désactive au démarrage. Cela est sans effet sur les plateformes non Linux.
* **`cgroup v2` avec `memory.events.local`** pour la réponse OOM. Sans cela, le
  canari se relance bien après un `SIGKILL`, mais ne peut pas confirmer un OOM ; la
  réponse n'est donc jamais exécutée (un avertissement est consigné au démarrage).
* **Capacité `mlock` (facultative).** Le verrouillage de la mémoire du canari nécessite
  `CAP_IPC_LOCK` ou une valeur `RLIMIT_MEMLOCK` suffisante ; en cas d'échec, le canari consigne un
  avertissement et sa mémoire peut être paginée sur disque, ce qui le rend moins efficace comme cible OOM.

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

  Si `memory.oom.group` de cgroup v2 est activé pour le cgroup du serveur, le noyau
  tue l'ensemble du cgroup comme une seule unité en cas d'OOM : le serveur meurt en même temps que le
  canari et la réponse n'est jamais exécutée. Le canari ne peut pas protéger le serveur dans ce
  mode ; un avertissement est consigné au démarrage.
</Warning>

<div id="configuration">
  ## Configuration
</div>

Le canary est contrôlé par les [paramètres du serveur](/docs/fr/reference/settings/server-settings/settings),
définis comme éléments de premier niveau de la configuration du serveur et appliqués au redémarrage.

| Setting                              | Default              | Description                                                                                                                                                                                                                                            |
| ------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `oom_canary_enable`                  | `false`              | Active le OOM canary.                                                                                                                                                                                                                                  |
| `oom_canary_size`                    | `104857600` (100 MB) | Nombre d’octets que le canary alloue et utilise. Des valeurs plus élevées en font une cible OOM plus probable.                                                                                                                                         |
| `oom_canary_relaunch`                | `true`               | Relance le canary après sa terminaison (sauf en cas d’échec permanent lors de l’initialisation ou d’arrêt), sous réserve des limites ci-dessous.                                                                                                       |
| `oom_canary_max_rapid_relaunches`    | `10`                 | Nombre maximal de relances *rapides* consécutives avant la désactivation de la relance automatique, afin d’éviter les redémarrages en boucle. Le compteur se réinitialise dès qu’un canary survit plus longtemps que `oom_canary_max_backoff_seconds`. |
| `oom_canary_initial_backoff_seconds` | `1`                  | Délai initial entre les relances ; il double à chaque fois jusqu’à la valeur maximale.                                                                                                                                                                 |
| `oom_canary_max_backoff_seconds`     | `60`                 | Délai maximal entre les relances.                                                                                                                                                                                                                      |

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

<div id="observability">
  ## Observabilité
</div>

Un OOM confirmé génère une ligne dans
[`system.crash_log`](/docs/fr/reference/system-tables/crash_log) avec `signal = 9` et un
`signal_description` mentionnant `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;
```

Le cycle de vie du canary et chaque étape de la réponse aux OOM sont également consignés dans le journal du serveur.