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

> サンプリングクエリプロファイラによって収集されたスタックトレースを格納するシステムテーブル。

# system.trace_log

<Info>
  **ClickHouse Cloud でのクエリ**

  このシステムテーブルのデータは、ClickHouse Cloud の各ノードにローカルに保持されています。したがって、すべてのデータを完全に把握するには、`clusterAllReplicas` 関数を使用する必要があります。詳細については、[こちら](/ja/reference/system-tables/overview#system-tables-in-clickhouse-cloud)を参照してください。
</Info>

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

[サンプリングクエリプロファイラ](/ja/concepts/features/performance/troubleshoot/sampling-query-profiler) によって収集されたスタックトレースが格納されます。

ClickHouse は、サーバー設定の [trace\_log](/ja/reference/settings/server-settings/settings/other#trace_log) セクションが設定されている場合にこのテーブルを作成します。あわせて次の設定も参照してください: [query\_profiler\_real\_time\_period\_ns](/ja/reference/settings/session-settings/query-profiler#query_profiler_real_time_period_ns), [query\_profiler\_cpu\_time\_period\_ns](/ja/reference/settings/session-settings/query-profiler#query_profiler_cpu_time_period_ns), [memory\_profiler\_step](/ja/reference/settings/session-settings/memory-profiler#memory_profiler_step),
[memory\_profiler\_sample\_probability](/ja/reference/settings/session-settings/memory-profiler#memory_profiler_sample_probability), [trace\_profile\_events](/ja/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` 内のアドレスはサーバー外部で解決する必要があります。

<div id="columns">
  ## カラム
</div>

* `hostname` ([LowCardinality(String)](/ja/reference/data-types/lowcardinality)) — クエリを実行するサーバーのホスト名。
* `event_date` ([Date](/ja/reference/data-types/date)) — サンプリング時点の日付。
* `event_time` ([DateTime](/ja/reference/data-types/datetime)) — サンプリング時点のタイムスタンプ。
* `event_time_microseconds` ([DateTime64(6)](/ja/reference/data-types/datetime64)) — マイクロ秒精度のサンプリング時点を示すタイムスタンプ。
* `timestamp_ns` ([UInt64](/ja/reference/data-types/int-uint)) — サンプリング時点のタイムスタンプ (ナノ秒単位) 。
* `revision` ([UInt32](/ja/reference/data-types/int-uint)) — ClickHouse server のビルドリビジョン。`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)](/ja/reference/data-types/enum)) — トレースの種類: `Real` は、実時間に基づいてスタックトレースを収集することを表します。`CPU` は、CPU 時間に基づいてスタックトレースを収集することを表します。`Memory` は、メモリ割り当てが次のウォーターマークを超えた際に、割り当てと解放を収集することを表します。`MemorySample` は、ランダムな割り当てと解放を収集することを表します。`MemoryPeak` は、ピークメモリ使用量の更新を収集することを表します。`ProfileEvent` は、プロファイルイベントの増分を収集することを表します。`JemallocSample` は、jemalloc サンプルを収集することを表します。`MemoryAllocatedWithoutCheck` は、メモリ制限を一切無視して行われる大規模な割り当て (>16MiB) の収集を表します (ClickHouse 開発者専用) 。`Instrumentation` は、XRay を通じて実行されたインストルメンテーションによって収集されたトレースを表します。
* `cpu_id` ([UInt64](/ja/reference/data-types/int-uint)) — CPUの識別子。
* `thread_id` ([UInt64](/ja/reference/data-types/int-uint)) — スレッドID。
* `thread_name` ([LowCardinality(String)](/ja/reference/data-types/lowcardinality)) — スレッド名。
* `query_id` ([String](/ja/reference/data-types/string)) — `query&#95;log` システムテーブルから実行されていたクエリの詳細を取得するために使用できるクエリ識別子です。
* `trace` ([Array(UInt64)](/ja/reference/data-types/array)) — サンプリング時点のスタックトレース。プロファイラーで収集されたトレースの種類では、FreeBSD を除く ELF プラットフォーム上で、メインの ClickHouse バイナリ内のアドレスは物理ファイルオフセットとして保存され、その他のアドレスは ClickHouseサーバープロセス内の仮想メモリアドレスです。インストルメンテーションのトレース行は例外で、生の仮想メモリアドレスが保存されます。
* `size` ([Int64](/ja/reference/data-types/int-uint)) — トレースの種類が Memory、MemorySample、MemoryAllocatedWithoutCheck、または MemoryPeak の場合は、割り当てられたメモリ量です。それ以外のトレースの種類では 0 です。
* `ptr` ([UInt64](/ja/reference/data-types/int-uint)) — 割り当てられたchunkのアドレスです。
* `memory_context` ([Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)](/ja/reference/data-types/enum)) — Memory Tracker のコンテキスト (Memory/MemoryPeak のみ) : `Unknown` コンテキストは、この `trace&#95;type` では定義されていません。`Global` はサーバー コンテキストを表します。`User` はユーザー/マージ コンテキストを表します。`Process` はプロセス (つまりクエリ) コンテキストを表します。`Thread` はスレッド (特定のプロセスのスレッド) コンテキストを表します。`Max` は特殊な値で、メモリトラッカーがブロックされていないことを示します (`blocked&#95;context` カラム用) 。
* `memory_blocked_context` ([Enum8('Unknown' = -1, 'Global' = 0, 'User' = 1, 'Process' = 2, 'Thread' = 3, 'Max' = 4)](/ja/reference/data-types/enum)) — メモリトラッカーがブロックされているコンテキスト (ClickHouse 開発者向け) : `Unknown` コンテキストはこの trace\_type では定義されていません。`Global` はサーバーコンテキストを表します。`User` はユーザー/merge コンテキストを表します。`Process` はプロセス (つまり `query`) コンテキストを表します。`Thread` はスレッド (特定のプロセスのスレッド) コンテキストを表します。`Max` は特殊な値で、メモリトラッカーがブロックされていないことを意味します (blocked\_context カラム用) 。
* `event` ([LowCardinality(String)](/ja/reference/data-types/lowcardinality)) — トレースタイプが ProfileEvent の場合は更新されたプロファイルイベントの名前、それ以外のトレースタイプでは空文字列です。
* `increment` ([Int64](/ja/reference/data-types/int-uint)) — トレースの種類が ProfileEvent の場合、profile event の増分値です。それ以外のトレースの種類では 0 になります。
* `symbols` ([Array(LowCardinality(String))](/ja/reference/data-types/array)) — シンボル化が有効な場合、`trace` に対応するデマングル済みのシンボル名が含まれます。シンボル化の有効/無効は、サーバー設定ファイルの `trace_log` 内にある `symbolize` 設定で切り替えられます。この設定はプロファイラーで収集されたトレースタイプに適用されますが、`Instrumentation` トレースタイプの行はこの設定に関係なくシンボル化されます。シンボル化は ELF プラットフォーム (Linux など) および macOS でサポートされます。FreeBSD では、このカラムは常に空です。
* `lines` ([Array(LowCardinality(String))](/ja/reference/data-types/array)) — シンボル化が有効な場合、`trace` に対応する、行番号付きのファイル名を表す文字列が格納されます。`symbolize` 設定はプロファイラーで収集されたトレースタイプに適用されますが、`Instrumentation` トレースタイプの行はこの設定に関係なくシンボル化されます。シンボル化は ELF プラットフォーム (Linux など) および macOS でサポートされます。FreeBSD では、このカラムは常に空です。ソース位置情報はベストエフォートです。デバッグ情報 (macOS では `.dSYM` バンドル) が必要であり、ELF プラットフォームではメインの ClickHouse バイナリ内のフレームについてのみ解決されます。解決されないフレームには空のエントリが含まれます。
* `function_id` ([Nullable(Int32)](/ja/reference/data-types/nullable)) — trace 型が Instrumentation の場合、ELF バイナリの xray\_instr\_map セクション内の関数に割り当てられる ID。
* `function_name` ([Nullable(String)](/ja/reference/data-types/nullable)) — トレースタイプが Instrumentation の場合、インストルメントされた関数名。
* `handler` ([Nullable(String)](/ja/reference/data-types/nullable)) — trace 型の Instrumentation では、インストルメントされた関数のハンドラー。
* `entry_type` ([Nullable(Enum8('Entry' = 0, 'Exit' = 1))](/ja/reference/data-types/nullable)) — トレース型の Instrumentation の場合、インストルメントされた関数のエントリタイプ。
* `duration_nanoseconds` ([Nullable(UInt64)](/ja/reference/data-types/nullable)) — トレース型の Instrumentation において、関数が実行されていた時間をナノ秒単位で表します。

**別名:**

* `build_id` — 実行中の ClickHouse server バイナリの build ID の別名。

シンボル化は、server's configuration file の `trace_log` にある `symbolize` 設定で有効または無効にできます。デフォルトでは有効です。この設定は、プロファイラによって収集されたトレースタイプに適用されます。`Instrumentation` トレースタイプの行は、この設定にかかわらずシンボル化されます。

<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 -- 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
```

<div id="chrome-event-trace-format">
  ## Chrome Event Trace Format への変換
</div>

プロファイリングデータは、次のクエリで 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
```

より簡潔で情報量の少ないトレースにしたい場合は、stack の部分を省略できます。

<div id="see-also">
  ## 関連項目
</div>

* [SYSTEM INSTRUMENT](/ja/reference/statements/system#instrument) — インストルメンテーションポイントを追加または削除します。
* [system.instrumentation](/ja/reference/system-tables/instrumentation) — インストルメント済みのポイントを確認します。
* [system.symbols](/ja/reference/system-tables/symbols) — インストルメンテーションポイントを追加するためのシンボルを確認します。