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

يُعد OpenTelemetry معيارًا مفتوحًا لتجميع التتبعات والمقاييس من التطبيقات الموزعة. ويدعم ClickHouse ‏OpenTelemetry إلى حدٍّ ما.

يقبل ClickHouse ترويسات HTTP الخاصة بسياق التتبع، كما هو موضح في توصية W3C. كما يقبل سياق التتبع عبر البروتوكول الأصلي المستخدم للتواصل بين خوادم ClickHouse أو بين العميل والخادم. ولأغراض الاختبار اليدوي، يمكن تمرير ترويسات سياق التتبع المتوافقة مع توصية Trace Context إلى clickhouse-client باستخدام الخيارين --opentelemetry-traceparent و--opentelemetry-tracestate.

إذا لم يتم تمرير سياق تتبع أصل، أو كان سياق التتبع الممرَّر غير متوافق مع معيار W3C المذكور أعلاه، يمكن لـ ClickHouse بدء تتبّع جديد باحتمال يتحكم فيه إعداد opentelemetry_start_trace_probability.

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

• الاستعلامات المُرسلة إلى خوادم ClickHouse البعيدة، مثل عند استخدام محرك الجدول Distributed.

• دالة الجدول url. تُرسَل معلومات سياق التتبع ضمن ترويسة HTTP.

يدعم ClickHouse تتبّع OpenTelemetry لطلبات ClickHouse Keeper (خدمة تنسيق متوافقة مع ZooKeeper). تتيح هذه الميزة رؤية تفصيلية لدورة حياة عمليات Keeper، بدءًا من إرسال الطلب من العميل وصولًا إلى معالجته على جهة الخادم.

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

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

عند تمكين التتبّع، ينشئ 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 — إرسال الاستجابة إلى العميل

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

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

ولكي تكون معلومات التتبّع مفيدة، يجب تصديرها إلى نظام مراقبة يدعم OpenTelemetry، مثل Jaeger أو Prometheus. ولا يعتمد ClickHouse على نظام مراقبة بعينه، بل يوفّر بيانات التتبّع فقط عبر جدول نظام. وتُخزَّن معلومات OpenTelemetry trace span التي يتطلبها المعيار في جدول system.opentelemetry_span_log.

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

تُحفَظ العلامات أو السمات في مصفوفتين متوازيتين تحتويان على المفاتيح والقيم. استخدم ARRAY JOIN للعمل معها.

يتيح الإعداد log_query_settings تسجيل التغييرات التي تطرأ على إعدادات الاستعلام أثناء تنفيذه. عند تمكينه، تُسجَّل أي تعديلات تُجرى على إعدادات الاستعلام في سجل الـ span ضمن OpenTelemetry. وتُعد هذه الميزة مفيدة بشكل خاص في بيئات production لتتبّع تغييرات الإعدادات التي قد تؤثر في أداء الاستعلام.

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

لأغراض الاختبار، يمكن إعداد التصدير باستخدام عرض مادي مع محرك URL على جدول system.opentelemetry_span_log، بحيث يرسل بيانات السجل الواردة إلى نقطة نهاية HTTP خاصة بمجمّع تتبّع. على سبيل المثال، لإرسال الحد الأدنى من بيانات span إلى مثيل Zipkin يعمل على http://localhost:9411، بتنسيق Zipkin v2 JSON:

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

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

• مدونة: Building an Observability Solution with ClickHouse - الجزء 2 - التتبعات