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

> عملية فرعية مُضحّى بها تستقطب قاتل نفاد الذاكرة (OOM) في Linux قبل خادم 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 canary ميزة تجريبية وهي معطّلة افتراضيًا. وقد يتغيّر سلوكها
  بين إصدارات ClickHouse إلى أن يكتمل التحقق منها في بيئات الإنتاج.
</Note>

<div id="overview">
  ## نظرة عامة
</div>

عندما تنفد الذاكرة لدى مضيف أو لدى `cgroup` للذاكرة، يُنهي قاتل نفاد الذاكرة (OOM) في Linux عملية باستخدام `SIGKILL` — وغالبًا ما تكون أكبر مستهلك للذاكرة، والتي
تكون في المضيف المخصص هي `clickhouse-server` نفسه. وبذلك يُفقد الخادوم بالكامل
بدلًا من منحه فرصة للتعافي.

يغيّر كاناري OOM الجهة التي تموت أولًا. فهو يشغّل عملية فرعية صغيرة *تضحية*
تجعل نفسها الهدف الأكثر ترجيحًا لـ OOM، بحيث تقتلها
النواة بدلًا من الخادوم. ثم يكتشف الخادوم هذا التوقف، ويتأكد من أنه كان حدث OOM،
ويخفف ضغط الذاكرة لكي يتمكن من الاستمرار.

لا يرفع الكناري أي memory limit، وليس بديلًا عن
الحدود الصحيحة (انظر [memory overcommit](/docs/ar/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)، ومحاولة إلغاء جميع
الاستعلامات الجارية بأفضل جهد ممكن، وإلغاء جميع عمليات الدمج وعمليات mutation، ووضع حدث في
[`system.crash_log`](/docs/ar/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**

  إذا كان `memory.oom.group` في `cgroup v2` مفعّلًا لـ cgroup الخاص بالخادم، فإن النواة
  تقتل cgroup بالكامل كوحدة واحدة عند حدوث OOM — فيتوقف الخادم مع
  العملية الكناري معًا، ولا تُنفَّذ الاستجابة مطلقًا. ولا تستطيع العملية الكناري حماية الخادم في هذا
  الوضع؛ ويُسجَّل تحذير عند بدء التشغيل.
</Warning>

<div id="configuration">
  ## التهيئة
</div>

تخضع عملية الكناري للتحكم عبر [إعدادات الخادم](/docs/ar/reference/settings/server-settings/settings)،
وتُحدَّد كعناصر من المستوى الأعلى في تهيئة الخادم وتُطبَّق عند إعادة التشغيل.

| الإعداد                              | الافتراضي            | الوصف                                                                                                                                                                                                         |
| ------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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/ar/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;
```

كما تُسجَّل دورة حياة الكاناري وكل خطوة من خطوات الاستجابة لحالة نفاد الذاكرة في سجل الخادم.