BetterDB Monitor

Valkeyにふさわしいモニタリングレイヤー。

BetterDBは、Valkeyが捨ててしまうもの（スローログ、コマンドパターン、クライアントアクティビティ、異常シグナル）を永続化します。これにより、「今起きていること」だけでなく、「午前3時に何が起きたのか」をデバッグできます。Valkey 8.x向けに構築され、COMMANDLOG、CLUSTER SLOT-STATS、スレッドごとのI/Oメトリクスをネイティブにサポートします。その他はRedis 6+と互換性があります。

ウェブサイト | Docker Hub | npm | ドキュメント | ブログ

BetterDBは、OCV Open Charterに基づいて運営されるパブリック・ベネフィット企業であるBetterDB Inc.によって構築されています。

クイックスタート（Docker）

docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest

ブラウザで http://localhost:3001 を開いてください。特定のインスタンスを監視するには:

docker run -d \
  --name betterdb \
  -p 3001:3001 \
  -e DB_HOST=your-valkey-host \
  -e DB_PORT=6379 \
  -e DB_PASSWORD=your-password \
  betterdb/monitor:latest

2つのイメージバリアントが公開されています。どちらもマルチアーキテクチャ（linux/amd64、linux/arm64）です:

永続ストレージ、カスタムポート、ライセンス、エアギャップ環境のセットアップについては、Docker本番デプロイを参照してください。

クイックスタート（CLI）

Dockerを使わずにBetterDB Monitorを実行する:

npx @betterdb/monitor

初回実行時には、対話式セットアップウィザードがデータベース接続、ストレージバックエンド（SQLite、PostgreSQL、またはインメモリ）、サーバー設定を案内します。設定は ~/.betterdb/config.json に保存されます。

npm install -g @betterdb/monitor   # グローバルインストール
betterdb --setup                   # セットアップウィザードを再実行
betterdb --port 8080               # サーバーポートを上書き
betterdb --db-host 1.2.3.4         # データベースホストを上書き
betterdb --help                    # 全オプションを表示

Node.js >= 20.0.0 と、監視対象のValkeyまたはRedisインスタンスが必要です。SQLiteストレージを使用する場合は、npm install -g better-sqlite3 も実行してください。

提供される機能

すべてを見る、すべてを保持

• 履歴分析 - 任意の時間範囲でスローログ、コマンドパターン、クライアントアクティビティ、レイテンシを照会できます。ログローテーション後に消えていたデータです。
• COMMANDLOGサポート - Valkey 8.1+限定。遅いリクエストだけでなく、大きなリクエストや大きなレスポンスも記録します。
• MONITORキャプチャセッション - 必要に応じて実際のトラフィックを記録: ライブテール、フィルタリング、再生、JSON/CSVエクスポート、接続履歴との相互参照が可能です。
• ホットキートラッキング - アクセス頻度の高いキーを、時間経過によるランク変動とともに表示。Key Analytics（Pro、早期アクセス中は無料）では、ライブサンプリングによる型、TTL、サイズ分布が追加されます。
• クラスタの可視性 - トポロジーグラフ、SLOT-STATSヒートマップ、スロットごとのCPUとキー分布。
• CPU & I/Oスレッドメトリクス - Redisツールでは得られないスレッド単位の可視性。
• クライアント分析 - どのサービスが何の原因かを、クライアント名とパターンで正確に把握できます。
• ACL監査証跡 - 誰が何にアクセスしたかを追跡し、コンプライアンスとインシデント後のデバッグのために永続化します。

理解して行動する

• 異常検知（Pro、早期アクセス中は無料） - 相関イベントと平易な英語による診断を備えた自動ベースライン学習。20以上の検知器、手動しきい値は不要。
• 容量予測 - メモリ、ops/sec、CPU、フラグメンテーションの上限到達までの予測時間。
• Webhook - HMAC署名付きアラート配信。リトライと完全な配信ログ付き。
• ライブマイグレーション - 分析、実行、検証の3フェーズのワークフローでRedisとValkey間を移行。

AI時代に向けて構築

• ベクター検索の可観測性 - valkey-search と RediSearch 向けのFT.SEARCH ops/secとレイテンシ、インデックスごとのヘルス。 docs/vector-ai を参照。
• 推論レイテンシ - インデックスごとのp50/p95/p99、SLA違反アラート付き（Pro、早期アクセス中は無料）。
• セマンティックキャッシュインテリジェンス（Pro、早期アクセス中は無料） - ヒット率の健全性、類似度しきい値の推奨、承認/拒否の提案ワークフロー。エージェントメモリの可観測性も含まれます。
• AIトレース - AIアプリケーションからのOTLPスパンウォーターフォールを、各リクエストの基盤となるValkeyのライブ状態と関連付けます。

あらゆるものと連携

• MCPサーバー - @betterdb/mcp 経由で Claude Code、Cursor、または任意のMCPクライアント向けの60のツール。
• Prometheusエンドポイント - 100以上の betterdb_* メトリクス。 docs/prometheus-metrics.md を参照。
• OpenTelemetry - メトリクスとイベントを任意のOTLPバックエンドにミラーリング。
• REST API - UI内のすべてがAPI呼び出しで、OpenAPIで文書化されています。

好みの方法でデータにアクセス

注: 本番ビルド（Docker、CLI）ではAPIルートは /api プレフィックスの下で提供されます。ローカル開発（pnpm dev）ではプレフィックスはありません - 例: http://localhost:3001/health。

対応データベース

バックエンドはワイヤー互換の iovalkey クライアント上の統合アダプターを使用し、INFO レスポンス（DB_TYPE=auto）からValkeyかRedisかを自動検出します。COMMANDLOGやSLOT-STATSなどの機能はバージョンごとに検出され、機能が利用できない場合、UIはグレースフルに縮退します。

マネージドサービスもサポートされています - AWS ElastiCache、MemoryDB、Redis Cloud、Upstashのガイドは docs/providers にあり、@betterdb/agent はアウトバウンドWebSocket経由でVPC内のインスタンスに到達します。

Docker本番デプロイ

Dockerイメージにはモニタリングアプリケーション（バックエンド + フロントエンド）が含まれています。必要なもの:

1. 監視対象のValkey/Redisインスタンス
2. データ永続化用のPostgreSQLインスタンス（またはメモリストレージを使用）

PostgreSQLストレージで実行

docker run -d \
  --name betterdb-monitor \
  -p 3001:3001 \
  -e DB_HOST=your-valkey-host \
  -e DB_PORT=6379 \
  -e DB_PASSWORD=your-password \
  -e STORAGE_TYPE=postgres \
  -e STORAGE_URL=postgresql://user:pass@postgres-host:5432/dbname \
  betterdb/monitor

カスタムポートで実行

PORT 環境変数を設定し、-p マッピングを合わせます:

docker run -d \
  --name betterdb-monitor \
  -p 8080:8080 \
  -e PORT=8080 \
  -e DB_HOST=your-valkey-host \
  betterdb/monitor

ホストネットワークで実行（localhostサービスにアクセス）

ValkeyとPostgreSQLが同じホストで実行されている場合:

docker run -d \
  --name betterdb-monitor \
  --network host \
  -e DB_HOST=localhost \
  -e DB_PORT=6380 \
  -e DB_PASSWORD=devpassword \
  -e STORAGE_TYPE=postgres \
  -e STORAGE_URL=postgresql://dev:devpass@localhost:5432/postgres \
  betterdb/monitor

環境変数

AI、OTLPエクスポート、Webhook調整、ヘルスゲートしきい値を含む完全なリファレンス: docs/configuration.md。

ライセンスとエアギャップサポート

BetterDB Monitorは、ホストがインターネットにアクセスできるかどうかに応じて、次の2つの方法のいずれかでPro/Enterprise機能を有効化します:

• オンラインライセンスキー - BETTERDB_LICENSE_KEY を設定します。モニターは betterdb.com に対して検証し、ローカルで検証済みの署名付きトークンをキャッシュするため、短い障害や再起動中もティアは機能し続けます。
• オフライン / エアギャップライセンストークン - インターネットに一切アクセスできないホスト向け（下記参照）。

エアギャップライセンスの仕組み

すべての権限は署名付きRS256 JWTです。モニターはイメージに埋め込まれた公開鍵に対してローカルで検証します。トークンを信頼するためにライセンスサーバーに到達する必要は一切ありません。したがって、エアギャップホストはゼロ接続で有料ティアを実行できます:

1. インターネットに接続されたマシンで、betterdb.com/account/licenses にサインインし、オフラインライセンストークン（.jwt、Pro/Enterprise）をダウンロードします。シークレットは含まれておらず、改ざんは不可能です - 編集すると署名が壊れます。
2. USB、構成管理、Docker/Kubernetesシークレットマウントなど、任意の方法でエアギャップホストに転送します。
3. BETTERDB_OFFLINE_LICENSE_FILE（パス）、BETTERDB_OFFLINE_LICENSE（インライン文字列）で指定するか、UIの**設定 → ライセンス →「エアギャップ環境ですか？オフラインライセンスを有効化」**に貼り付けます。

オフライントークンが設定され、BETTERDB_LICENSE_KEY が設定されていない場合、モニターはゼロのアウトバウンドリクエストを行います - ライセンスチェック、テレメトリ、更新pingはすべて無効になります。トークンが期限切れになるまで付与されたティアを実行し（永続ライセンスは毎年再ダウンロード）、その後Communityに戻ります。

# fully offline - no network required
docker volume create betterdb-data
docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d   # volume writable by UID 1001 (one-time)

docker run -d --name betterdb-monitor -p 3001:3001 \
  -e DB_HOST=your-valkey-host -e DB_PORT=6379 -e DB_PASSWORD=your-password \
  -v /path/to/betterdb-license.jwt:/run/secrets/betterdb-license.jwt:ro \
  -e BETTERDB_OFFLINE_LICENSE_FILE=/run/secrets/betterdb-license.jwt \
  -v betterdb-data:/app/data \
  betterdb/monitor

GET /api/license/status で確認 → source: offline-token、mode: offline、airGapped: true。

永続化: /app/data に書き込み可能なボリュームをマウントして、オフラインライセンスとオンラインの障害猶予トークンが再起動後も残るようにします。コンテナはUID 1001で実行されるため、新しく作成したボリュームは（上記のように）そのUIDにchownする必要があります - そうしないと、EACCES … license.jwt で永続化に失敗します。

完全なフロー、検証の優先順位、キーローテーションのラン ブックについては、オフライン & エアギャップライセンス と 設定リファレンス を参照してください。

Dockerイメージの詳細

• ベースイメージ: node:20-alpine
• 圧縮サイズ: ~360MB（latest / -no-ai）/ ~640MB（実験的なAIヘルパーのローカルLLM依存関係を含むバージョン付きイメージ）
• プラットフォーム: linux/amd64, linux/arm64
• 含まれるもの: バックエンドAPI + フロントエンド静的ファイル（Fastifyが配信）
• 含まれないもの: SQLiteサポート（PostgreSQLまたはメモリストレージを使用）

コンテナ操作

docker logs -f betterdb-monitor        # ログを追跡
docker stop betterdb-monitor           # 停止
docker rm betterdb-monitor             # 削除

ストレージバックエンド

BetterDB Monitorは、監査証跡、分析、キャプチャ、異常データを次の3つのバックエンドのいずれかに永続化します:

Prometheusメトリクス

メトリクスは GET /api/prometheus/metrics でPrometheusテキスト形式で公開されます: ACL監査、クライアント接続、slowlog/commandlogパターン、メモリ、スループット、キースペース、レプリケーション、クラスタスロット統計、Node.jsランタイムメトリクス - すべて betterdb_ プレフィックス付きです。

scrape_configs:
  - job_name: 'betterdb-monitor'
    metrics_path: '/api/prometheus/metrics'
    static_configs:
      - targets: ['your-monitor-host:3001']

完全なメトリクスリファレンス: docs/prometheus-metrics.md と docs/prometheus-integration.md。

開発

プロジェクト構成

betterdb-monitor/
├── apps/
│   ├── api/                 # NestJS backend (Fastify)
│   └── web/                 # React frontend (Vite)
├── packages/                # Published packages (see below)
├── docs/                    # Documentation site (Jekyll)
├── docker-compose.yml       # Local Valkey (port 6380) and Redis (port 6382) for testing
└── package.json             # Workspace root

パッケージ

このモノレポは、いくつかのスタンドアロンパッケージを提供しています。完全なリストは packages/ を参照してください。

技術スタック

• バックエンド: Fastifyアダプターを使用したNestJS、Valkey/Redis接続用の iovalkey、TypeScript strictモード。ポート 3001。
• フロントエンド: React + TypeScript、Vite、TailwindCSS、Recharts。開発サーバーはポート 5173。
• モノレポ: pnpm workspaces + Turborepo。

ローカルセットアップ

前提条件: Node.js >= 20.0.0、pnpm >= 9.0.0、Docker。

pnpm install
cp .env.example .env
pnpm docker:dev        # local Valkey (6380) and Redis (6382)
pnpm dev               # web on :5173, api on :3001

Valkeyの代わりにRedisに接続するには、.env で DB_PORT=6382 を設定します。

pnpm dev:api           # API only
pnpm dev:web           # frontend only
pnpm docker:dev:down   # stop local databases
pnpm build             # production build
pnpm test              # API tests

Dockerイメージのビルド:

pnpm docker:build      # local build
pnpm docker:publish    # multi-arch build & push (requires buildx)

新機能の追加

1. apps/api/src/ に新しいエンドポイントを追加する
2. apps/web/src/api/ に対応するAPI呼び出しを追加する
3. packages/shared/src/types/ に共有型を追加する

コードスタイル

• TypeScript strictモード、明示的な戻り値の型、any なし
• ESLint + Prettier 設定済み

ライセンス

• docs/ 配下のコンテンツはCC BY-SA 4.0でライセンスされています。
• proprietary/ 配下のコンテンツは商用ライセンスの対象です（proprietary/LICENSE を参照）。これらの機能は早期アクセス期間中は無料です。
• その他すべては MIT です。