> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 包含由采样查询分析器收集的堆栈跟踪的系统表

# system.trace_log

<Info>
  **在 ClickHouse Cloud 中查询**

  此系统表中的数据分别保存在 ClickHouse Cloud 各节点的本地。因此，如需查看所有数据的完整情况，需要使用 `clusterAllReplicas` 函数。更多详情请参见[此处](/zh/reference/system-tables/overview#system-tables-in-clickhouse-cloud)。
</Info>

<div id="description">
  ## 说明
</div>

包含由[采样查询分析器](/zh/concepts/features/performance/troubleshoot/sampling-query-profiler)收集的堆栈跟踪。

当服务器配置中的 [trace\_log](/zh/reference/settings/server-settings/settings#trace_log) 部分启用时，ClickHouse 会创建此表。另请参见以下设置：[query\_profiler\_real\_time\_period\_ns](/zh/reference/settings/session-settings#query_profiler_real_time_period_ns)、[query\_profiler\_cpu\_time\_period\_ns](/zh/reference/settings/session-settings#query_profiler_cpu_time_period_ns)、[memory\_profiler\_step](/zh/reference/settings/session-settings#memory_profiler_step)、
[memory\_profiler\_sample\_probability](/zh/reference/settings/session-settings#memory_profiler_sample_probability)、[trace\_profile\_events](/zh/reference/settings/session-settings#trace_profile_events)。

要分析日志，请使用 `addressToLine`、`addressToLineWithInlines`、`addressToSymbol` 和 `demangle` 这些内部信息函数。

<div id="columns">
  ## 列
</div>

* `hostname` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 执行该查询的服务器主机名。
* `event_date` ([Date](/zh/reference/data-types/date)) — 采样时刻的日期。
* `event_time` ([DateTime](/zh/reference/data-types/datetime)) — 采样时间点的时间戳。
* `event_time_microseconds` ([DateTime64(6)](/zh/reference/data-types/datetime64)) — 具有微秒精度的采样时刻时间戳。
* `timestamp_ns` ([UInt64](/zh/reference/data-types/int-uint)) — 采样时刻的时间戳 (以纳秒为单位) 。
* `revision` ([UInt32](/zh/reference/data-types/int-uint)) — 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)](/zh/reference/data-types/enum)) — trace 类型：`Real` 表示按 `挂钟时间` 收集堆栈跟踪。`CPU` 表示按 CPU 时间收集堆栈跟踪。`Memory` 表示当内存分配超过相应的 watermark 时，收集分配和释放。`MemorySample` 表示收集随机分配和释放。`MemoryPeak` 表示收集峰值内存占用的更新信息。`ProfileEvent` 表示收集 profile events 的增量。`JemallocSample` 表示收集 jemalloc 样本。`MemoryAllocatedWithoutCheck` 表示收集忽略任何内存限制时发生的大额分配 (>16MiB)  (仅适用于 ClickHouse 开发者) 。`Instrumentation` 表示通过 XRay 插桩收集的 trace。
* `cpu_id` ([UInt64](/zh/reference/data-types/int-uint)) — CPU 编号。
* `thread_id` ([UInt64](/zh/reference/data-types/int-uint)) — 线程标识符。
* `thread_name` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 线程名。
* `query_id` ([String](/zh/reference/data-types/string)) — 查询标识符，可用于从 query\_log 系统表中获取正在运行查询的详细信息。
* `trace` ([Array(UInt64)](/zh/reference/data-types/array)) — 采样时的堆栈跟踪。每个元素都是 ClickHouse server 进程中的一个虚拟内存地址。
* `size` ([Int64](/zh/reference/data-types/int-uint)) — 对于 Memory、MemorySample、MemoryAllocatedWithoutCheck 或 MemoryPeak 这几种 trace 类型，表示已分配的内存量；对于其他 trace 类型，则为 0。
* `ptr` ([UInt64](/zh/reference/data-types/int-uint)) — 已分配 chunk 的内存地址。
* `memory_context` ([Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)](/zh/reference/data-types/enum)) — Memory Tracker 的上下文 (仅适用于 Memory/MemoryPeak) ：`Unknown` 表示此 trace\_type 未定义上下文。`Global` 表示服务器上下文。`User` 表示用户/合并上下文。`Process` 表示进程 (即查询) 上下文。`Thread` 表示线程 (特定进程的线程) 上下文。`Max` 是一个特殊值，表示 memory tracker 未被阻塞 (仅针对 `blocked&#95;context` 列) 。
* `memory_blocked_context` ([Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)](/zh/reference/data-types/enum)) — memory tracker 被阻塞时对应的上下文 (仅供 ClickHouse 开发者使用) ：`Unknown` 表示该 `trace&#95;type` 未定义上下文。`Global` 表示服务器上下文。`User` 表示用户/merge 上下文。`Process` 表示进程 (即查询) 上下文。`Thread` 表示线程 (特定进程的线程) 上下文。`Max` 是一个特殊值，表示 memory tracker 未被阻塞 (针对 `blocked&#95;context` 列) 。
* `event` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 对于 trace 类型，ProfileEvent 是已更新的 profile 事件名称；对于其他 trace 类型，则为空字符串。
* `increment` ([Int64](/zh/reference/data-types/int-uint)) — 当 trace 类型为 ProfileEvent 时，表示该 profile event 的增量；其他 trace 类型则为 0。
* `symbols` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 如果启用了符号化，则包含与 `trace` 对应的已解修饰符号名称。可在服务器配置文件中 `trace_log` 下的 `symbolize` 设置里启用或禁用符号化。
* `lines` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 如果启用了符号化，则包含带行号的文件名字符串，并与 `trace` 相对应。
* `function_id` ([Nullable(Int32)](/zh/reference/data-types/nullable)) — 对于 trace 类型的 Instrumentation，表示在 elf-binary 的 xray\_instr\_map 节中分配给该函数的 ID。
* `function_name` ([Nullable(String)](/zh/reference/data-types/nullable)) — 对于 trace 类型的 Instrumentation，表示被插桩函数的名称。
* `handler` ([Nullable(String)](/zh/reference/data-types/nullable)) — 对于 trace 类型的 Instrumentation，表示已插桩函数的处理器。
* `entry_type` ([Nullable(Enum8('Entry' = 0, 'Exit' = 1))](/zh/reference/data-types/nullable)) — 对于 trace 类型 Instrumentation，表示插桩函数的进入/退出类型。
* `duration_nanoseconds` ([Nullable(UInt64)](/zh/reference/data-types/nullable)) — 对于 trace 类型的 Instrumentation，表示函数运行时间，单位为纳秒。

**别名：**

* `build_id` — `'E2EEB60ED9503BFFA825B628D480CCDC40B2D416'` 的别名。

可以在服务器的配置文件中，通过 `trace_log` 下的 `symbolize` 启用或禁用符号化。

<div id="example">
  ## 示例
</div>

```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 -- 317万
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','/home/ubuntu/ClickHouse/ClickHouse/build/programs/clickhouse','./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','/home/ubuntu/ClickHouse/ClickHouse/build/programs/clickhouse','/home/ubuntu/ClickHouse/ClickHouse/build/programs/clickhouse']
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
```

<div id="chrome-event-trace-format">
  ## 转换为 Chrome Event Trace Format
</div>

可使用以下查询将 profiling 数据转换为 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 命令行客户端执行该命令，将结果导出为 `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
```

如果希望 trace 更紧凑、但包含的信息更少，我们可以省略堆栈部分。

<div id="see-also">
  ## 另请参阅
</div>

* [SYSTEM INSTRUMENT](/zh/reference/statements/system#instrument) — 添加或移除插桩点。
* [system.instrumentation](/zh/reference/system-tables/instrumentation) — 查看已插桩的点。
* [system.symbols](/zh/reference/system-tables/symbols) — 查看可用于添加插桩点的符号。