サンプリングクエリプロファイラ

ClickHouse のサンプリングクエリプロファイラツールに関するドキュメント

ClickHouse では、クエリ実行を分析するためのサンプリングプロファイラが動作します。 このプロファイラを使用すると、クエリ実行中に最も高頻度で使われているソースコード上のルーチンを特定できます。 アイドル時間を含む CPU 時間と実時間を追跡できます。

ClickHouse Cloud では、クエリプロファイラは自動的に有効になります。 次のクエリ例では、関数名とソースコード上の位置を解決したうえで、プロファイル対象のクエリで最も頻出するスタックトレースを特定します。

デフォルトでは、プロファイラは収集時にスタックトレースをシンボル化し、結果を system.trace_log の symbols および lines カラムに保存します。そのため、以下の例ではこれらのカラムを直接読み取り、イントロスペクション関数は必要ありません。シンボル化は trace_log サーバー設定セクションの symbolize 設定によって制御されます (デフォルトで有効)。ELF プラットフォーム (Linux など) および macOS でサポートされています。FreeBSD では symbols および lines カラムは常に空です。symbols 内の関数名はバイナリのシンボルテーブルから取得され、デフォルトで利用できます。lines 内のソースコード上の位置はベストエフォートで提供されます。デバッグ情報が必要であり (macOS ではバイナリの隣にある .dSYM バンドル)、ELF プラットフォームではメインの ClickHouse バイナリ内のフレームのみが解決されるため、解決できないフレーム (共有ライブラリ内のフレームなど) のエントリは空のままとなります。シンボル化が無効な場合は、trace カラム内の生のアドレスを解決するために、addressToSymbol、demangle、addressToLine のイントロスペクション関数を使用してください。これらの関数はシンボル化と同じプラットフォーム (Linux などの ELF プラットフォームおよび macOS) で利用できます。FreeBSD ではこれらもコンパイルされていないため、trace 内のアドレスはサーバー外部で解決する必要があります。

query_id の値は、プロファイルしたいクエリの ID に置き換えてください。

ClickHouse Cloud

ClickHouse Cloud では、クエリ結果テーブルの上にあるバーの右端 (テーブル/チャート切り替えの横) の ”…” をクリックすると、クエリ ID を取得できます。コンテキストメニューが開くので、“Copy query ID” をクリックしてください。

クラスター内のすべてのノードから選択するには、clusterAllReplicas(default, system.trace_log) を使用します。

SELECT
    count(),
    arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\n') AS sym
FROM clusterAllReplicas(default, system.trace_log)
WHERE query_id = '<query_id>' AND trace_type = 'CPU' AND event_date = today()
GROUP BY trace
ORDER BY count() DESC
LIMIT 10

セルフマネージド

SELECT
    count(),
    arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\n') AS sym
FROM system.trace_log
WHERE query_id = '<query_id>' AND trace_type = 'CPU' AND event_date = today()
GROUP BY trace
ORDER BY count() DESC
LIMIT 10

​

セルフマネージド環境でクエリプロファイラを使用する

セルフマネージド環境でクエリプロファイラを使用するには、以下の手順に従ってください。

1. デバッグ情報付きの ClickHouse をインストールする

   clickhouse-common-static-dbg パッケージをインストールします。

   1. 手順「Debian リポジトリをセットアップする」の説明に従います
   2. sudo apt-get install clickhouse-server clickhouse-client clickhouse-common-static-dbg を実行して、デバッグ情報付きでコンパイルされた ClickHouse のバイナリをインストールします
   3. sudo service clickhouse-server start を実行してサーバーを起動します
   4. clickhouse-client を実行します。clickhouse-common-static-dbg のデバッグシンボルはサーバーで自動的に使用されるため、有効化のために特別な操作は必要ありません
2. サーバー設定を確認する

   サーバー設定ファイルの trace_log セクションが設定されていることを確認してください。これはデフォルトで有効です。

   <!-- Trace log. Stores stack traces collected by query profilers.
        See query_profiler_real_time_period_ns and query_profiler_cpu_time_period_ns settings. -->
   <trace_log>
       <database>system</database>
       <table>trace_log</table>
   
       <partition_by>toYYYYMM(event_date)</partition_by>
       <flush_interval_milliseconds>7500</flush_interval_milliseconds>
       <max_size_rows>1048576</max_size_rows>
       <reserved_size_rows>8192</reserved_size_rows>
       <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
       <!-- Indication whether logs should be dumped to the disk in case of a crash -->
       <flush_on_crash>false</flush_on_crash>
       <symbolize>true</symbolize>
   </trace_log>
   

   このセクションでは、プロファイラの動作結果を含む trace_log システムテーブルを設定します。 デフォルトで有効な symbolize オプションを指定すると、ClickHouse は収集時に各スタックフレームを解決し、デマングルされた関数名とソースコード上の位置を symbols および lines カラムに保存します。 symbols の関数名はシンボルテーブルから取得され、デフォルトで利用できます。一方、lines のソースコード上の位置にはデバッグ情報 (macOS では .dSYM バンドル) が必要です。ELF プラットフォームでは、メインの ClickHouse バイナリ内のフレームに対してのみ解決され、解決できないフレームの lines エントリは空になります。

   trace カラム内の生のアドレスは、あらかじめシンボル化されたカラムに比べて、再起動やアップグレードをまたいだ安定性が低い点に注意してください。 FreeBSD を除く ELF プラットフォームでは、メインの ClickHouse バイナリ内のフレームは物理ファイルオフセットとして保存されるため、バイナリが変更されない限り、再起動後も解決可能です。一方、macOS および FreeBSD では、再起動後に無効になる可能性がある実行時仮想アドレスとして保存されます。 メインバイナリ外のフレーム (たとえば共有ライブラリ内のフレーム) は常に実行時仮想アドレスとして保存され、再起動後に無効になる可能性があります。また、コードレイアウトが変わるため、バイナリのアップグレード後はすべての生のアドレスを解決できなくなります。 ClickHouse は再起動時にテーブルをクリーンアップしないため、古い生のアドレスが残る場合があります。 一方、あらかじめシンボル化された symbols および lines カラムは、再起動やアップグレード後も有効なままであるため、履歴データを分析する際はこれらを優先してください。

3. プロファイラのタイマーを設定する

   query_profiler_cpu_time_period_ns または query_profiler_real_time_period_ns を設定します。 これら 2 つの設定は同時に使用できます。

   これらの設定により、プロファイラのタイマーを構成できます。 これらはセッション設定であるため、サーバー全体、個々のユーザーやユーザープロファイル、対話セッション、さらには個々のクエリごとに異なるサンプリング頻度を設定できます。

   デフォルトのサンプリング頻度は 1 秒あたり 1 サンプルで、CPU タイマーと実時間タイマーの両方が有効になっています。 この頻度であれば、サーバーのパフォーマンスに影響を与えずに、ClickHouse クラスターに関する十分な情報を収集できます。 個々のクエリごとにプロファイルを取得する必要がある場合は、より高いサンプリング頻度を使用してください。

4. `trace_log` システムテーブルを分析する

   特定のクエリのプロファイルを取得するには、trace_log テーブルのデータを集計する必要があります。 データは個々の関数単位でも、スタックトレース全体単位でも集計できます。

   シンボル化が有効な場合 (デフォルト) 、復元された関数名とソースコード内の位置はすでに symbols および lines カラムで利用できるため、追加のセットアップは必要ありません。FreeBSD ではシンボル化はサポートされておらず、これらのカラムは常に空です。デバッグ情報がないフレームや、メインの ClickHouse バイナリの範囲外にあるフレームでは、lines エントリが空になる場合があります (上記を参照) 。

   シンボル化が無効になっている場合、または trace カラム内の生のアドレスをオンザフライで解決する場合 (たとえば、インラインフレームを展開するため) は、allow_introspection_functions 設定でイントロスペクション関数を有効にします。

   SET allow_introspection_functions=1
   

   セキュリティ上の理由により、イントロスペクション関数はデフォルトで無効になっています

   addressToLine、addressToLineWithInlines、addressToSymbol、demangle の イントロスペクション関数 を使用すると、関数名と ClickHouse コード内での位置を取得できます。シンボル化と同様に、これらの関数は Linux などの ELF プラットフォームおよび macOS で利用できますが、FreeBSD では利用できません。

   trace_log の情報を可視化する必要がある場合は、フレームグラフ と speedscope を試してください。

​

flameGraph 関数でフレームグラフを生成する

ClickHouse には、trace_log に保存されたスタックトレースから直接フレームグラフを生成する集約関数 flameGraph があります。 出力は、flamegraph.pl と互換性のあるフォーマットの文字列配列です。

構文:

flameGraph(traces, [size = 1], [ptr = 0])

引数:

• traces — スタックトレース。Array(UInt64)。
• size — メモリプロファイリングにおける割り当てサイズ。Int64。
• ptr — 割り当てアドレス。UInt64。

ptr が 0 以外の場合、flameGraph は同じサイズとポインタを持つ割り当て (size > 0) と解放 (size < 0) を対応付けます。 表示されるのは、解放されていない割り当てだけです。 対応する割り当てがない解放は無視されます。

​

CPU フレームグラフ

以下のクエリを実行するには、flamegraph.pl がインストールされている必要があります。

次のコマンドでインストールできます。

git clone https://github.com/brendangregg/FlameGraph
# 次のように使用します:
# ~/FlameGraph/flamegraph.pl

以下のクエリでは、flamegraph.pl を、お使いのマシン上で flamegraph.pl が配置されているパスに置き換えてください

SET query_profiler_cpu_time_period_ns = 10000000;

クエリを実行してから、フレームグラフを作成します。

clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(arrayReverse(trace)))
        FROM system.trace_log
        WHERE trace_type = 'CPU' AND query_id = '<query_id>'" \
    | flamegraph.pl > flame_cpu.svg

​

メモリフレームグラフ — 全割り当て

SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;

クエリを実行し、フレームグラフを生成します:

clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size))
        FROM system.trace_log
        WHERE trace_type = 'MemorySample' AND query_id = '<query_id>'" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem.svg

​

メモリ フレームグラフ — 未解放の割り当て

この種類では、ポインタを基準に割り当てと解放を照合し、クエリ中に解放されなかったメモリのみを表示します。

SET memory_profiler_sample_probability = 1, max_untracked_memory = 1,
    use_uncompressed_cache = 1,
    merge_tree_max_rows_to_use_cache = 100000000000,
    merge_tree_max_bytes_to_use_cache = 1000000000000;

フレームグラフを作成するには、以下のクエリを実行します。

clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size, ptr))
        FROM system.trace_log
        WHERE trace_type = 'MemorySample' AND query_id = '<query_id>'" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_unfreed.svg

​

メモリフレームグラフ — ある時点でのアクティブなメモリ割り当て

この方法を使うと、ピークメモリ使用量を特定し、その時点で何が割り当てられていたかを可視化できます。

SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;

​

メモリ使用量の推移を確認する

SELECT
    event_time,
    formatReadableSize(max(s)) AS m
FROM (
    SELECT
        event_time,
        sum(size) OVER (ORDER BY event_time) AS s
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'MemorySample'
)
GROUP BY event_time
ORDER BY event_time;

​

メモリ使用量が最大となる時点を特定する

SELECT
    argMax(event_time, s),
    max(s)
FROM (
    SELECT
        event_time,
        sum(size) OVER (ORDER BY event_time) AS s
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'MemorySample'
);

​

その時点でアクティブな割り当てのフレームグラフを作成する

clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size, ptr))
        FROM (
            SELECT * FROM system.trace_log
            WHERE trace_type = 'MemorySample'
              AND query_id = '<query_id>'
              AND event_time <= '<time_point>'
            ORDER BY event_time
        )" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_time_point_pos.svg

​

その時点以降の解放処理のフレームグラフを作成する (後から何が解放されたのかを把握するため)

clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, -size, ptr))
        FROM (
            SELECT * FROM system.trace_log
            WHERE trace_type = 'MemorySample'
              AND query_id = '<query_id>'
              AND event_time > '<time_point>'
            ORDER BY event_time DESC
        )" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_time_point_neg.svg

​

例

以下のコードスニペットでは、次の処理を行います。

• trace_log データをクエリ ID と当日の日付でフィルタリングします。
• あらかじめシンボル化された symbols および lines カラムを読み取り、以下を含むレポートを作成します。
  • シンボル名と対応するソースコード関数。
  • これらの関数のソースコード上の位置。
• 生のスタックトレース (trace カラム) で集計します。シンボル化されたカラムは表示のみに使用するため、ベストエフォートのシンボル化によって異なるスタックトレースが統合されることはありません。

SELECT
    count(),
    arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\n') AS sym
FROM system.trace_log
WHERE (query_id = '<query_id>') AND (event_date = today())
GROUP BY trace
ORDER BY count() DESC
LIMIT 10