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

> دليل لاستخدام OpenTelemetry في التتبع الموزع وجمع المقاييس في ClickHouse

# تتبع ClickHouse باستخدام OpenTelemetry

يُعد [OpenTelemetry](https://opentelemetry.io/) معيارًا مفتوحًا لتجميع التتبعات والمقاييس من التطبيقات الموزعة. ويدعم ClickHouse ‏OpenTelemetry إلى حدٍّ ما.

<div id="supplying-trace-context-to-clickhouse">
  ## تزويد ClickHouse بسياق التتبع
</div>

يقبل ClickHouse ترويسات HTTP الخاصة بسياق التتبع، كما هو موضح في [توصية W3C](https://www.w3.org/TR/trace-context/). كما يقبل سياق التتبع عبر البروتوكول الأصلي المستخدم للتواصل بين خوادم ClickHouse أو بين العميل والخادم. ولأغراض الاختبار اليدوي، يمكن تمرير ترويسات سياق التتبع المتوافقة مع توصية Trace Context إلى `clickhouse-client` باستخدام الخيارين `--opentelemetry-traceparent` و`--opentelemetry-tracestate`.

إذا لم يتم تمرير سياق تتبع أصل، أو كان سياق التتبع الممرَّر غير متوافق مع معيار W3C المذكور أعلاه، يمكن لـ ClickHouse بدء تتبّع جديد باحتمال يتحكم فيه إعداد [opentelemetry\_start\_trace\_probability](/docs/ar/reference/settings/session-settings#opentelemetry_start_trace_probability).

<div id="propagating-the-trace-context">
  ## نشر سياق التتبع
</div>

يُنقَل سياق التتبع إلى الخدمات اللاحقة في الحالات التالية:

* الاستعلامات المُرسلة إلى خوادم ClickHouse البعيدة، مثل عند استخدام محرك الجدول [Distributed](/docs/ar/reference/engines/table-engines/special/distributed).

* دالة الجدول [url](/docs/ar/reference/functions/table-functions/url). تُرسَل معلومات سياق التتبع ضمن ترويسة HTTP.

<div id="tracing-clickhouse-keeper-requests">
  ## تتبّع طلبات ClickHouse Keeper
</div>

يدعم ClickHouse تتبّع OpenTelemetry لطلبات [ClickHouse Keeper](/docs/ar/guides/oss/deployment-and-scaling/keeper/index) (خدمة تنسيق متوافقة مع ZooKeeper). تتيح هذه الميزة رؤية تفصيلية لدورة حياة عمليات Keeper، بدءًا من إرسال الطلب من العميل وصولًا إلى معالجته على جهة الخادم.

<div id="enabling-keeper-tracing">
  ### تمكين تتبّع طلبات Keeper
</div>

لتمكين التتبّع لطلبات Keeper، اضبط الإعدادات التالية في إعدادات عميل ZooKeeper/Keeper:

```xml theme={null}
<clickhouse>
    <zookeeper>
        <node>
            <host>keeper1</host>
            <port>9181</port>
        </node>
        <!-- Enable OpenTelemetry tracing context propagation -->
        <pass_opentelemetry_tracing_context>true</pass_opentelemetry_tracing_context>
    </zookeeper>
</clickhouse>
```

<div id="keeper-span-types">
  ### أنواع Span في Keeper
</div>

عند تمكين التتبّع، ينشئ ClickHouse وحدات span لكلٍّ من عمليات Keeper من جهة العميل ومن جهة الخادم:

**وحدات span من جهة العميل:**

* `zookeeper.create` — إنشاء عقدة جديدة
* `zookeeper.get` — جلب بيانات العقدة
* `zookeeper.set` — تعيين بيانات العقدة
* `zookeeper.remove` — إزالة عقدة
* `zookeeper.list` — سرد العقد الفرعية
* `zookeeper.exists` — التحقّق مما إذا كانت العقدة موجودة
* `zookeeper.multi` — تنفيذ عدة عمليات بشكل ذرّي
* `zookeeper.client.requests_queue` — الزمن المستغرَق في انتظار الطلبات في الطابور قبل إرسالها

**وحدات span من جهة الخادم (Keeper):**

* `keeper.receive_request` — استلام الطلب من العميل وتحليله
* `keeper.dispatcher.requests_queue` — انتظار الطلبات في طابور dispatcher
* `keeper.write.pre_commit` — المعالجة التمهيدية لطلبات الكتابة قبل Raft commit
* `keeper.write.commit` — معالجة طلبات الكتابة بعد Raft commit
* `keeper.read.wait_for_write` — طلبات القراءة التي تنتظر عمليات الكتابة التابعة
* `keeper.read.process` — معالجة طلبات القراءة
* `keeper.dispatcher.responses_queue` — انتظار الاستجابات في طابور dispatcher
* `keeper.send_response` — إرسال الاستجابة إلى العميل

<div id="sampling-and-performance">
  ### أخذ العينات والأداء
</div>

للحدّ من الأعباء الإضافية الناتجة عن التتبّع، يستخدم Keeper أخذ العينات الديناميكي. ويُضبط معدل أخذ العينات تلقائيًا بين 1/10,000 و1/10 بناءً على حجم الطلب. كما تُسجَّل مدد جميع الطلبات (التي خضعت لأخذ العينات والتي لم تخضع لها) في مقاييس المُدرَّج التكراري لمراقبة الأداء.

<div id="tracing-the-clickhouse-itself">
  ## تتبّع ClickHouse ذاته
</div>

ينشئ ClickHouse `trace spans` لكل استعلام، وكذلك لبعض مراحل تنفيذ الاستعلام، مثل تخطيط الاستعلام أو الاستعلامات الموزعة.

ولكي تكون معلومات التتبّع مفيدة، يجب تصديرها إلى نظام مراقبة يدعم OpenTelemetry، مثل [Jaeger](https://jaegertracing.io/) أو [Prometheus](https://prometheus.io/). ولا يعتمد ClickHouse على نظام مراقبة بعينه، بل يوفّر بيانات التتبّع فقط عبر جدول نظام. وتُخزَّن معلومات OpenTelemetry trace span [التي يتطلبها المعيار](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#span) في جدول [system.opentelemetry\_span\_log](/docs/ar/reference/system-tables/opentelemetry_span_log).

يجب تمكين هذا الجدول في تهيئة الخادم؛ راجع العنصر `opentelemetry_span_log` في ملف الإعداد الافتراضي `config.xml`. وهو مفعّل افتراضيًا.

تُحفَظ العلامات أو السمات في مصفوفتين متوازيتين تحتويان على المفاتيح والقيم. استخدم [ARRAY JOIN](/docs/ar/reference/statements/select/array-join) للعمل معها.

<div id="log-query-settings">
  ## إعدادات سجل الاستعلام
</div>

يتيح الإعداد [log\_query\_settings](/docs/ar/reference/settings/session-settings) تسجيل التغييرات التي تطرأ على إعدادات الاستعلام أثناء تنفيذه. عند تمكينه، تُسجَّل أي تعديلات تُجرى على إعدادات الاستعلام في سجل الـ span ضمن OpenTelemetry. وتُعد هذه الميزة مفيدة بشكل خاص في بيئات production لتتبّع تغييرات الإعدادات التي قد تؤثر في أداء الاستعلام.

<div id="integration-with-monitoring-systems">
  ## التكامل مع أنظمة المراقبة
</div>

حاليًا، لا توجد أداة جاهزة يمكنها تصدير بيانات التتبّع من ClickHouse إلى نظام مراقبة.

لأغراض الاختبار، يمكن إعداد التصدير باستخدام عرض مادي مع محرك [URL](/docs/ar/reference/engines/table-engines/special/url) على جدول [system.opentelemetry\_span\_log](/docs/ar/reference/system-tables/opentelemetry_span_log)، بحيث يرسل بيانات السجل الواردة إلى نقطة نهاية HTTP خاصة بمجمّع تتبّع. على سبيل المثال، لإرسال الحد الأدنى من بيانات span إلى مثيل Zipkin يعمل على `http://localhost:9411`، بتنسيق Zipkin v2 JSON:

```sql theme={null}
CREATE MATERIALIZED VIEW default.zipkin_spans
ENGINE = URL('http://127.0.0.1:9411/api/v2/spans', 'JSONEachRow')
SETTINGS output_format_json_named_tuples_as_objects = 1,
    output_format_json_array_of_rows = 1 AS
SELECT
    lower(hex(trace_id)) AS traceId,
    CASE WHEN parent_span_id = 0 THEN '' ELSE lower(hex(parent_span_id)) END AS parentId,
    lower(hex(span_id)) AS id,
    operation_name AS name,
    start_time_us AS timestamp,
    finish_time_us - start_time_us AS duration,
    cast(tuple('clickhouse'), 'Tuple(serviceName text)') AS localEndpoint,
    cast(tuple(
        attribute.values[indexOf(attribute.names, 'db.statement')]),
        'Tuple("db.statement" text)') AS tags
FROM system.opentelemetry_span_log
```

في حال حدوث أي أخطاء، سيُفقد دون أي إشعار الجزء من بيانات السجل الذي وقع فيه الخطأ. تحقّق من سجل الخادم بحثًا عن رسائل الخطأ إذا لم تصل البيانات.

<div id="related-content">
  ## محتوى ذي صلة
</div>

* مدونة: [Building an Observability Solution with ClickHouse - الجزء 2 - التتبعات](https://clickhouse.com/blog/storing-traces-and-spans-open-telemetry-in-clickhouse)