CockroachDBのAdminUIをざっと眺めて、フーンとなるだけの時間

本記事のサマリ

CockroachDBのAdmin UIは、ブラウザから http://localhost:8080でアクセスできる管理画面で、クラスターの状態監視からパフォーマンス分析まで幅広い機能を提供しています。実際に各画面を見ながら、開発現場で役立つ機能や注目すべき指標について整理してみました。

これからCockroachDBで開発するにあたり、軽く触りたかったので、LocalでDocker環境を立てつつ見てみた次第です。

※ 前回のCockroachDBの導入記事はこちら↓
https://zenn.dev/stellarcreate/articles/cockroachdb-beginner-to-practical-knowledge

前提条件

この記事では、以下のDocker Compose構成でCockroachDBを起動していることを前提としています：

services:
  cockroachdb:
    image: cockroachdb/cockroach:v24.1.0
    container_name: todo-cockroachdb
    command: start-single-node --insecure
    ports:
      - "26257:26257"  # SQL port
      - "8080:8080"    # Admin UI
    volumes:
      - cockroach_data:/cockroach/cockroach-data
    restart: unless-stopped

volumes:
  cockroach_data:

起動方法は簡単です：

docker compose up -d

その後、ブラウザで http://localhost:8080 にアクセスすることでAdmin UIが開きます。--insecureオプションで起動しているため、開発環境では認証なしでアクセスできます（本番環境では必ず適切な認証設定を行ってください）。

Overview - クラスター概要

最初に目にするOverview画面は、まさにクラスターのダッシュボードです。
（AWSのEC2ダッシュボード的な?）
左上のCapacity Usageでは現在のディスク使用率が 0.0%と表示されており、まだまだ余裕があることが分かります。

注目すべきは右側のNode Statusセクションです。1個のLiveノード、56個のTotal Rangesが確認できます。

ここでTotal Rangesという概念について少し丁寧に説明しておきます。CockroachDBは、すべてのデータを「Range」という単位で管理しています。

https://www.cockroachlabs.com/docs/stable/architecture/distribution-layer.html

Rangeとは、キーバリューペアの連続したチャンクのことで、デフォルトで512MiBまで格納できます。この制限に達すると、CockroachDBは自動的にRangeを2つに分割します（Range Split）。

つまり、Total Rangesの数は以下のような時に変化します：

• 増える時: データが増えて既存のRangeがデフォルトの512MiBを超えたとき（自動分割）
• 減る時: データを大量に削除してRangeが一定サイズ以下に縮小し、隣接するRangeと自動マージされたとき（Range Merge）

現在表示されている 56個というのは、システムデータベースとアプリケーションデータベースを合わせた、クラスター全体のRange総数です。開発環境で todo_dbデータベースのサイズが29.2 KiBしかないのに56個もRangeがあるのは、CockroachDB自身が使う systemデータベースやインデックス、メタデータ（meta1、meta2などのメタRange）が含まれているためです。

本番環境でデータが増えていくと、このRange数も比例して増加します。例えば、100GBのデータがあれば、単純計算で約200個のRangeが作られることになります（100GB ÷ 512MiB ≒ 200）。Range数を見ることで、「あ、データが順調に増えてるな」とか「思ったよりRangeが多いな、インデックスが多すぎるのかも？」といった気づきを得られるわけです。

下部のNode Listでは、各ノードの詳細情報が一覧表示されています：

項目	値	意味
Uptime	14 minutes	ノードの稼働時間
Replicas	56	このノードが持つレプリカ数
Capacity Usage	0%	ストレージ使用率
Memory Use	10%	メモリ使用率
vCPU	10	利用可能なvCPU数

開発環境なので1ノード構成ですが、本番環境では複数ノードの状態を横並びで確認できるため、負荷の偏りやノード障害を素早く検知できそうです。

Metrics - パフォーマンスを測る

Metrics画面では、時系列でクラスターのパフォーマンスを追跡できます。画面上部のSQL Statementsグラフを見ると、14:50付近で急激にクエリ実行数が増加していることが分かります。これは恐らくアプリケーションからのバッチ処理やテストデータの投入があったタイミングでしょう。

特に興味深いのは中段のService Latency（SQL Statements, 99th percentile）のグラフです。同じ14:50付近でレイテンシが10msを超えてスパイクしています。SQLクエリの実行数増加とレイテンシ悪化が同時に発生しているということは、データベースに負荷がかかった瞬間を捉えているわけですね。

下部のSQL Statement Contentionは幸い低い値を維持しているようで、トランザクションの競合は発生していないことが確認できます。

実際の開発現場では、この画面でアプリケーションリリース後のパフォーマンス変化や、定期バッチ処理の影響を監視することが多いと思います。特にレイテンシのスパイクが見つかったときは、同じ時間帯のSQL Activityと照らし合わせて原因を特定する、という使い方が有効です。

Databases - テーブルを眺める

Databases画面では、クラスター内のデータベース一覧を確認できます。デフォルトで defaultdb、postgres、system、todo_dbの4つが見えています。

todo_dbを見てみると、サイズが 29.2 KiB、テーブル数が 3、Range Countが 4となっています。小さなアプリケーションのデータベースとしては妥当なサイズ感ですね。一方で systemデータベースは 1015.6 KiBと意外と大きく、53個のテーブルを持っています。これはCockroachDB自身のメタデータが格納されているためです。

画面上部に緑色のインジケータで「Auto stats collection - enabled」と表示されているのが確認できます。これは重要な機能なので、少し説明しておきましょう。

https://www.cockroachlabs.com/docs/stable/cost-based-optimizer.html

CockroachDBは、SQLクエリを実行する際に「どのインデックスを使うか」「どの順番でテーブルを結合するか」といった実行計画を決定します。この時、コストベースオプティマイザーというコンポーネントが、各テーブルの行数やデータの分布といった統計情報を参考にしながら、最も効率的（コストが低い）と思われる実行計画を選びます。

「Auto stats collection」が有効だと、CockroachDBは以下のタイミングで自動的に統計情報を収集・更新します：

• テーブルを新規作成したとき
• データが更新されて「古くなった行」が一定数を超えたとき（デフォルトでは500行、または全体の20%）
• スキーマ変更（ALTER TABLEなど）が実行されたとき

この統計情報があることで、オプティマイザーは「このテーブルには100万行あって、このカラムの値は均等に分布している」といった情報をもとに、適切な実行計画を選べるようになります。逆に統計情報が古いと、「実際には100万行あるのに、オプティマイザーは1000行しかないと思っている」といった状況が発生し、非効率な実行計画が選ばれてしまう可能性があります。

デフォルトで有効になっており、ほとんどの場合はそのままで問題ありません。大規模なデータロード中など、特殊な状況でのみ一時的に無効化することがあります。

データベースをクリックして詳細画面に入ると、テーブルレベルの情報が見えてきます。todo_dbの中には "public"."Assignee"、"public"."Todo"、"public"."_prisma_migrations"の3つのテーブルがあることが分かります。

各テーブルの % of Live Data列を見ると、どれも100%となっています。これは、ガベージコレクションの対象となる古いバージョンのデータが少ないことを意味しており、健全な状態と言えるでしょう。

この画面は、特に「どのテーブルがストレージを多く消費しているか」を特定するのに役立ちます。予想以上にデータが肥大化しているテーブルがあれば、インデックスの見直しやアーカイブ戦略を検討するきっかけになります。

SQL Activity - クエリの履歴を読む

SQL Activity画面は、実行されたSQLステートメントの詳細分析ができる画面です。Statement Fingerprintsタブでは、パラメータ値が正規化されたクエリパターンごとに統計情報が表示されます。

表示されているクエリを見ると、INSERT INTO public."Todo"系のクエリが多数実行されていることが分かります。執行回数が 18回、12回と表示されているので、アプリケーションからのデータ投入処理が頻繁に行われているようです。

各クエリの Statement Time列では、実行にかかった時間を確認できます。1.1 ms、730.0 µsといった値が見えており、幸いパフォーマンス的には良好な状態のようです。

時間範囲を Past Hourで絞り込んでいるのも実用的です。問題が発生した特定の時間帯にフォーカスして、どのクエリが原因だったかを特定する際に重宝します。

実際の運用では、ここで発見したスロークエリをもとに、インデックスの追加やクエリの書き換えを検討することが多いと思います。特に % of All Runtime列で大きな割合を占めているクエリは、最適化の効果が高い候補です。

Jobs

Jobs画面では、CockroachDBがバックグラウンドで実行するジョブの履歴を確認できます。画面を見ると、すべてのジョブが SUCCEEDEDステータスで完了しており、健全な状態であることが分かります。

興味深いのは、ジョブの種類の多様性です：

• ALTER TABLEによるスキーマ変更
• CREATE UNIQUE INDEXでのインデックス作成
• GC for temporary indexでの一時インデックスのクリーンアップ
• DROP DATABASEでのデータベース削除
• クラスターの初期化処理

Duration列を見ると、ほとんどの操作が 00:00:00、つまり1秒未満で完了しています。これは開発環境でデータ量が少ないためですが、本番環境では大きなテーブルでのインデックス作成やスキーマ変更に数時間かかることも珍しくありません。

このJobs画面は、特にマイグレーションやメンテナンス作業の進捗確認に重宝します。「さっき実行したALTER TABLE、まだ終わってないかな？」という時に、この画面を見れば一発で状況が把握できます！

Hot Ranges - データのホットスポットを探る

Hot Ranges画面は、CockroachDBの分散アーキテクチャを理解する上で非常に興味深い画面です。各RangeのQPS（Queries Per Second）やCPU使用時間、読み書きの統計を確認できます。

例えば、Range ID 51を見ると、QPSが 3.53、Write操作で 701.4 Bのデータが書き込まれています。一方、Range ID 18では、Read操作で 28.11キー、2.0 KiBのデータが読み取られています。

これらの情報から、どのRangeに負荷が集中しているかを特定できます。もし特定のRangeのQPSが異常に高ければ、それは「ホットスポット」と呼ばれる問題の兆候かもしれません。

ホットスポットは、例えば以下のような場面で発生しがちです：

• 連番のプライマリキーを使用した場合、最新のレコードに書き込みが集中
• 特定の人気商品やユーザーへのアクセスが集中
• 時系列データで、常に最新の時刻付近にデータが挿入される

この情報を元に、テーブル設計やシャーディング戦略の見直しを検討することができます。分散データベースならではの視点ですね👍

Advanced Debug

Reports セクションには、運用に役立つ専門的なレポートが並んでいます：

レポート	URL	用途
Custom Time Series Chart	#/debug/chart	カスタムメトリクスのグラフ化
Problem Ranges	#/reports/problemranges	問題のあるRangeの特定
Data Distribution	#/data-distribution	データ分散状況の可視化
Statement Diagnostics	#/reports/statements/diagnosticshistory	SQLステートメントの詳細診断

Configuration セクションでは、クラスター設定やロケーション情報を確認できます。特に本番環境では、ノードの物理的な配置（マルチリージョン構成など）を確認する際に重要です。

Even More Advanced Debugging セクションは、さらにマニアックなデバッグ情報へのアクセスを提供します。Node Diagnosticsでは、各ノードの詳細な診断情報を、Storesではストレージエンジンレベルの情報を確認できます。

これらのツールは、通常の運用では滅多に使わないかもしれませんが、本格的な障害調査や性能問題の深掘りには欠かせません。「なんか調子悪いな」程度では使いませんが、「本気で原因を突き止める必要がある」時の強力な武器になります。

まとめ - Admin UIで見えてくるCockroachDBの世界

CockroachDB Admin UIを一通り眺めてみると、単なる管理画面を超えた、分散データベースの「生きた状態」を観察できるツールであることが分かります。

普段のアプリケーション開発では、SQL文を書いてデータを操作することが中心ですが、Admin UIを通じて見ると「あ、このクエリがこれだけのRangeに影響を与えているんだ」「このテーブルがこんなにホットスポットになっているんだ」といった新たな発見があります。

特に印象的だったのは、Hot Rangesでの負荷分散の可視化です。従来のRDBMSでは見ることができない、分散アーキテクチャならではの視点を提供してくれそうです。

開発環境では http://localhost:8080で気軽にアクセスできます（insecure modeなので本番では適切な認証設定が必要ですが）。CockroachDB Cloudを使っている場合は、専用のCloud Consoleが提供されているので、そちらでより洗練されたUIを体験できるでしょう。

分散データベースの世界は、最初は複雑に感じるかもしれませんが、Admin UIを通して眺めてみると、意外と親しみやすい存在に思えて...きていると嬉しいです...
ぜひ実際に触ってみて、CockroachDBの奥深さを体験してみましょう✨