Skip to main content
ClickHouse Cloud でのクエリこのシステムテーブルのデータは、ClickHouse Cloud の各ノードにローカルに保持されています。したがって、すべてのデータを完全に把握するには、clusterAllReplicas 関数を使用する必要があります。詳細については、こちらを参照してください。

説明

サンプリングクエリプロファイラ によって収集されたスタックトレースが格納されます。 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 のソース位置はベストエフォートであり、デバッグ情報 (macOS では .dSYM バンドル) が必要です。また、ELF プラットフォームではメインの ClickHouse バイナリ内のフレームについてのみ解決されます。解決できないフレームの lines エントリは空になります。 シンボル化が無効になっている場合、または trace カラム内の生のアドレスをオンデマンドで解決したい場合 (たとえば、インラインフレームを展開するため) は、addressToLineaddressToLineWithInlinesaddressToSymbol、および demangle イントロスペクション関数を使用します。これらの関数は、シンボル化と同じプラットフォーム (Linux などの ELF プラットフォームおよび macOS) で利用できます。FreeBSD ではこれらもコンパイルされていないため、trace 内のアドレスはサーバー外部で解決する必要があります。

カラム

  • hostname (LowCardinality(String)) — クエリを実行するサーバーのホスト名。
  • event_date (Date) — サンプリング時点の日付。
  • event_time (DateTime) — サンプリング時点のタイムスタンプ。
  • event_time_microseconds (DateTime64(6)) — マイクロ秒精度のサンプリング時点を示すタイムスタンプ。
  • timestamp_ns (UInt64) — サンプリング時点のタイムスタンプ (ナノ秒単位) 。
  • revision (UInt32) — 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)) — トレースの種類: Real は、実時間に基づいてスタックトレースを収集することを表します。CPU は、CPU 時間に基づいてスタックトレースを収集することを表します。Memory は、メモリ割り当てが次のウォーターマークを超えた際に、割り当てと解放を収集することを表します。MemorySample は、ランダムな割り当てと解放を収集することを表します。MemoryPeak は、ピークメモリ使用量の更新を収集することを表します。ProfileEvent は、プロファイルイベントの増分を収集することを表します。JemallocSample は、jemalloc サンプルを収集することを表します。MemoryAllocatedWithoutCheck は、メモリ制限を一切無視して行われる大規模な割り当て (>16MiB) の収集を表します (ClickHouse 開発者専用) 。Instrumentation は、XRay を通じて実行されたインストルメンテーションによって収集されたトレースを表します。
  • cpu_id (UInt64) — CPUの識別子。
  • thread_id (UInt64) — スレッドID。
  • thread_name (LowCardinality(String)) — スレッド名。
  • query_id (String) — query_log システムテーブルから実行されていたクエリの詳細を取得するために使用できるクエリ識別子です。
  • trace (Array(UInt64)) — サンプリング時点のスタックトレース。プロファイラーで収集されたトレースの種類では、FreeBSD を除く ELF プラットフォーム上で、メインの ClickHouse バイナリ内のアドレスは物理ファイルオフセットとして保存され、その他のアドレスは ClickHouseサーバープロセス内の仮想メモリアドレスです。インストルメンテーションのトレース行は例外で、生の仮想メモリアドレスが保存されます。
  • size (Int64) — トレースの種類が Memory、MemorySample、MemoryAllocatedWithoutCheck、または MemoryPeak の場合は、割り当てられたメモリ量です。それ以外のトレースの種類では 0 です。
  • ptr (UInt64) — 割り当てられたchunkのアドレスです。
  • memory_context (Enum8(‘Unknown’ = -1, ‘Global’ = 0, ‘User’ = 1, ‘Process’ = 2, ‘Thread’ = 3, ‘Max’ = 4)) — Memory Tracker のコンテキスト (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 はユーザー/merge コンテキストを表します。Process はプロセス (つまり query) コンテキストを表します。Thread はスレッド (特定のプロセスのスレッド) コンテキストを表します。Max は特殊な値で、メモリトラッカーがブロックされていないことを意味します (blocked_context カラム用) 。
  • event (LowCardinality(String)) — トレースタイプが ProfileEvent の場合は更新されたプロファイルイベントの名前、それ以外のトレースタイプでは空文字列です。
  • increment (Int64) — トレースの種類が ProfileEvent の場合、profile event の増分値です。それ以外のトレースの種類では 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)) — trace 型が Instrumentation の場合、ELF バイナリの xray_instr_map セクション内の関数に割り当てられる ID。
  • function_name (Nullable(String)) — トレースタイプが Instrumentation の場合、インストルメントされた関数名。
  • handler (Nullable(String)) — trace 型の Instrumentation では、インストルメントされた関数のハンドラー。
  • entry_type (Nullable(Enum8(‘Entry’ = 0, ‘Exit’ = 1))) — トレース型の Instrumentation の場合、インストルメントされた関数のエントリタイプ。
  • duration_nanoseconds (Nullable(UInt64)) — トレース型の Instrumentation において、関数が実行されていた時間をナノ秒単位で表します。
別名:
  • build_id — 実行中の ClickHouse server バイナリの build ID の別名。
シンボル化は、server’s configuration file の trace_log にある symbolize 設定で有効または無効にできます。デフォルトでは有効です。この設定は、プロファイラによって収集されたトレースタイプに適用されます。Instrumentation トレースタイプの行は、この設定にかかわらずシンボル化されます。

Chrome Event Trace Format への変換

プロファイリングデータは、次のクエリで Chrome の Event Trace Format に変換できます。クエリは chrome_trace.sql ファイルとして保存してください。
そして、これを ClickHouse Client で実行して trace.json ファイルにエクスポートすれば、そのファイルを Perfetto または speedscope にインポートできます。
より簡潔で情報量の少ないトレースにしたい場合は、stack の部分を省略できます。

関連項目

  • SYSTEM INSTRUMENT — インストルメンテーションポイントを追加または削除します。
  • system.instrumentation — インストルメント済みのポイントを確認します。
  • system.symbols — インストルメンテーションポイントを追加するためのシンボルを確認します。
最終更新日 2026年8月14日