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 на лету (например, чтобы раскрыть inline-кадры), используйте функции интроспекции 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) — ревизия сборки сервера ClickHouse. При подключении к серверу с помощью 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 означает сбор трассировок стека по астрономическому времени. CPU означает сбор трассировок стека по времени CPU. Memory означает сбор событий выделения и освобождения памяти, когда её выделение превышает следующую водяную метку. MemorySample означает сбор случайных событий выделения и освобождения памяти. MemoryPeak означает сбор обновлений пикового потребления памяти. ProfileEvent означает сбор приращений profile events. JemallocSample означает сбор сэмплов jemalloc. MemoryAllocatedWithoutCheck означает сбор значительных выделений памяти (>16MiB), который выполняется без учёта каких-либо ограничений памяти (только для разработчиков ClickHouse).Instrumentation означает трассы, собранные с помощью инструментирования через XRay.
cpu_id (UInt64) — идентификатор процессора.
thread_id (UInt64) — идентификатор потока.
thread_name (LowCardinality(String)) — имя потока.
query_id (String) — идентификатор запроса, который можно использовать для получения сведений о выполнявшемся запросе из системной таблицы query_log.
trace (Array(UInt64)) — трассировка стека на момент сэмплирования. Для типов трассировок, собранных профилировщиком, на платформах ELF, кроме FreeBSD, адреса в основном бинарном файле ClickHouse хранятся как физические смещения в файле, а остальные адреса являются виртуальными адресами памяти в процессе сервера ClickHouse. Строки трассировки Instrumentation являются исключением: в них хранятся необработанные виртуальные адреса памяти.
size (Int64) — для типов trace Memory, MemorySample, MemoryAllocatedWithoutCheck и MemoryPeak это объём выделенной памяти, для остальных типов trace — 0.
ptr (UInt64) — адрес выделенного фрагмента.
memory_context (Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)) — контекст трекера памяти (только для Memory/MemoryPeak): контекст Unknown не определён для данного trace_type. Global обозначает контекст сервера. User обозначает контекст пользователя или слияния. Process обозначает контекст процесса (то есть запроса). Thread обозначает контекст потока (потока конкретного процесса). Max — это специальное значение, которое означает, что трекер памяти не заблокирован (для столбца 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)) — Для типа trace ProfileEvent это имя обновлённого события профиля, для других типов trace это пустая строка.
increment (Int64) — для трассировки типа ProfileEvent это величина приращения события профиля, для остальных типов трассировки — 0.
symbols (Array(LowCardinality(String))) — Если символизация включена, содержит деманглированные имена символов, соответствующие trace. Символизацию можно включить или отключить с помощью настройки symbolize в разделе trace_log файла конфигурации сервера; настройка применяется к типам трассировок, собираемым профилировщиком, тогда как строки с типом трассировки Instrumentation символизируются независимо от неё. Символизация поддерживается на платформах ELF (таких как Linux) и macOS; на FreeBSD этот столбец всегда пуст.
lines (Array(LowCardinality(String))) — Если символизация включена, содержит строки с именами файлов и номерами строк, соответствующими trace. Настройка symbolize применяется к типам трассировок, собираемым профилировщиком, тогда как строки с типом трассировки Instrumentation символизируются независимо от неё. Символизация поддерживается на платформах ELF (таких как Linux) и macOS; на FreeBSD этот столбец всегда пуст. Местоположения в исходном коде определяются по возможности: для них требуется отладочная информация (пакет .dSYM в macOS), а на платформах ELF они определяются только для кадров внутри основного бинарного файла ClickHouse; для неразрешённых кадров записи пусты.
function_id (Nullable(Int32)) — Для типа trace Instrumentation — идентификатор, присвоенный функции в разделе xray_instr_map ELF-бинарного файла.
function_name (Nullable(String)) — Для Instrumentation типа trace — имя функции, в которую добавлена инструментация.
handler (Nullable(String)) — Для трассировок типа Instrumentation — обработчик функции с инструментированием.
entry_type (Nullable(Enum8('Entry' = 0, 'Exit' = 1))) — Для трассы типа Instrumentation: тип Entry/Exit инструментируемой функции.
duration_nanoseconds (Nullable(UInt64)) — для trace-типа Instrumentation: время выполнения функции в наносекундах.

Псевдонимы:

build_id — псевдоним для 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, чтобы экспортировать в файл trace.json, который затем можно импортировать либо в Perfetto, либо в speedscope.

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

Мы можем опустить часть со стеком, если нужна более компактная, но менее информативная трассировка.

См. также

SYSTEM INSTRUMENT — Добавить или удалить точки инструментирования.
system.instrumentation — Просмотреть инструментированные точки.
system.symbols — Просмотреть символы для добавления точек инструментирования.