ClickHouse に組み込まれた ClickStack のご紹介

TLDR; #

26.2 より、新しい配布形態として ClickHouse に組み込まれた ClickStack UI の提供を開始します。ClickStack UI が ClickHouse バイナリに直接組み込まれて配布されるようになったため、ローカルインスタンスでのオブザーバビリティの検証、独自のデータセットの探索、さらには ClickHouse 自体の内部調査を簡単に行えます。https://localhost:8123, にアクセスし、「ClickStack」を選択するだけで探索を始められます。

はじめに #

これまで、ClickStack は Docker ベースの配布形式で利用可能でした。テストや検証目的であれば 単一コンテナでフルスタックを実行 できますし、本番環境へ移行する際には Helm などのツール を使用して UI、Collector、ClickHouse を個別に動かすなど、各コンポーネントを個別にデプロイ することもできます。

さらに最近では、UI と ClickHouse の両方をホストする ClickHouse Cloud 上のフルマネージド ClickStack をリリースしました。統合認証に加え、ClickHouse Cloud のストレージとコンピュートの分離アーキテクチャを活用できます。これにより、オブジェクトストレージでの長期データ保持を実現しながら、コンピュートを個別にスケーリングして 1 GB あたりのコストを最小限に抑えることが可能です。

26.2 からは、3 つ目の選択肢が加わります。

ClickStack UI が ClickHouse バイナリ自体に組み込まれるようになりました。高性能な C++ データベースに Web アプリケーションを組み込むと聞くと、バイナリサイズが大幅に肥大化するように思えるかもしれません。しかし実際には、追加されるフットプリントを 4.1 MB 未満に抑えており、軽量かつ迅速なインストールの維持を実現しています。

これにより、ClickHouse をインストールするだけですぐに ClickStack を利用できるようになります。Docker を使う場合も、バイナリを直接ダウンロードする場合も、お好みのパッケージマネージャー経由でインストールする場合でも、ClickStack は即座に利用可能です。ClickHouse をインストールして http://localhost:8123 にアクセスし、メニューから ClickStack を選択するだけで、わずか数秒でログ、トレース、メトリクスの探索を開始できます。

探索とローカル開発向けに設計 #

組み込み版の ClickStack UI は、ローカルでの検証や学習、オブザーバビリティ UI を使った ClickHouse 内の独自データの探索向けに設計されています。本番環境でのデプロイを意図したものではありません。

この配布形態により、ローカルの ClickHouse インスタンスでオブザーバビリティを試用したり、独自のデータセットを探索したり、ClickHouse 自体の動作を調査したりすることが容易になります。ClickHouse はすでに豊富な内部ログやメトリクスを出力しており、パフォーマンスの診断や最適化に極めて有用です。ClickStack UI を使えば、これらのデータを手軽に可視化し、インスタンスの挙動をより深く理解できます。

ClickHouse のプリセットダッシュボードは、ローカル環境の問題やパフォーマンスの課題を診断するのに役立ちます。また、ローカルログの検索や、システムメトリクステーブルを使った可視化の構築も可能です。

規模の大きい環境や本番環境へのデプロイでは、ClickStack の各コンポーネントを個別に実行することを常に推奨しています。

また、組み込み版では配布サイズを小さく抑え、シンプルな利用体験を維持するために、あえて一部の機能を省いています。永続的な状態ストレージを持たないため、ダッシュボードやクエリの永続化に加えて、アラート機能も無効化されています。イベントパターン機能も、WASM Python ランタイムが必要となりサイズが大きくなるため含まれていません。

こうした制限の一部は、ブラウザベースのストレージなどのアプローチを用いて将来的に対応する可能性がありますが、現時点ではシンプルさと手軽さに重点を置いています。

大規模に ClickStack を運用する予定がある場合や、アラートとデータの永続化が必要な場合は、引き続きオープンソースの Docker 版またはマネージドクラウドのサービスを利用することをお勧めします。

技術的な課題 #

興味のある方向けに説明すると、完全な Web アプリケーションを C++ のデータベースバイナリ内に組み込むにあたっては、興味深いエンジニアリング上の決定がいくつかありました。

前提条件 #

ClickStack を ClickHouse 内に組み込むことは、コアチームが定めた厳しい条件の枠内で作業することを意味していました。これは、ClickHouse バイナリに求められるエンジニアリング標準を反映したものです。

1. ClickHouse に Node.js の依存関係を追加することは論外である
2. ファイルはファイルシステム上のどこかに残すのではなく、バイナリ内に組み込む必要がある
3. ClickStack によってバイナリサイズを大幅に肥大化させてはならない

Next.js に関する部分 #

ClickStack を支える UI である HyperDX は、Next.js アプリケーションです。ご存じの方も多いと思いますが、Next.js はページを提供(サーブ)する前にサーバー上でレンダリングを行うフルスタックフレームワークであり、フロントエンドとバックエンドの双方が1つのアプリケーションにバンドルされています。静的ページと動的 HTML の両方を提供できます。しかし、Node.js の依存関係を導入せずに動的ページを提供するには、Next.js の内部実装を大幅に書き直す必要があります。そのため、動的ページの提供は選択肢から外れました。幸いなことに、ClickStack は静的ページを多用しています。ブラウザ上で React は動作し続けますが、動的なサーバーサイドレンダリングはほとんど発生しません。

ClickHouse には既存の HTML ページがいくつか用意されています。たとえば、WebUI でクエリを実行するための play.html や、ClickHouse インスタンスの健全性を確認するのに非常に役立つダッシュボード用の dashboards.html などです。dashboards.html ページでは一部 JavaScript の読み込みも行われています。

しかし、どちらも ClickStack のような本格的な最新ウェブサイトの webpack 出力を提供する複雑さには到底及びません。この複雑さについては ClickHouse へのバンドル のセクションで説明しますが、既存の Web ページが存在していたおかげで、わずかなカスタム機能を追加するだけでハンドラーを1つ増やせることがわかりました。

ClickStack の既存バリエーションと ClickHouse への接続 #

ClickStack には、コア機能が依存しているコンポーネントがすでにいくつか存在します。標準的なアプリケーションには、Next.js、Express、MongoDB が含まれます。Express と MongoDB は主に、保存済み検索、ダッシュボード、ソースを対象とした CRUD の永続化レイヤーとして使用されます。また、Express サーバーは ClickHouse のプロキシとしても機能し、データベースの認証情報がフロントエンドに漏洩しないよう認証も処理します。ClickStack を ClickHouse に組み込む際、Express バックエンド、MongoDB、プロキシレイヤーが利用できなくなることは明白でした。

しかし、必要な機能の大部分を備えたデモサイトがすでに存在していました。そこでは、接続情報はセッションストレージに保存され、ソースはローカルストレージに永続化され、プロキシレイヤーなしで ClickHouse に直接クエリを実行できるようになっていました。必要だった修正は、すべてのリンクにプレフィックス「/clickstack」を付与することだけでした。この仕組みを使えば、ClickHouse へのバンドルを試行できます。

また、ClickStack の「イベントパターン」機能に使用されているブラウザ用 WASM Python ランタイムである pyodide の削除も決定しました。これは純粋に、ClickHouse のバイナリサイズが許容範囲を超えて肥大化してしまうためです。

ClickHouse へのバンドル #

ClickHouse は多くのサードパーティライブラリを使用しており、それらを git サブモジュール経由で管理しています。つまり、依存関係のバージョン更新は、特定のコミットをチェックアウトして ClickHouse のビルドを再実行するだけで済みます。これにより、ClickStack を利用可能なサブモジュールとして提供できれば、新しい ClickStack バージョンへのアップグレードが容易になるという基本的な基盤が得られます。

ClickHouse のビルドには、cmake、ccache、ninja など、多くの依存ツールが必要です。しかし、Node.js は含まれていません。ローカル開発時の摩擦を減らしビルド時間を短縮するためにも、node.js のような影響の大きい新たな依存関係を追加することは選択肢になり得ませんでした。優れた代替案は、リリース時に静的バンドルを生成し、それを git サブモジュールに直接含めることです。ClickStack リポジトリを煩雑にしたくなかったため、ClickStack の特定バージョンを再現性高くチェックアウトし、静的出力をビルドして、バンドルを更新できる新しいリポジトリを作成することにしました。理想的には、ClickStack の新バージョンリリース時にすべて自動化される形です。

しかし、まだ問題が残っています。ClickHouse のビルド内にファイルは配置されましたが、それらをどうやって組み込むべきでしょうか。

C++ には、既知のファイルをファイルとしてではなく生のバイト列として組み込める #embed マクロがあります。あいにく Next.js の特徴として、ランダムに見えるファイル名が大量に出力されます。これに対処するため、cmake の機能を活用して C++ ファイルを動的に生成しています。処理の流れは次のとおりです。

1. 静的定義、具体的にはファイル名、バイト列、MIME タイプを含む構造体定義を持つ新しいファイルを作成する
2. contrib/clickstack/out 内のすべてのファイルを検索する
3. ファイル名でソートする
4. ファイルごとに以下の処理を行う
   1. ファイルを gzip 圧縮する(バイナリサイズおよびブラウザへ転送するデータ量を削減するため)
   2. 配列内にエントリを生成する

生成されたファイルは、シンプルに #include されます。その後、/clickstack HTTP ハンドラーへのリクエストが発生すると、対象ファイルの二分探索が行われます。ファイルが見つかった場合、適切な MIME タイプとともにファイルが返されます。ブラウザ側では、ユーザーが ClickHouse に対する認証用のユーザー名とパスワードの認証情報を入力する必要があり、これらを使って HTTP 経由で ClickHouse に直接クエリが実行されます。

その結果、実際のバイナリ自体に直接組み込まれるサイズは約 4.2 MB という、非常に無駄のない追加に収まりました。

今すぐ始める #

ClickHouse に組み込まれた ClickStack を試すには、通常どおり ClickHouse をインストールします。1行のインストーラーコマンドを使用できます。

1curl https://clickhouse.com/ | sh

その他のインストール方法については、オープンソース向けクイックスタートガイドを参照してください。

今回の例では、実行されたクエリやリソース使用状況など、手元の ClickHouse インスタンス内部の様子を調べられるよう、内部ログを有効化します。

バイナリをダウンロードしたら、ClickHouse のデータを保存するディレクトリに移動します。次に、クエリログとメトリクスログを有効にする設定スニペットを作成します。

1mkdir -p config.d && echo "<clickhouse><query_log><database>system</database><table>query_log</table></query_log><query_thread_log><database>system</database><table>query_thread_log</table></query_thread_log><query_views_log><database>system</database><table>query_views_log</table></query_views_log><metric_log><database>system</database><table>metric_log</table></metric_log><asynchronous_metric_log><database>system</database><table>asynchronous_metric_log</table></asynchronous_metric_log></clickhouse>" | sudo tee ./config.d/query_logs.xml > /dev/null

これによりデフォルト設定に追加が行われ、システムログテーブルが有効になります。

サーバーを起動し、ブラウザで http://localhost:8123/clickstack を開きます。

1./clickhouse server

ローカルインスタンスへの接続は自動的に作成されます。すでに OpenTelemetry データがロードされている場合、ClickStack はそれを検出してソースを自動生成します。新規インストール環境では、ソースの作成を促すメッセージが表示されます。今回の例では、system.query_log を指す新しい Log Source を作成します。

設定: Name: Query Logs

Database: system

Table: query_log

Timestamp Column: event_time

Default Select: event_time, query_kind, query, databases, tables, initial_user, projections, memory_usage, written_rows, read_rows, query_duration_ms

ソースを保存します。検索ビューにリダイレクトされ、クエリログがすぐに表示され始めるはずです。

この時点で、手元の ClickHouse インスタンスのオブザーバビリティが確立されています。

http://localhost:8213/play で Play UI を開き、いくつかクエリを実行して、それらが ClickStack に表示されるのを確認してみてください。デフォルトの選択項目では、実行時間、メモリ使用量、使用されたプロジェクションなどの有用なメタデータを表示できます。

また、左側のナビゲーションメニューから利用できる ClickHouse プリセットダッシュボードも組み込まれています。クエリレイテンシやスロークエリの把握、最も実行時間を要しているクエリパターンのハイライト、テーブルごとのクエリ数の表示、CPU 使用率、メモリ消費量、S3 リクエスト数、挿入アクティビティといった主要なシステムメトリクスの可視化が可能です。これらのビューを組み合わせることで、組み込みの ClickStack UI だけで ClickHouse インスタンスの状態を即座に把握できます。

ClickStack の探索を続け、その機能をさらに学ぶには、用意されているサンプルデータセットのいずれかを試してみることをお勧めします。これらには、OpenTelemetry デモからのサンプルオブザーバビリティデータに加えて、セッションリプレイ機能の探索やローカルインフラストラクチャと ClickHouse インスタンスのモニタリングを行うためのサンプルが含まれています。

まとめ #

ClickStack が ClickHouse に直接組み込まれたことで、オブザーバビリティの導入はデータベース自体のインストールと同じくらいシンプルになりました。追加のセットアップは不要で、個別のサービスを実行する必要も、外部 UI をデプロイする必要もありません。わずか数秒で、ログ、トレース、メトリクス、さらには ClickHouse 自体の内部動作まで探索し始めることができます。

この配布形態によって導入のハードルが下がり、手元のローカルデータセットを使って ClickStack の価値をより手軽に見出していただけることを願っています。製品の学習、デモの実施、チームのトレーニング、クエリの検証、開発時における ClickHouse の動作把握のための実践的な環境を提供します。

コミュニティの皆様にどのようにご活用いただき、その進化にご貢献いただけるかを楽しみにしています。