> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> توثيق أداة أخذ العينات لتنميط الاستعلامات في ClickHouse

# أداة أخذ العينات لتنميط الاستعلامات

يشغّل ClickHouse أداة تنميط تعتمد على أخذ العينات تتيح تحليل تنفيذ الاستعلامات.
وباستخدام أداة التنميط، يمكنك العثور على إجراءات الشيفرة المصدرية الأكثر استخدامًا أثناء تنفيذ الاستعلام.
يمكنك تتبّع وقت CPU والوقت الفعلي المنقضي، بما في ذلك وقت الخمول.

يتم تمكين أداة تنميط الاستعلامات تلقائيًا في ClickHouse Cloud.
يعثر مثال الاستعلام التالي على تتبعات المكدس الأكثر تكرارًا لاستعلام خضع للتنميط، مع أسماء الدوال بعد حلّ الرموز ومواضعها في الشيفرة المصدرية:

<Tip>
  استبدل قيمة `query_id` بمعرّف الاستعلام الذي تريد تنميطه.
</Tip>

<Tabs>
  <Tab title="ClickHouse Cloud">
    في ClickHouse Cloud، يمكنك الحصول على معرّف الاستعلام بالنقر على **"..."** في أقصى يمين الشريط أعلى جدول نتائج الاستعلام (بجوار مفتاح التبديل table/chart). سيؤدي ذلك إلى فتح قائمة سياق يمكنك من خلالها النقر على **"Copy query ID"**.

    استخدم `clusterAllReplicas(default, system.trace_log)` للاختيار من جميع عُقد الـ cluster:

    ```sql theme={null}
    SELECT
        count(),
        arrayStringConcat(arrayMap(x -> concat(demangle(addressToSymbol(x)), '\n    ', addressToLine(x)), trace), '\n') AS sym
    FROM clusterAllReplicas(default, system.trace_log)
    WHERE query_id = '<query_id>' AND trace_type = 'CPU' AND event_date = today()
    GROUP BY trace
    ORDER BY count() DESC
    LIMIT 10
    SETTINGS allow_introspection_functions = 1
    ```
  </Tab>

  <Tab title="Self-managed">
    ```sql theme={null}
    SELECT
        count(),
        arrayStringConcat(arrayMap(x -> concat(demangle(addressToSymbol(x)), '\n    ', addressToLine(x)), trace), '\n') AS sym
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'CPU' AND event_date = today()
    GROUP BY trace
    ORDER BY count() DESC
    LIMIT 10
    SETTINGS allow_introspection_functions = 1
    ```
  </Tab>
</Tabs>

<div id="self-managed-query-profiler">
  ## استخدام أداة تنميط الاستعلامات في عمليات النشر المُدارة ذاتيًا
</div>

في عمليات النشر المُدارة ذاتيًا، لاستخدام أداة تنميط الاستعلامات اتبع الخطوات التالية:

<Steps>
  <Step>
    ### ثبّت ClickHouse مع معلومات تصحيح الأخطاء

    ثبّت الحزمة `clickhouse-common-static-dbg`:

    1. اتبع التعليمات في الخطوة ["إعداد مستودع Debian"](/ar/get-started/setup/self-managed/debian-ubuntu#setup-the-debian-repository)
    2. شغّل `sudo apt-get install clickhouse-server clickhouse-client clickhouse-common-static-dbg` لتثبيت الملفات الثنائية المترجمة لـ ClickHouse مع معلومات تصحيح الأخطاء
    3. شغّل `sudo service clickhouse-server start` لبدء تشغيل الخادم
    4. شغّل `clickhouse-client`. سيلتقط الخادم تلقائيًا رموز تصحيح الأخطاء من `clickhouse-common-static-dbg` — ولا تحتاج إلى القيام بأي إجراء خاص لتمكينها
  </Step>

  <Step>
    ### تحقّق من إعدادات الخادم

    تأكد من إعداد قسم [`trace_log`](/ar/reference/settings/server-settings/settings#trace_log) في [ملف إعدادات الخادم](/ar/concepts/features/configuration/server-config/configuration-files). وهو مُمكَّن افتراضيًا:

    ```xml theme={null}
    <!-- سجل التتبّع. يخزّن تتبعات المكدس التي تجمعها أدوات تحليل الاستعلامات.
         راجع الإعدادين query_profiler_real_time_period_ns و query_profiler_cpu_time_period_ns. -->
    <trace_log>
        <database>system</database>
        <table>trace_log</table>

        <partition_by>toYYYYMM(event_date)</partition_by>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <!-- يحدد ما إذا كان ينبغي تفريغ السجلات إلى القرص عند حدوث crash -->
        <flush_on_crash>false</flush_on_crash>
        <symbolize>true</symbolize>
    </trace_log>
    ```

    يضبط هذا القسم الجدول النظامي [trace\_log](/ar/reference/system-tables/trace_log) الذي يحتوي على نتائج عمل أداة التحليل.
    تذكّر أن البيانات في هذا الجدول تكون صالحة فقط أثناء تشغيل الخادم.
    بعد إعادة تشغيل الخادم، لا ينظّف ClickHouse هذا الجدول، وقد تصبح جميع عناوين الذاكرة الافتراضية المخزنة غير صالحة.
  </Step>

  <Step>
    ### اضبط مؤقتات التحليل

    أعِد الإعدادين [`query_profiler_cpu_time_period_ns`](/ar/reference/settings/session-settings#query_profiler_cpu_time_period_ns) أو [`query_profiler_real_time_period_ns`](/ar/reference/settings/session-settings#query_profiler_real_time_period_ns).
    يمكن استخدام كلا الإعدادين في الوقت نفسه.

    تتيح لك هذه الإعدادات ضبط مؤقتات أداة التحليل.
    وبما أنها إعدادات جلسة، يمكنك استخدام تردد sampling مختلف للخادم بالكامل، أو للمستخدمين الأفراد أو ملفات تعريف المستخدمين، أو لجلسة العمل التفاعلية الخاصة بك، أو لكل query على حدة.

    تردد sampling الافتراضي هو عينة واحدة في الثانية، كما أن مؤقتَي CPU والوقت الفعلي مُمكَّنان.
    ويتيح لك هذا التردد جمع معلومات كافية عن ClickHouse cluster لديك من دون التأثير في أداء الخادم.
    إذا كنت بحاجة إلى تحليل كل query على حدة، فاستخدم تردد sampling أعلى.
  </Step>

  <Step>
    ### حلّل الجدول النظامي `trace_log`

    لتحليل الجدول النظامي `trace_log`، اسمح باستخدام دوال الاستبطان عبر الإعداد [`allow_introspection_functions`](/ar/reference/settings/session-settings#allow_introspection_functions):

    ```sql theme={null}
    SET allow_introspection_functions=1
    ```

    <Note>
      لدواعٍ أمنية، تكون دوال الاستبطان معطّلة افتراضيًا
    </Note>

    استخدم [دوال الاستبطان](/ar/reference/functions/regular-functions/introspection) `addressToLine` و`addressToLineWithInlines` و`addressToSymbol` و`demangle` للحصول على أسماء الدوال ومواضعها في شيفرة ClickHouse.
    وللحصول على profile لاستعلام معيّن، تحتاج إلى تجميع البيانات من الجدول `trace_log`.
    ويمكنك تجميع البيانات بحسب الدوال الفردية أو بحسب تتبعات المكدس كاملة.

    <Tip>
      إذا كنت بحاجة إلى تصوّر معلومات `trace_log`، فجرّب [flamegraph](/ar/integrations/connectors/tools/gui#clickhouse-flamegraph) و[speedscope](https://www.speedscope.app).
    </Tip>
  </Step>
</Steps>

<div id="flamegraph">
  ## إنشاء مخططات اللهب باستخدام الدالة `flameGraph`
</div>

يوفّر ClickHouse الدالة التجميعية [`flameGraph`](/ar/reference/functions/aggregate-functions/flame_graph) التي تُنشئ مخطط اللهب مباشرةً من تتبعات المكدس المخزّنة في `trace_log`.
ويكون الناتج مصفوفة من السلاسل النصية بتنسيق متوافق مع [flamegraph.pl](https://github.com/brendangregg/FlameGraph).

**البنية:**

```sql theme={null}
flameGraph(traces, [size = 1], [ptr = 0])
```

**الوسائط:**

* `traces` — تتبّع مكدس الاستدعاءات. [`Array(UInt64)`](/ar/reference/data-types/array).
* `size` — حجم التخصيص لتنميط الذاكرة. [`Int64`](/ar/reference/data-types/int-uint).
* `ptr` — عنوان التخصيص. [`UInt64`](/ar/reference/data-types/int-uint).

عندما تكون قيمة `ptr` غير صفرية، فإن `flameGraph` يطابق بين التخصيصات (`size > 0`) وعمليات إلغاء التخصيص (`size < 0`) التي لها الحجم والمؤشر نفسيهما.
ولا تُعرض إلا التخصيصات التي لم تُحرَّر.
وتُتجاهل عمليات إلغاء التخصيص غير المطابقة.

<div id="cpu-flame-graph">
  ### مخطط اللهب للـ CPU
</div>

<Note>
  تتطلب الاستعلامات أدناه أن يكون [flamegraph.pl](https://github.com/brendangregg/FlameGraph) مثبّتًا على جهازك.

  يمكنك القيام بذلك بتشغيل:

  ```bash theme={null}
  git clone https://github.com/brendangregg/FlameGraph
  # ثم استخدمه على النحو التالي:
  # ~/FlameGraph/flamegraph.pl
  ```

  استبدل `flamegraph.pl` في الاستعلامات التالية بالمسار الذي يوجد فيه `flamegraph.pl` على جهازك.
</Note>

```sql theme={null}
SET query_profiler_cpu_time_period_ns = 10000000;
```

نفّذ الاستعلام، ثم أنشئ مخطط اللهب:

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(arrayReverse(trace)))
        FROM system.trace_log
        WHERE trace_type = 'CPU' AND query_id = '<query_id>'" \
    | flamegraph.pl > flame_cpu.svg
```

<div id="memory-flame-graph-all">
  ### مخطط اللهب للذاكرة — جميع عمليات تخصيص الذاكرة
</div>

```sql theme={null}
SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;
```

شغّل استعلامك، ثم أنشئ مخطط اللهب:

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size))
        FROM system.trace_log
        WHERE trace_type = 'MemorySample' AND query_id = '<query_id>'" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem.svg
```

<div id="memory-flame-graph-unfreed">
  ### مخطط اللهب للذاكرة — التخصيصات غير المُحرَّرة
</div>

يطابق هذا النمط عمليات التخصيص مع عمليات تحرير الذاكرة بحسب المؤشر، ويعرض فقط الذاكرة التي لم تُحرَّر أثناء الاستعلام.

```sql theme={null}
SET memory_profiler_sample_probability = 1, max_untracked_memory = 1,
    use_uncompressed_cache = 1,
    merge_tree_max_rows_to_use_cache = 100000000000,
    merge_tree_max_bytes_to_use_cache = 1000000000000;
```

نفّذ الاستعلام التالي لإنشاء مخطط اللهب:

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size, ptr))
        FROM system.trace_log
        WHERE trace_type = 'MemorySample' AND query_id = '<query_id>'" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_unfreed.svg
```

<div id="memory-flame-graph-time-point">
  ### مخطط اللهب للذاكرة — التخصيصات النشطة في لحظة زمنية معيّنة
</div>

يتيح لك هذا الأسلوب تحديد ذروة استخدام الذاكرة وتصور ما كان مخصصًا في تلك اللحظة.

```sql theme={null}
SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;
```

<div id="find-memory-usage-over-time">
  #### تتبّع استخدام الذاكرة بمرور الوقت
</div>

```sql theme={null}
SELECT
    event_time,
    formatReadableSize(max(s)) AS m
FROM (
    SELECT
        event_time,
        sum(size) OVER (ORDER BY event_time) AS s
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'MemorySample'
)
GROUP BY event_time
ORDER BY event_time;
```

<div id="find-time-point-maximum-memory-usage">
  #### حدِّد النقطة الزمنية ذات أعلى استخدام للذاكرة
</div>

```sql theme={null}
SELECT
    argMax(event_time, s),
    max(s)
FROM (
    SELECT
        event_time,
        sum(size) OVER (ORDER BY event_time) AS s
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'MemorySample'
);
```

<div id="build-flame-graph">
  #### أنشئ مخطط اللهب لتخصيصات الذاكرة النشطة عند تلك اللحظة الزمنية
</div>

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size, ptr))
        FROM (
            SELECT * FROM system.trace_log
            WHERE trace_type = 'MemorySample'
              AND query_id = '<query_id>'
              AND event_time <= '<time_point>'
            ORDER BY event_time
        )" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_time_point_pos.svg
```

<div id="build-flame-graph-deallocations">
  #### أنشئ مخطط مخطط اللهب لعمليات تحرير الذاكرة بعد تلك النقطة الزمنية (لفهم ما الذي حُرِّر لاحقًا)
</div>

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, -size, ptr))
        FROM (
            SELECT * FROM system.trace_log
            WHERE trace_type = 'MemorySample'
              AND query_id = '<query_id>'
              AND event_time > '<time_point>'
            ORDER BY event_time DESC
        )" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_time_point_neg.svg
```

<div id="example">
  ## مثال
</div>

مقتطف الشيفرة أدناه:

* يطبّق عامل تصفية على بيانات `trace_log` حسب معرّف الاستعلام والتاريخ الحالي.
* يجمّع حسب تتبّع المكدس.
* يستخدم دوال الاستبطان للحصول على تقرير يتضمن:
  * أسماء الرموز والدوال المقابلة لها في الشيفرة المصدرية.
  * مواضع هذه الدوال في الشيفرة المصدرية.

```sql theme={null}
SELECT
    count(),
    arrayStringConcat(arrayMap(x -> concat(demangle(addressToSymbol(x)), '\n    ', addressToLine(x)), trace), '\n') AS sym
FROM system.trace_log
WHERE (query_id = '<query_id>') AND (event_date = today())
GROUP BY trace
ORDER BY count() DESC
LIMIT 10
```