> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 샘플링 쿼리 프로파일러와 trace_type 컬럼에 명시된 다른 소스가 수집한 스택 트레이스를 담고 있는 시스템 테이블입니다.

# system.trace_log

<Info>
  **ClickHouse Cloud에서 쿼리하기**

  이 시스템 테이블의 데이터는 ClickHouse Cloud의 각 노드에 로컬로 저장됩니다. 따라서 전체 데이터를 모두 확인하려면 `clusterAllReplicas` 함수를 사용해야 합니다. 자세한 내용은 [여기](/ko/reference/system-tables/overview#system-tables-in-clickhouse-cloud)를 참조하십시오.
</Info>

## 설명

[샘플링 쿼리 프로파일러](/ko/concepts/features/performance/troubleshoot/sampling-query-profiler)와 `trace_type` 컬럼에 명시된 기타 소스에서 수집된 스택 트레이스를 포함합니다.

서버 구성의 [trace\_log](/ko/reference/settings/server-settings/settings/other#trace_log) 섹션이 설정되어 있으면 ClickHouse가 이 테이블을 생성합니다. 다음 설정도 참조하십시오: [query\_profiler\_real\_time\_period\_ns](/ko/reference/settings/session-settings/query-profiler#query_profiler_real_time_period_ns), [query\_profiler\_cpu\_time\_period\_ns](/ko/reference/settings/session-settings/query-profiler#query_profiler_cpu_time_period_ns), [memory\_profiler\_step](/ko/reference/settings/session-settings/memory-profiler#memory_profiler_step),
[memory\_profiler\_sample\_probability](/ko/reference/settings/session-settings/memory-profiler#memory_profiler_sample_probability), [trace\_profile\_events](/ko/reference/settings/session-settings/trace-profile-events#trace_profile_events).

심볼화가 활성화되어 있으면(기본값) 디맹글된 함수 이름과 소스 위치가 이미 `symbols` 및 `lines` 컬럼에 제공되므로 인트로스펙션 함수 없이 로그를 직접 분석할 수 있습니다. `symbolize` 설정은 프로파일러가 수집한 트레이스 유형에 적용되지만, `Instrumentation` 트레이스 유형의 행은 이 설정과 관계없이 심볼화됩니다. 심볼화는 ELF 플랫폼(예: Linux) 및 macOS에서 지원됩니다. FreeBSD에서는 `symbols` 및 `lines` 컬럼이 항상 비어 있습니다. `symbols`의 함수 이름은 바이너리의 심볼 테이블에서 가져오며 기본적으로 사용할 수 있습니다. 반면 `lines`의 소스 위치는 가능한 범위에서 제공됩니다. 이를 위해 디버그 정보(macOS에서는 `.dSYM` 번들)가 필요하며, ELF 플랫폼에서는 기본 ClickHouse 바이너리 내부의 프레임에 대해서만 해석됩니다. 해석되지 않은 프레임의 `lines` 항목은 비어 있습니다.
심볼화가 비활성화되어 있거나 `trace` 컬럼의 원시 주소를 동적으로 해석하려는 경우(예: 인라인 프레임 확장) `addressToLine`, `addressToLineWithInlines`, `addressToSymbol`, `demangle` 인트로스펙션 함수를 사용하십시오. 이 함수들은 심볼화와 동일한 플랫폼(예: Linux 등의 ELF 플랫폼 및 macOS)에서 사용할 수 있습니다. FreeBSD에서는 이 함수들도 컴파일되지 않으므로 `trace`의 주소를 서버 외부에서 해석해야 합니다.

## Chrome Event Trace Format으로 변환

프로파일링 데이터는 다음 쿼리로 Chrome의 Event Trace Format으로 변환할 수 있습니다. 이 쿼리를 `chrome_trace.sql` 파일에 저장하십시오:

```sql theme={null}
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](https://ui.perfetto.dev/) 또는 [speedscope](https://www.speedscope.app/)로 가져올 수 있습니다.

```bash theme={null}
echo $(clickhouse client --query "$(cat chrome_trace.sql)") > trace.json
```

더 간결하지만 정보량은 적은 트레이스를 원한다면 스택 부분은 생략할 수 있습니다.

이 테이블은 언제든지 TRUNCATE하거나 삭제해도 안전합니다.

## 컬럼

* `hostname` ([LowCardinality(String)](/ko/reference/data-types/lowcardinality)) — 쿼리를 실행하는 서버의 호스트명입니다.
* `clickhouse_version` ([LowCardinality(String)](/ko/reference/data-types/lowcardinality)) — 행을 생성한 ClickHouse 서버의 버전입니다.
* `system_processor` ([LowCardinality(String)](/ko/reference/data-types/lowcardinality)) — 행을 생성한 ClickHouse 서버의 CPU 아키텍처입니다.
* `event_date` ([Date](/ko/reference/data-types/date)) — 샘플링 시점의 날짜입니다.
* `event_time` ([DateTime](/ko/reference/data-types/datetime)) — 샘플링 시점의 타임스탬프.
* `event_time_microseconds` ([DateTime64(6)](/ko/reference/data-types/datetime64)) — 마이크로초 단위 정밀도를 가진 샘플링 시점의 타임스탬프입니다.
* `timestamp_ns` ([UInt64](/ko/reference/data-types/int-uint)) — 나노초 단위로 기록된 샘플링 시점의 타임스탬프입니다.
* `revision` ([UInt32](/ko/reference/data-types/int-uint)) — ClickHouse 서버의 빌드 리비전입니다. `clickhouse-client`로 서버에 연결하면 `Connected to ClickHouse server version 19.18.1.`와 유사한 문자열이 표시됩니다. 이 필드에는 서버의 `version`이 아니라 `revision`이 들어 있습니다.
* `trace_type` ([Enum8('Real' = 0, 'CPU' = 1, 'Memory' = 2, 'MemorySample' = 3, 'MemoryPeak' = 4, 'ProfileEvent' = 5, 'JemallocSample' = 6, 'MemoryAllocatedWithoutCheck' = 7, 'Instrumentation' = 8, 'MemoryLargeAllocation' = 9)](/ko/reference/data-types/enum)) — 트레이스 유형: `Real`은 실제 경과 시간을 기준으로 스택 트레이스를 수집함을 나타냅니다. `CPU`는 CPU 시간을 기준으로 스택 트레이스를 수집함을 나타냅니다. `Memory`는 메모리 할당이 다음 워터마크를 초과할 때 메모리 할당 및 해제를 수집함을 나타냅니다. `MemorySample`은 임의의 메모리 할당 및 해제를 수집함을 나타냅니다. `MemoryPeak`은 최대 메모리 사용량 업데이트를 수집함을 나타냅니다. `ProfileEvent`는 profile events 증가분을 수집함을 나타냅니다. `JemallocSample`은 jemalloc 샘플을 수집함을 나타냅니다. `MemoryAllocatedWithoutCheck`는 메모리 제한을 무시하고 수행되는 대규모 할당(>16MiB)을 수집함을 나타냅니다(ClickHouse 개발자 전용). `Instrumentation`은 XRay를 통해 수행된 계측으로 수집된 traces를 나타냅니다. `MemoryLargeAllocation`은 크기가 `min_allocation_size_to_log_stack_trace`에 도달한 전역 메모리 추적기에 대한 단일 청구를 나타내며, 이러한 trace는 서버 로그에도 기록됩니다(ClickHouse 개발자 전용).
* `cpu_id` ([UInt64](/ko/reference/data-types/int-uint)) — CPU 식별자.
* `thread_id` ([UInt64](/ko/reference/data-types/int-uint)) — 스레드 ID.
* `thread_name` ([LowCardinality(String)](/ko/reference/data-types/lowcardinality)) — 스레드 이름입니다.
* `query_id` ([String](/ko/reference/data-types/string)) — query\_log 시스템 테이블(system table)에서 실행 중이던 쿼리의 세부 정보를 조회하는 데 사용할 수 있는 쿼리 식별자입니다.
* `trace` ([Array(UInt64)](/ko/reference/data-types/array)) — 샘플링 시점의 스택 트레이스입니다. 프로파일러가 수집한 trace 타입의 경우 FreeBSD를 제외한 ELF 플랫폼에서는 기본 ClickHouse 바이너리 내 주소가 물리적 파일 오프셋으로 저장되며, 다른 주소는 ClickHouse 서버 프로세스 내의 가상 메모리 주소입니다. Instrumentation trace 행은 예외로, 원시 가상 메모리 주소를 저장합니다.
* `size` ([Int64](/ko/reference/data-types/int-uint)) — 메모리 관련 trace 타입에서는 바이트 단위 크기입니다. Memory와 MemoryAllocatedWithoutCheck에서는 할당된 크기이고, MemorySample과 JemallocSample에서는 할당된 크기이되 메모리 할당 해제 시에는 음수로 표시되며, MemoryPeak에서는 추적기의 새로운 최대값이고, MemoryLargeAllocation에서는 전역 메모리 추적기에 청구된 크기입니다. 다른 trace 타입에서는 0입니다.
* `ptr` ([UInt64](/ko/reference/data-types/int-uint)) — 할당된 청크의 주소입니다.
* `memory_context` ([Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)](/ko/reference/data-types/enum)) — 메모리 트래커 컨텍스트(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)](/ko/reference/data-types/enum)) — 메모리 추적기(memory tracker)가 차단되는 컨텍스트입니다(ClickHouse 개발자 전용): `Unknown` 컨텍스트는 이 trace\_type에 대해 정의되어 있지 않습니다. `Global`은 서버 컨텍스트를 나타냅니다. `User`는 사용자/머지 컨텍스트를 나타냅니다. `Process`는 프로세스(즉, 쿼리) 컨텍스트를 나타냅니다. `Thread`는 스레드(특정 프로세스의 스레드) 컨텍스트를 나타냅니다. `Max`는 메모리 추적기가 차단되지 않음을 의미하는 특수 값입니다(blocked\_context 컬럼용).
* `event` ([LowCardinality(String)](/ko/reference/data-types/lowcardinality)) — trace 타입이 ProfileEvent인 경우 업데이트된 프로파일 이벤트 이름이며, 다른 trace 타입인 경우 빈 문자열입니다.
* `increment` ([Int64](/ko/reference/data-types/int-uint)) — trace 유형이 ProfileEvent일 때는 프로파일 이벤트의 증가량이고, 다른 trace 유형에서는 0입니다.
* `symbols` ([Array(LowCardinality(String))](/ko/reference/data-types/array)) — 심볼화가 활성화된 경우 `trace`에 대응하는 디맹글링된 심볼 이름을 포함합니다. 심볼화는 서버 설정 파일의 `trace_log` 아래 `symbolize` 설정에서 활성화하거나 비활성화할 수 있으며, 이 설정은 프로파일러가 수집한 trace 유형에 적용됩니다. 반면 `Instrumentation` trace 유형의 행은 이 설정과 관계없이 심볼화됩니다. 심볼화는 ELF 플랫폼(예: Linux)과 macOS에서 지원되며, FreeBSD에서는 이 컬럼이 항상 비어 있습니다.
* `lines` ([Array(LowCardinality(String))](/ko/reference/data-types/array)) — 심볼화가 활성화되어 있으면 `trace`에 대응하는 파일 이름과 줄 번호가 포함된 문자열을 담습니다. `symbolize` 설정은 프로파일러가 수집한 trace 유형에 적용되며, `Instrumentation` trace 유형의 행은 이 설정과 관계없이 심볼화됩니다. 심볼화는 ELF 플랫폼(예: Linux)과 macOS에서 지원되며, FreeBSD에서는 이 컬럼이 항상 비어 있습니다. 소스 위치는 최선의 노력으로 제공됩니다. 이를 위해서는 디버그 정보(macOS에서는 `.dSYM` 번들)가 필요하며, ELF 플랫폼에서는 기본 ClickHouse binary 내부의 프레임에 대해서만 해석됩니다. 해석되지 않은 프레임에는 빈 항목이 있습니다.
* `function_id` ([Nullable(Int32)](/ko/reference/data-types/nullable)) — trace 타입 Instrumentation에서 elf-binary의 xray\_instr\_map 섹션에 있는 함수에 할당된 ID입니다.
* `function_name` ([Nullable(String)](/ko/reference/data-types/nullable)) — trace 유형 Instrumentation에서 계측된 함수의 이름입니다.
* `handler` ([Nullable(String)](/ko/reference/data-types/nullable)) — trace 유형 Instrumentation에서 계측된 함수의 handler입니다.
* `entry_type` ([Nullable(Enum8('Entry' = 0, 'Exit' = 1))](/ko/reference/data-types/nullable)) — trace 타입이 Instrumentation인 경우, 계측된 함수의 진입 유형입니다.
* `duration_nanoseconds` ([Nullable(UInt64)](/ko/reference/data-types/nullable)) — trace 타입의 Instrumentation에서 함수가 실행된 시간을 나노초 단위로 나타냅니다.

**별칭:**

* `build_id` — 실행 중인 ClickHouse 서버 바이너리의 build ID를 나타내는 별칭입니다.

서버의 설정 파일에서 `trace_log` 아래에 있는 `symbolize` 설정으로 심볼화를 활성화하거나 비활성화할 수 있습니다. 기본적으로 활성화되어 있습니다. 이 설정은 프로파일러가 수집한 트레이스 유형에 적용되지만, `Instrumentation` 트레이스 유형의 행은 이 설정과 관계없이 심볼화됩니다.

## 예시

```sql theme={null}
SELECT * FROM system.trace_log LIMIT 1 \G
```

```text theme={null}
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
```

## 관련 항목

* [SYSTEM INSTRUMENT](/ko/reference/statements/system#instrument) — 계측 지점을 추가하거나 제거합니다.
* [system.instrumentation](/ko/reference/system-tables/instrumentation) — 계측이 적용된 지점을 확인합니다.
* [system.symbols](/ko/reference/system-tables/symbols) — 계측 지점을 추가할 수 있는 심볼을 확인합니다.