system.trace_log | ClickHouse Docs

الوصف

يحتوي على تتبعات المكدس التي يجمعها مُحلِّل أداء الاستعلام المعتمد على أخذ العينات.

ينشئ ClickHouse هذا الجدول عند تعيين قسم إعدادات الخادم trace_log. راجع أيضًا الإعدادات التالية: query_profiler_real_time_period_ns، query_profiler_cpu_time_period_ns، memory_profiler_step، memory_profiler_sample_probability، trace_profile_events.

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

الأعمدة

hostname (LowCardinality(String)) — اسم مضيف الخادم الذي ينفّذ الاستعلام.
event_date (Date) — تاريخ لحظة أخذ العينة.
event_time (DateTime) — الطابع الزمني للحظة أخذ العينة.
event_time_microseconds (DateTime64(6)) — الطابع الزمني للحظة أخذ العينة بدقة الميكروثانية.
timestamp_ns (UInt64) — الطابع الزمني للحظة أخذ العينة بالنانوثانية.
revision (UInt32) — رقم build revision الخاص بـ ClickHouse server. عند الاتصال بالخادم باستخدام clickhouse-client، سترى سلسلة مشابهة لـ Connected to ClickHouse server version 19.18.1.. يحتوي هذا الحقل على revision، وليس version الخاص بالخادم.
trace_type (Enum8('Real' = 0, 'CPU' = 1, 'Memory' = 2, 'MemorySample' = 3, 'MemoryPeak' = 4, 'ProfileEvent' = 5, 'JemallocSample' = 6, 'MemoryAllocatedWithoutCheck' = 7, 'Instrumentation' = 8)) — نوع التتبّع: يمثّل Real جمع stack traces وفق wall-clock time. ويمثّل CPU جمع stack traces وفق وقت CPU. ويمثّل Memory جمع allocations وdeallocations عندما يتجاوز تخصيص الذاكرة الـ watermark التالي. ويمثّل MemorySample جمع allocations وdeallocations عشوائيًا. ويمثّل MemoryPeak جمع تحديثات peak memory usage. ويمثّل ProfileEvent جمع الزيادات في profile events. ويمثّل JemallocSample جمع عينات jemalloc. ويمثّل MemoryAllocatedWithoutCheck جمع عمليات التخصيص الكبيرة (>16MiB) مع تجاهل أي memory limit (لمطوري ClickHouse فقط). ويمثّل Instrumentation traces التي جُمعت عبر instrumentation المُنفَّذ بواسطة XRay.
cpu_id (UInt64) — معرّف CPU.
thread_id (UInt64) — معرّف thread.
thread_name (LowCardinality(String)) — اسم thread.
query_id (String) — معرّف الاستعلام الذي يمكن استخدامه للحصول على تفاصيل عن استعلام كان قيد التشغيل من system table المسماة query_log.
trace (Array(UInt64)) — stack trace عند لحظة أخذ العينة. بالنسبة إلى أنواع التتبّع التي يجمعها Profiler، على منصات ELF باستثناء FreeBSD، تُخزَّن العناوين داخل ملف ClickHouse binary الرئيسي كإزاحات فعلية داخل الملف، بينما تكون العناوين الأخرى عناوين ذاكرة افتراضية داخل ClickHouse server process. تمثّل صفوف تتبّع Instrumentation استثناءً: إذ تخزّن عناوين ذاكرة افتراضية خامًا.
size (Int64) — بالنسبة إلى أنواع التتبّع Memory وMemorySample وMemoryAllocatedWithoutCheck وMemoryPeak، فهو مقدار الذاكرة المخصّصة، أما بالنسبة إلى أنواع التتبّع الأخرى فقيمته 0.
ptr (UInt64) — عنوان الـ chunk المخصّص.
memory_context (Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)) — سياق memory tracker (فقط لـ Memory/MemoryPeak): يكون سياق Unknown غير معرّف لهذا trace_type. ويمثّل Global سياق الخادم. ويمثّل User سياق المستخدم/الدمج. ويمثّل Process سياق العملية (أي الاستعلام). ويمثّل Thread سياق thread (thread الخاصة بعملية معيّنة). أما Max فهي قيمة خاصة تعني أن memory tracker غير محظور (للعمود blocked_context).
memory_blocked_context (Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)) — السياق الذي يكون فيه متتبّع الذاكرة موقوفًا (لمطوري ClickHouse فقط): سياق Unknown غير معرّف لهذا trace_type. يشير Global إلى سياق الخادم. ويشير User إلى سياق المستخدم/الدمج. ويشير Process إلى سياق العملية (أي الاستعلام). ويشير Thread إلى سياق الخيط (خيط العملية المعنية). أما Max فهي قيمة خاصة تعني أن متتبّع الذاكرة غير موقوف (لعمود blocked_context).
event (LowCardinality(String)) — بالنسبة إلى نوع التتبّع ProfileEvent، فهذا هو اسم حدث profile الذي تم تحديثه، أما في أنواع التتبّع الأخرى فهو سلسلة فارغة.
increment (Int64) — بالنسبة إلى نوع التتبّع ProfileEvent، فهذا هو مقدار الزيادة في حدث profile، أما في أنواع التتبّع الأخرى فهو 0.
symbols (Array(LowCardinality(String))) — إذا كان تحويل الرموز إلى أسماء مفعّلًا، فسيحتوي على أسماء الرموز بعد فك تشويهها، المقابلة لـ trace. يمكن تفعيل تحويل الرموز إلى أسماء أو تعطيله في الإعداد symbolize ضمن trace_log في ملف تهيئة الخادم؛ ينطبق الإعداد على أنواع التتبّع التي يجمعها Profiler، بينما تُحوَّل صفوف نوع التتبّع Instrumentation إلى رموز بغض النظر عنه. يُدعم تحويل الرموز إلى أسماء على منصات ELF (مثل Linux) وmacOS؛ أما على FreeBSD فيكون هذا العمود فارغًا دائمًا.
lines (Array(LowCardinality(String))) — إذا كان تحويل الرموز إلى أسماء مفعّلًا، فسيحتوي على سلاسل تضم أسماء الملفات مع أرقام الأسطر، المقابلة لـ trace. ينطبق الإعداد symbolize على أنواع التتبّع التي يجمعها Profiler، بينما تُحوَّل صفوف نوع التتبّع Instrumentation إلى رموز بغض النظر عنه. يُدعم تحويل الرموز إلى أسماء على منصات ELF (مثل Linux) وmacOS؛ أما على FreeBSD فيكون هذا العمود فارغًا دائمًا. تُحدَّد مواقع المصدر بأفضل جهد: فهي تتطلب معلومات تصحيح الأخطاء (حزمة .dSYM على macOS)، وعلى منصات ELF لا تُحدَّد إلا للإطارات داخل ملف ClickHouse الثنائي الرئيسي؛ أما الإطارات غير المحلولة فلها إدخالات فارغة.
function_id (Nullable(Int32)) — بالنسبة إلى نوع التتبّع Instrumentation، فهذا هو المعرّف المُسنَد إلى الدالة في القسم xray_instr_map من ملف ELF الثنائي.
function_name (Nullable(String)) — بالنسبة إلى نوع التتبّع Instrumentation، فهذا هو اسم الدالة التي خضعت للـ instrumentation.
handler (Nullable(String)) — بالنسبة إلى نوع التتبّع Instrumentation، فهذا هو handler الخاص بالدالة التي خضعت للـ instrumentation.
entry_type (Nullable(Enum8('Entry' = 0, 'Exit' = 1))) — بالنسبة إلى نوع التتبّع Instrumentation، فهذا هو نوع الإدخال للدالة التي خضعت للـ instrumentation.
duration_nanoseconds (Nullable(UInt64)) — بالنسبة إلى نوع التتبّع Instrumentation، فهذا هو الزمن الذي استغرقتْه الدالة أثناء التشغيل، بالنانوثانية.

الأسماء المستعارة:

build_id — اسم مستعار لمعرّف البناء للملف الثنائي لخادم ClickHouse قيد التشغيل.

يمكن تمكين حل الرموز أو تعطيله باستخدام الإعداد symbolize ضمن trace_log في ملف إعدادات الخادم. وهو مُمكَّن افتراضيًا. ينطبق هذا الإعداد على أنواع التتبعات التي يجمعها محلل الأداء؛ أما الصفوف ذات نوع التتبّع Instrumentation فيُجرى فيها حلّ الرموز بغض النظر عن هذا الإعداد.

مثال

SELECT * FROM system.trace_log LIMIT 1 \G

Row 1:
──────
hostname:                clickhouse.eu-central1.internal
event_date:              2025-11-11
event_time:              2025-11-11 11:53:59
event_time_microseconds: 2025-11-11 11:53:59.128333
timestamp_ns:            1762862039128333000
revision:                54504
trace_type:              Instrumentation
cpu_id:                  19
thread_id:               3166432 -- 3.17 million
query_id:                ef462508-e189-4ea2-b231-4489506728e8
trace:                   [350594916,447733712,447742095,447727324,447726659,221642873,450882315,451852359,451905441,451885554,512404306,512509092,612861767,612863269,612466367,612455825,137631896259267,137631896856768]
size:                    0
ptr:                     0
memory_context:          Unknown
memory_blocked_context:  Unknown
event:
increment:               0
symbols:                 ['StackTrace::StackTrace()','DB::InstrumentationManager::createTraceLogElement(DB::InstrumentationManager::InstrumentedPointInfo const&, XRayEntryType, std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>>) const','DB::InstrumentationManager::profile(XRayEntryType, DB::InstrumentationManager::InstrumentedPointInfo const&)','DB::InstrumentationManager::dispatchHandlerImpl(int, XRayEntryType)','DB::InstrumentationManager::dispatchHandler(int, XRayEntryType)','__xray_FunctionEntry','DB::QueryMetricLog::startQuery(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>>, unsigned long)','DB::logQueryStart(std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>> const&, std::__1::shared_ptr<DB::Context> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, unsigned long, std::__1::shared_ptr<DB::IAST> const&, DB::QueryPipeline const&, DB::IInterpreter const*, bool, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, bool)','DB::executeQueryImpl(char const*, char const*, std::__1::shared_ptr<DB::Context>, DB::QueryFlags, DB::QueryProcessingStage::Enum, std::__1::unique_ptr<DB::ReadBuffer, std::__1::default_delete<DB::ReadBuffer>>&, std::__1::shared_ptr<DB::IAST>&, std::__1::shared_ptr<DB::ImplicitTransactionControlExecutor>, std::__1::function<void ()>)','DB::executeQuery(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::shared_ptr<DB::Context>, DB::QueryFlags, DB::QueryProcessingStage::Enum)','DB::TCPHandler::runImpl()','DB::TCPHandler::run()','Poco::Net::TCPServerConnection::start()','Poco::Net::TCPServerDispatcher::run()','Poco::PooledThread::run()','Poco::ThreadImpl::runnableEntry(void*)','start_thread','__clone3']
lines:                   ['./build/../src/Common/StackTrace.cpp:395','./src/Common/StackTrace.h:62','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:738','./build/./src/Interpreters/InstrumentationManager.cpp:257','./build/./src/Interpreters/InstrumentationManager.cpp:225','','./build/./src/Interpreters/QueryMetricLog.cpp:0','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:667','./build/./src/Interpreters/executeQuery.cpp:0','./build/./src/Interpreters/executeQuery.cpp:0','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:744','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:583','./build/../base/poco/Net/src/TCPServerConnection.cpp:54','../contrib/llvm-project/libcxx/include/__memory/unique_ptr.h:80','./build/../base/poco/Foundation/src/ThreadPool.cpp:219','../base/poco/Foundation/include/Poco/AutoPtr.h:77','','']
function_id:             231255
function_name:           DB::QueryMetricLog::startQuery(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>>, unsigned long)
handler:                 profile
entry_type:              Exit
duration_nanoseconds:   58435

التحويل إلى تنسيق تتبّع الأحداث في Chrome

يمكن تحويل بيانات تحليل الأداء إلى تنسيق تتبّع الأحداث في Chrome باستخدام الاستعلام التالي. احفظ الاستعلام في ملف chrome_trace.sql:

WITH traces AS (
    SELECT * FROM system.trace_log
    WHERE event_date >= today() AND trace_type = 'Instrumentation' AND handler = 'profile'
    ORDER BY event_time, entry_type
)
SELECT
    format(
        '{{"traceEvents": [{}\n]}}',
        arrayStringConcat(
            groupArray(
                format(
                    '\n{{"name": "{}", "cat": "clickhouse", "ph": "{}", "ts": {}, "pid": 1, "tid": {}, "args": {{"query_id": "{}", "cpu_id": {}, "stack": [{}]}}}},',
                    function_name,
                    if(entry_type = 0, 'B', 'E'),
                    timestamp_ns/1000,
                    toString(thread_id),
                    query_id,
                    cpu_id,
                    arrayStringConcat(arrayMap((x, y) -> concat('"', x, ': ', y, '", '), lines, symbols))
                )
            )
        )
    )
FROM traces;

وتشغيله باستخدام ClickHouse Client لتصديره إلى ملف trace.json يمكن استيراده إما عبر Perfetto أو speedscope.

echo $(clickhouse client --query "$(cat chrome_trace.sql)") > trace.json

يمكننا حذف جزء المكدس إذا أردنا تتبّعًا أكثر اختصارًا لكنه أقل إفادة.

انظر أيضًا

SYSTEM INSTRUMENT — أضف نقاط القياس أو أزلها.
system.instrumentation — استعرض نقاط القياس المُضافة.
system.symbols — استعرض الرموز لإضافة نقاط القياس إليها.