system.trace_log 시스템 테이블

system.trace_log 는 sampling query profiler 와 trace_type 열에 이름이 있는 다른 소스가 수집한 스택 트레이스를 담고 있어요. ClickHouse는 trace_log 서버 구성 섹션이 설정되면 이 테이블을 생성해요.

출처: 문서

본문

ClickHouse Cloud에서의 조회 — 이 시스템 테이블의 데이터는 ClickHouse Cloud에서 각 노드에 로컬로 저장돼요. 따라서 모든 데이터의 완전한 뷰를 얻으려면 clusterAllReplicas 함수가 필요해요. 자세한 내용은 여기 를 참고하세요.

Description

sampling query profiler 와 trace_type 열에 이름이 있는 다른 소스가 수집한 스택 트레이스를 포함해요. 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. 심볼화(symbolization)가 활성화되면(기본값) 디맹글된 함수 이름과 소스 위치가 이미 symbols 및 lines 열에 있어서 introspection 함수 없이 로그를 직접 분석할 수 있어요. symbolize 설정은 프로파일러 수집 트레이스 유형에 적용되고 Instrumentation 트레이스 유형의 행은 이와 무관하게 항상 심볼화돼요. 심볼화는 ELF 플랫폼(예: Linux)과 macOS에서 지원되며, FreeBSD에서는 symbols 와 lines 열이 항상 비어 있어요. symbols 의 함수 이름은 바이너리의 심볼 테이블에서 가져오며 기본적으로 사용할 수 있고, lines 의 소스 위치는 최선(best-effort) 방식이에요: 디버그 정보(macOS의 .dSYM 번들)가 필요하며, ELF 플랫폼에서는 메인 ClickHouse 바이너리 내부의 프레임에 대해서만 해석되고, 해석되지 않은 프레임은 빈 lines 항목을 가져요. 심볼화가 비활성화되었거나, trace 열의 원시 주소를 즉시 해석하고 싶다면(예: 인라인 프레임 확장), addressToLine, addressToLineWithInlines, addressToSymbol 및 demangle introspection 함수를 사용해요. 이 함수들은 심볼화와 같은 플랫폼(ELF 플랫폼, 예: Linux 및 macOS)에서 사용할 수 있고, FreeBSD에서는 둘 다 컴파일되지 않으므로 trace 의 주소는 서버 밖에서 해석해야 해요.

Chrome Event Trace Format으로 변환

프로파일링 데이터는 다음 쿼리로 Chrome의 Event Trace Format으로 변환할 수 있어요. 쿼리를 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로 실행하여 Perfetto 또는 speedscope로 가져올 수 있는 trace.json 파일로 내보내요.

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

더 압축적이지만 정보가 적은 트레이스를 원하면 스택 부분을 생략할 수 있어요. 이 테이블은 언제든지 안전하게 truncate 하거나 drop 할 수 있어요.

Columns

hostname (LowCardinality(String)) — 쿼리를 실행한 서버의 호스트 이름이에요.
clickhouse_version (LowCardinality(String)) — 이 행을 만든 ClickHouse 서버의 버전이에요.
system_processor (LowCardinality(String)) — 이 행을 만든 ClickHouse 서버의 CPU 아키텍처예요.
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, ‘MemoryLargeAllocation’ = 9)) — 트레이스 유형이에요: Real 은 벽시계 시간(wall-clock time)으로 스택 트레이스를 수집함을 나타내요. CPU 는 CPU 시간으로 스택 트레이스를 수집함을 나타내요. Memory 는 메모리 할당이 다음 워터마크를 초과할 때 할당과 해제를 수집함을 나타내요. MemorySample 은 무작위 할당과 해제를 수집함을 나타내요. MemoryPeak 은 피크 메모리 사용량의 업데이트를 수집함을 나타내요. ProfileEvent 는 프로파일 이벤트의 증가를 수집함을 나타내요. JemallocSample 은 jemalloc 샘플을 수집함을 나타내요. MemoryAllocatedWithoutCheck 는 메모리 제한을 무시하고 수행되는 중요한 할당(>16MiB)의 수집을 나타내요(ClickHouse 개발자 전용). Instrumentation 은 XRay를 통해 수행된 계측에 의해 수집된 트레이스를 나타내요. MemoryLargeAllocation 은 크기가 min_allocation_size_to_log_stack_trace 에 도달한 전역 메모리 추적기로의 단일 청구를 나타내며, 이러한 트레이스는 서버 로그에도 기록돼요(ClickHouse 개발자 전용).
cpu_id (UInt64) — CPU 식별자예요.
thread_id (UInt64) — 스레드 식별자예요.
thread_name (LowCardinality(String)) — 스레드 이름이에요.
query_id (String) — query_log 시스템 테이블에서 실행 중이던 쿼리에 대한 세부 정보를 얻는 데 사용할 수 있는 쿼리 식별자예요.
trace (Array(UInt64)) — 샘플링 시점의 스택 트레이스예요. 프로파일러 수집 트레이스 유형의 경우 FreeBSD를 제외한 ELF 플랫폼에서 메인 ClickHouse 바이너리 내부의 주소는 물리적 파일 오프셋으로 저장되고, 다른 주소는 ClickHouse 서버 프로세스 내부의 가상 메모리 주소로 저장돼요. Instrumentation 트레이스 행은 예외로 원시 가상 메모리 주소를 저장해요.
size (Int64) — 메모리 트레이스 유형의 경우 크기(바이트)예요: Memory 및 MemoryAllocatedWithoutCheck 는 할당된 크기, MemorySample 및 JemallocSample 은 할당 크기(해제 시 음수), MemoryPeak 는 추적기의 새 피크, MemoryLargeAllocation 은 전역 메모리 추적기로의 청구 크기예요. 다른 트레이스 유형은 0이에요.
ptr (UInt64) — 할당된 청크의 주소예요.
memory_context (Enum8(‘Unknown’ = -1, ‘Global’ = 0, ‘User’ = 1, ‘Process’ = 2, ‘Thread’ = 3, ‘Max’ = 4)) — 메모리 추적기 컨텍스트(Memory, MemoryPeak, MemoryLargeAllocation에만 해당)예요: 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)) — ProfileEvent 트레이스 유형의 경우 업데이트된 프로파일 이벤트의 이름이고, 다른 트레이스 유형은 빈 문자열이에요.
increment (Int64) — ProfileEvent 트레이스 유형의 경우 프로파일 이벤트의 증가량이고, 다른 트레이스 유형은 0이에요.
symbols (Array(LowCardinality(String))) — 심볼화가 활성화되어 있으면 trace 에 해당하는 디맹글된 심볼 이름을 포함해요. 심볼화는 서버 구성 파일의 trace_log 아래 symbolize 설정에서 활성화/비활성화할 수 있으며, 설정은 프로파일러 수집 트레이스 유형에 적용되고 Instrumentation 트레이스 유형의 행은 이와 무관하게 항상 심볼화돼요. 심볼화는 ELF 플랫폼(예: Linux)과 macOS에서 지원되며 FreeBSD에서는 이 열이 항상 비어 있어요.
lines (Array(LowCardinality(String)) — 심볼화가 활성화되어 있으면 trace 에 해당하는 파일 이름과 줄 번호가 있는 문자열을 포함해요. symbolize 설정은 프로파일러 수집 트레이스 유형에 적용되고 Instrumentation 트레이스 유형의 행은 이와 무관하게 항상 심볼화돼요. 심볼화는 ELF 플랫폼(예: Linux)과 macOS에서 지원되며 FreeBSD에서는 이 열이 항상 비어 있어요. 소스 위치는 최선 방식이에요: 디버그 정보(macOS의 .dSYM 번들)가 필요하며, ELF 플랫폼에서는 메인 ClickHouse 바이너리 내부의 프레임에 대해서만 해석되고, 해석되지 않은 프레임은 빈 항목을 가져요.
function_id (Nullable(Int32)) — Instrumentation 트레이스 유형의 경우 elf 바이너리의 xray_instr_map 섹션에서 함수에 할당된 ID예요.
function_name (Nullable(String)) — Instrumentation 트레이스 유형의 경우 계측된 함수의 이름이에요.
handler (Nullable(String)) — Instrumentation 트레이스 유형의 경우 계측된 함수의 핸들러예요.
entry_type (Nullable(Enum8(‘Entry’ = 0, ‘Exit’ = 1))) — Instrumentation 트레이스 유형의 경우 계측된 함수의 항목 유형이에요.
duration_nanoseconds (Nullable(UInt64)) — Instrumentation 트레이스 유형의 경우 함수가 실행된 시간(나노초)이에요.

별칭(Aliases):

build_id — 실행 중인 ClickHouse 서버 바이너리의 빌드 ID 별칭이에요.

심볼화는 서버 구성 파일의 trace_log 아래 symbolize 설정으로 활성화/비활성화할 수 있어요. 기본적으로 활성화되어 있어요. 이 설정은 프로파일러 수집 트레이스 유형에 적용되며, Instrumentation 트레이스 유형의 행은 이와 무관하게 항상 심볼화돼요.

Example

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>>) 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, std::__1::allocator> const&, std::__1::chrono::time_point>>, unsigned long)','DB::logQueryStart(std::__1::chrono::time_point>> const&, std::__1::shared_ptr const&, std::__1::basic_string, std::__1::allocator> const&, unsigned long, std::__1::shared_ptr const&, DB::QueryPipeline const&, DB::IInterpreter const*, bool, std::__1::basic_string, std::__1::allocator> const&, std::__1::basic_string, std::__1::allocator> const&, bool)','DB::executeQueryImpl(char const*, char const*, std::__1::shared_ptr, DB::QueryFlags, DB::QueryProcessingStage::Enum, std::__1::unique_ptr>&, std::__1::shared_ptr&, std::__1::shared_ptr, std::__1::function)','DB::executeQuery(std::__1::basic_string, std::__1::allocator> const&, std::__1::shared_ptr, 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, std::__1::allocator> const&, std::__1::chrono::time_point>>, unsigned long)
handler:                 profile
entry_type:              Exit
duration_nanoseconds:   58435

system.trace_log 시스템 테이블