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

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

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

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

افتراضيًا، تحلّ أداة التنميط رموز تتبعات المكدس وقت جمعها وتخزّن النتائج في العمودين symbols وlines من system.trace_log، لذا تقرأ الأمثلة أدناه هذين العمودين مباشرةً ولا تتطلب دوال الاستبطان. ويجري التحكم في حلّ الرموز عبر الإعداد symbolize في قسم تهيئة الخادم trace_log (وهو مفعّل افتراضيًا)، وهو مدعوم على منصات ELF (مثل Linux) وmacOS؛ أما على FreeBSD، فيكون العمودان symbols وlines فارغين دائمًا. تأتي أسماء الدوال في symbols من جدول رموز الملف الثنائي وهي متاحة افتراضيًا. أما مواضع الشيفرة المصدرية في lines فهي تُوفَّر بأفضل جهد: إذ تتطلب معلومات تصحيح الأخطاء (وفي macOS، حزمة .dSYM بجوار الملف الثنائي)، وعلى منصات ELF لا تُحل إلا الإطارات الموجودة داخل الملف الثنائي الرئيسي لـ ClickHouse، لذلك تُترك الإدخالات الخاصة بالإطارات التي لا يمكن حلّها (مثل تلك الموجودة في المكتبات المشتركة) فارغة. إذا كان حلّ الرموز معطّلًا، فاستخدم دوال الاستبطان addressToSymbol وdemangle وaddressToLine دوال الاستبطان لحلّ العناوين الأولية في العمود trace بدلًا من ذلك. تتوفر هذه الدوال على المنصات نفسها التي يدعمها حلّ الرموز (منصات ELF مثل Linux وmacOS)؛ أما على FreeBSD، فهي غير مُصرَّفة أيضًا، لذا يجب حلّ العناوين في trace خارج الخادم.

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

ClickHouse Cloud

في ClickHouse Cloud، يمكنك الحصول على معرّف الاستعلام بالنقر على ”…” في أقصى يمين الشريط أعلى جدول نتائج الاستعلام (بجوار مفتاح التبديل table/chart). سيؤدي ذلك إلى فتح قائمة سياق يمكنك من خلالها النقر على “Copy query ID”.

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

SELECT
    count(),
    arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\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

مُدار ذاتيًا

SELECT
    count(),
    arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\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

​

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

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

1. ثبّت ClickHouse مع معلومات تصحيح الأخطاء

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

   1. اتبع التعليمات في الخطوة “إعداد مستودع Debian”
   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 — ولا تحتاج إلى القيام بأي إجراء خاص لتمكينها
2. تحقّق من إعدادات الخادم

   تأكد من إعداد قسم trace_log في ملف إعدادات الخادم. وهو مُمكَّن افتراضيًا:

   <!-- Trace log. Stores stack traces collected by query profilers.
        See query_profiler_real_time_period_ns and query_profiler_cpu_time_period_ns settings. -->
   <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>
       <!-- Indication whether logs should be dumped to the disk in case of a crash -->
       <flush_on_crash>false</flush_on_crash>
       <symbolize>true</symbolize>
   </trace_log>
   

   يضبط هذا القسم الجدول النظامي trace_log الذي يحتوي على نتائج عمل أداة التنميط. يؤدي الخيار symbolize (المُمكَّن افتراضيًا) إلى أن يحلّل ClickHouse كل إطار مكدس وقت جمع البيانات ويخزّن أسماء الدوال بعد فكّ تشويهها ومواقع المصدر في العمودين symbols وlines. تأتي أسماء الدوال في symbols من جدول الرموز وتكون متاحة افتراضيًا، بينما تتطلب مواقع المصدر في lines معلومات تصحيح الأخطاء (حزمة .dSYM على macOS)، ولا تُحلّ على منصات ELF إلا للإطارات الموجودة داخل الملف الثنائي الرئيسي لـ ClickHouse؛ وتحتوي الإطارات غير المحلولة على إدخالات lines فارغة.

   لاحظ أن العناوين الخام في العمود trace أقل استقرارًا عبر عمليات إعادة التشغيل والترقيات من الأعمدة التي رُمّزت مسبقًا. على منصات ELF باستثناء FreeBSD، تُخزَّن الإطارات الموجودة في الملف الثنائي الرئيسي لـ ClickHouse كإزاحات فعلية داخل الملف، لذا تظل قابلة للحل عبر عمليات إعادة التشغيل ما دام الملف الثنائي لم يتغير؛ أما على macOS وFreeBSD فتُخزَّن كعناوين افتراضية وقت التشغيل قد تصبح غير صالحة بعد إعادة التشغيل. تُخزَّن الإطارات خارج الملف الثنائي الرئيسي (مثل تلك الموجودة في المكتبات المشتركة) دائمًا كعناوين افتراضية وقت التشغيل قد تصبح غير صالحة بعد إعادة التشغيل، ويصبح أي عنوان خام غير قابل للحل بعد ترقية الملف الثنائي لأن تخطيط الشيفرة يتغير. لا ينظّف ClickHouse الجدول عند إعادة التشغيل، لذا قد تبقى العناوين الخام المتقادمة. أما العمودان symbols وlines اللذان رُمّزا مسبقًا فيظلان صالحين عبر عمليات إعادة التشغيل والترقيات، لذا فضّلهما عند تحليل البيانات التاريخية.

3. اضبط مؤقتات التحليل

   أعِد الإعدادين query_profiler_cpu_time_period_ns أو query_profiler_real_time_period_ns. يمكن استخدام كلا الإعدادين في الوقت نفسه.

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

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

4. حلّل الجدول النظامي trace_log

   وللحصول على profile لاستعلام معيّن، تحتاج إلى تجميع البيانات من الجدول trace_log. ويمكنك تجميع البيانات بحسب الدوال الفردية أو بحسب تتبعات المكدس كاملة.

   عند تمكين ترميز الرموز (وهو الإعداد الافتراضي)، تكون أسماء الدوال بعد فك تشويهها ومواضعها في المصدر متاحة بالفعل في العمودين symbols وlines، لذا لا يلزم إجراء إعداد إضافي. لا يُدعم ترميز الرموز على FreeBSD، حيث تكون هذه الأعمدة فارغة دائمًا. قد تكون إدخالات lines فارغة للإطارات التي تفتقر إلى معلومات تصحيح الأخطاء أو التي تقع خارج الملف الثنائي الرئيسي لـ ClickHouse (راجع أعلاه).

   إذا كان ترميز الرموز معطّلًا، أو كنت تريد تحليل العناوين الأولية في العمود trace عند الحاجة (على سبيل المثال، لتوسيع الإطارات المضمنة)، فاسمح باستخدام دوال الاستبطان عبر الإعداد allow_introspection_functions:

   SET allow_introspection_functions=1
   

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

   استخدم دوال الاستبطان addressToLine وaddressToLineWithInlines وaddressToSymbol وdemangle للحصول على أسماء الدوال ومواضعها في شيفرة ClickHouse. وكما في ترميز الرموز، تتوفر هذه الدوال على منصات ELF (مثل Linux) وmacOS، ولكن ليس على FreeBSD.

   إذا كنت بحاجة إلى تصوّر معلومات trace_log، فجرّب flamegraph وspeedscope.

​

إنشاء مخططات اللهب باستخدام الدالة flameGraph

يوفّر ClickHouse الدالة التجميعية flameGraph التي تُنشئ مخطط اللهب مباشرةً من تتبعات المكدس المخزّنة في trace_log. ويكون الناتج مصفوفة من السلاسل النصية بتنسيق متوافق مع flamegraph.pl.

البنية:

flameGraph(traces, [size = 1], [ptr = 0])

الوسائط:

• traces — تتبّع مكدس الاستدعاءات. Array(UInt64).
• size — حجم التخصيص لتنميط الذاكرة. Int64.
• ptr — عنوان التخصيص. UInt64.

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

​

مخطط اللهب للـ CPU

تتطلب الاستعلامات أدناه أن يكون flamegraph.pl مثبّتًا على جهازك.

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

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

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

SET query_profiler_cpu_time_period_ns = 10000000;

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

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

​

مخطط اللهب للذاكرة — جميع عمليات تخصيص الذاكرة

SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;

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

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

​

مخطط اللهب للذاكرة — التخصيصات غير المُحرَّرة

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

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;

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

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

​

مخطط اللهب للذاكرة — التخصيصات النشطة في لحظة زمنية معيّنة

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

SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;

​

تتبّع استخدام الذاكرة بمرور الوقت

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;

​

حدِّد النقطة الزمنية ذات أعلى استخدام للذاكرة

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'
);

​

أنشئ مخطط اللهب لتخصيصات الذاكرة النشطة عند تلك اللحظة الزمنية

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

​

أنشئ مخطط مخطط اللهب لعمليات تحرير الذاكرة بعد تلك النقطة الزمنية (لفهم ما الذي حُرِّر لاحقًا)

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

​

مثال

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

• يصفّي بيانات trace_log بحسب معرّف الاستعلام والتاريخ الحالي.
• يقرأ العمودين symbols وlines المرمّزين مسبقًا لإنشاء تقرير يتضمن:
  • أسماء الرموز ودوال الشيفرة المصدرية المقابلة لها.
  • مواضع هذه الدوال في الشيفرة المصدرية.
• يُجمّع حسب تتبع المكدس الخام (العمود trace)، مع استخدام الأعمدة المرمّزة للعرض فقط، لضمان عدم دمج تتبعات المكدس المتميزة مطلقًا نتيجة حلّ الرموز بأفضل جهد.

SELECT
    count(),
    arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\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