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

# كيفية جمع وتصوّر تتبّع الاستعلام

> يوضح هذا الدليل كيفية جمع بيانات تتبّع الاستعلام وتصوّرها باستخدام ClickHouse مُدار ذاتيًا، إما بالاعتماد على الطرق المضمّنة أو باستخدام Grafana. ويكون ذلك مفيدًا بشكل خاص عند العمل على استعلامات معقّدة والحاجة إلى فهم آليات التنفيذ الداخلية بما يتجاوز ما يوفّره EXPLAIN.

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

**المتطلبات المسبقة**:

* الإلمام بـ [ملفات تهيئة ClickHouse](/docs/ar/concepts/features/configuration/server-config/configuration-files)
* مثيل من [خادم ClickHouse](/docs/ar/get-started/setup/install) قيد التشغيل
* (اختياري) مثيل محلي من [Grafana](https://grafana.com/docs/grafana/latest/fundamentals/getting-started/) قيد التشغيل

<Steps>
  <Step title={<>تحقق من تفعيل جدول النظام <code>opentelemetry_span_log</code></>} id="enable-system-table">
    إذا لم تُجرِ أي تعديلات على قسم `opentelemetry_span_log` في ملف `config.xml`، يمكنك تخطي هذه الخطوة.

    افتح ملف `config.xml` الافتراضي لـ ClickHouse وابحث عن القسم التالي:

    ```yaml theme={null}
    <!--
        OpenTelemetry log contains OpenTelemetry trace spans.

        NOTE: this table does not use standard schema with event_date and event_time!
    -->
    <opentelemetry_span_log>
        <!--
            The default table creation code is insufficient, this <engine> spec
            is a workaround. There is no 'event_time' for this log, but two times,
            start and finish. It is sorted by finish time, to avoid inserting
            data too far away in the past (probably we can sometimes insert a span
            that is seconds earlier than the last span in the table, due to a race
            between several spans inserted in parallel). This gives the spans a
            global order that we can use to e.g. retry insertion into some external
            system.
        -->
        <engine>
            engine MergeTree
            partition by toYYYYMM(finish_date)
            order by (finish_date, finish_time_us, trace_id)
        </engine>
        <database>system</database>
        <table>opentelemetry_span_log</table>
        <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>
        <flush_on_crash>false</flush_on_crash>
    </opentelemetry_span_log>
    ```

    تأكد من أنه ليس معطَّلًا بالتعليق، وإلا فلن تتمكن من رؤية `system.opentelemetry_span_log` في الخطوات التالية.
    وقد يحدث ذلك أيضًا إذا كان خادم ClickHouse لديك لا يستخدم ملف الإعدادات الافتراضي.

    تحقق في سجلات الخادم لديك عن شيء مثل:

    ```text theme={null}
    Processing configuration file 'config.xml'.
    There is no file 'config.xml', will use embedded config.
    ```

    <Tip>
      في التثبيتات القياسية، يقع هذا الملف في `/etc/clickhouse-server/config.xml`
    </Tip>
  </Step>

  <Step title="تفعيل تتبّع OpenTelemetry" id="enable-otel-tracing">
    بعد تشغيل ClickHouse server، افتح ClickHouse client وفعّل جمع التتبعات باستخدام الاستعلام التالي:

    ```bash theme={null}
    SET opentelemetry_trace_processors=1;
    ```

    من المفترض أن يظهر لك الآن جدول النظام `opentelemetry_span_log` إذا شغّلت:

    ```sql theme={null}
    SHOW TABLES IN system
    ```

    بعد ذلك، نفِّذ:

    ```
    SET opentelemetry_start_trace_probability=1;
    ```

    يحدّد هذا احتمال أن يبدأ ClickHouse trace للاستعلامات التي يجري تنفيذها، حيث إن
    `1` تعني أن trace مفعّل لجميع الاستعلامات المنفذة.
  </Step>

  <Step title="الحصول على معرّف الاستعلام" id="obtain-query-id">
    نفّذ الاستعلام التجريبي التالي، أو الاستعلام الذي ترغب في تتبّعه:

    ```sql theme={null}
    SELECT pow(number, 2) FROM numbers(10E4);
    ```

    انسخ مُعرّف الاستعلام:

    ```sql highlight={6} theme={null}
    :) SELECT pow(number, 2) FROM numbers(10E4);

    SELECT pow(number, 2)
    FROM numbers(100000.)

    Query id: a9241258-a0c4-4776-a00b-e6a1d9bec4a1
    ```
  </Step>

  <Step title="أنشئ ملف تتبع" id="generate-trace-file">
    نفّذ الاستعلام التالي، مع استبدال معرّف الاستعلام بالمعرّف الذي حصلت عليه في الخطوة السابقة:

    ```sql theme={null}
    WITH 'a9241258-a0c4-4776-a00b-e6a1d9bec4a1' AS my_query_id
    SELECT
        concat(substring(hostName(), length(hostName()), 1), leftPad(greatest(attribute['clickhouse.thread_id'], attribute['thread_number']), 5, '0')) AS group,
        operation_name,
        start_time_us,
        finish_time_us,
        sipHash64(operation_name) AS color,
        attribute
    FROM system.opentelemetry_span_log
    WHERE (trace_id IN (
        SELECT trace_id
        FROM system.opentelemetry_span_log
        WHERE (attribute['clickhouse.query_id']) = my_query_id
    )) AND (operation_name != 'query') AND (operation_name NOT LIKE 'Query%')
    ORDER BY
        hostName() ASC,
        group ASC,
        parent_span_id ASC,
        start_time_us ASC
    INTO OUTFILE 'trace.json'
    FORMAT JSON
    SETTINGS output_format_json_named_tuples_as_objects = 1
    ```

    سيؤدي هذا إلى كتابة الـ trace في ملف باسم `trace.json`.
    وبشكل افتراضي، يُنشأ هذا الملف في دليل العمل الحالي الذي تُشغِّل منه أداة `clickhouse-client` أو `clickhouse-local`.
  </Step>

  <Step title="تصوَّر بيانات التتبّع باستخدام الأدوات المدمجة" id="visualize-trace-using-built-in-tooling">
    استخدم عارض التتبّع المستضاف على [https://trace-visualizer.clickhouse.com/](https://trace-visualizer.clickhouse.com/).
    حمّل ملف `trace.json` من الخطوة السابقة لعرض التتبّع بصريًا.

    <Image img="https://mintcdn.com/private-7c7dfe99/ufw4Fv2WNLmoOCdU/images/knowledgebase/trace-visualizer-example.png?fit=max&auto=format&n=ufw4Fv2WNLmoOCdU&q=85&s=31a5a5b04d205a7db89e4c1bf2f8e94a" size="md" alt="مثال على عارض التتبّع في ClickHouse" width="2974" height="1514" data-path="images/knowledgebase/trace-visualizer-example.png" />
  </Step>

  <Step title="استخدام Grafana لعرض التتبعات بصريًا" id="using-grafana">
    نوصي باستخدام Grafana لتصوّر بيانات التتبّع واستكشافها عبر إضافة ClickHouse الرسمية.
    وقد حُسّنت الإضافة لإتاحة تصوّر التتبّعات باستخدام Trace Panel.
    وهذا مدعوم سواءً كتصوّر أو كمكوّن في Explore.

    اتبع الخطوات الموضحة في ["استخدام Grafana وClickHouse من أجل Observability"](/docs/ar/guides/use-cases/observability/build-your-own/grafana)
    لإعداد Grafana باستخدام إضافة ClickHouse.

    من علامة التبويب Explore، يمكنك بعد ذلك تشغيل الاستعلام التالي، مع استبدال `trace_id` بالقيمة الخاصة بك:

    ```sql theme={null}
    SELECT
        toString(trace_id) AS traceID,
        toString(span_id) AS spanID,
        if(toString(parent_span_id)='0', '', toString(parent_span_id)) AS parentSpanID,
        'ClickHouse' AS serviceName,
        operation_name AS operationName,
        start_time_us/1000000 AS startTime,
        (finish_time_us - start_time_us)/1000 AS duration,
        arrayMap(key -> map('key', key, 'value', attribute[key]), mapKeys(attribute)) AS serviceTags
    FROM system.opentelemetry_span_log
    WHERE trace_id = '68a14b27-a61f-596d-3746-2b03d2530e42' ORDER BY startTime ASC
    ```

    تأكد من تعيين `Query type` إلى `Traces`:

    <Image img="https://mintcdn.com/private-7c7dfe99/ufw4Fv2WNLmoOCdU/images/knowledgebase/trace-visualization-grafana.png?fit=max&auto=format&n=ufw4Fv2WNLmoOCdU&q=85&s=c9b4062554d26a82072652fa78387ec7" size="md" alt="تصوّر التتبعات في ClickHouse في Grafana" width="3018" height="996" data-path="images/knowledgebase/trace-visualization-grafana.png" />

    انقر على "Run Query" وافحص مخطط التتبّع:

    <Image img="https://mintcdn.com/private-7c7dfe99/ufw4Fv2WNLmoOCdU/images/knowledgebase/trace-visualization-diagram.png?fit=max&auto=format&n=ufw4Fv2WNLmoOCdU&q=85&s=ca8aa94807d052d3197cdbce461ba35e" size="md" alt="تصوّر التتبعات في ClickHouse في Grafana" width="2458" height="1076" data-path="images/knowledgebase/trace-visualization-diagram.png" />
  </Step>
</Steps>