BetterDB Monitor

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

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

Website | Docker Hub | npm | Documentation | Blog

BetterDB は、OCV Open Charter に基づいて運営される公益企業である BetterDB Inc. によって構築されています。

BetterDB Monitor - Key Analytics with per-type key size distribution histograms

クイックスタート（Docker）```bash

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

ブラウザで `http://localhost:3001` を開いてください。特定のインスタンスを監視するには:```bash
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

ホストマシン上のデータベースに接続しますか？ コンテナ内では localhost はコンテナ自身を指し、ホストを指しません。そのため、データベースホストには host.docker.internal を使用してください。Docker Desktop (macOS/Windows) ではそのまま動作します。Linux では、docker run コマンドに --add-host=host.docker.internal:host-gateway を追加して名前が解決されるようにしてください。ダッシュボードのワンクリック「ローカルインスタンスに接続」ボタンはこれを自動検出し、適切なホストを事前入力します。

2つのイメージバリアントが公開されており、どちらもマルチアーキテクチャ (linux/amd64, linux/arm64) です:

タグ	内容
`latest`, `X.Y.Z-no-ai`	デフォルトイメージ - すべてのモニタリング機能を含み、実験的なローカルLLM AIヘルパーの依存関係は含みません
`X.Y.Z`	実験的なAIヘルパーを追加 (独自のOllamaを持ち込み、`AI_ENABLED` でデフォルト無効)

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

クイックスタート (Kubernetes / Helm)```bash

helm repo add betterdb https://docs.betterdb.com/charts helm repo update helm install betterdb-monitor betterdb/betterdb-monitor
--namespace betterdb --create-namespace
--set db.host=my-valkey.default.svc.cluster.local
--set db.password=yourpassword

Then `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` を実行し、`http://localhost:3001` を開くか、チャートのイングレスを有効にします。PostgreSQL バックエンドの履歴、独自の Secrets の持ち込み、およびエアギャップ環境向けライセンスについては、[Kubernetes ガイド](https://docs.betterdb.com/kubernetes) と [チャート README](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md) で詳しく説明されています。

## クイックスタート（CLI）

Docker を使用せずに BetterDB Monitor を実行する場合：```bash
npx @betterdb/monitor

初回実行時には、対話式のセットアップウィザードがデータベース接続、ストレージバックエンド（SQLite、PostgreSQL、またはインメモリ）、およびサーバー設定を案内します。設定は ~/.betterdb/config.json に保存されます。```bash npm install -g @betterdb/monitor # global install betterdb --setup # re-run setup wizard betterdb --port 8080 # override server port betterdb --db-host 1.2.3.4 # override database host betterdb --help # all options

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](https://github.com/valkey-io/valkey-search) と RediSearch のインデックスごとのヘルスを含む FT.SEARCH ops/sec とレイテンシ。 [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md) を参照してください。
- **推論レイテンシ** - インデックスごとの p50/p95/p99 と、SLA 違反アラート (Pro、早期アクセス中は無料)。
- **セマンティックキャッシュインテリジェンス** (Pro、早期アクセス中は無料) - ヒット率のヘルス、類似度しきい値の推奨、承認/拒否の提案ワークフロー。エージェントメモリの可観測性も含まれます。
- **AI トレース** - AI アプリケーションからの OTLP スパンウォーターフォールを、各リクエストの下にあるライブ Valkey 状態と関連付けます。

### あらゆるものに接続

- **MCP サーバー** - Claude Code、Cursor、または任意の MCP クライアント向けの 60 ツールを [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp) 経由で提供。
- **Prometheus エンドポイント** - 100 以上の `betterdb_*` メトリクス。 [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) を参照してください。
- **OpenTelemetry** - メトリクスとイベントを任意の OTLP バックエンドにミラーリング。
- **REST API** - UI のすべてが API 呼び出しであり、OpenAPI で文書化されています。

## データに好きな方法でアクセス

| インターフェース | 詳細 |
|-----------|---------|
| Web UI | `http://localhost:3001` |
| MCP サーバー | `npx @betterdb/mcp` (stdio) - 設定 → MCP トークンでトークンを作成 |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| REST API (OpenAPI) | `http://localhost:3001/docs` |
| ヘルスチェック | `http://localhost:3001/api/health` |

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

## サポートされているデータベース

| データベース | 最小バージョン | サポートされる機能 |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | COMMANDLOG (8.1+) と CLUSTER SLOT-STATS を含むすべての機能 |
| **Redis** | 6+ | Valkey 限定の COMMANDLOG と CLUSTER SLOT-STATS を除くすべての機能 |

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

マネージドサービスもサポートされています - AWS ElastiCache、MemoryDB、Redis Cloud、Upstash のガイドは [docs/providers](https://github.com/betterdb-inc/monitor/blob/master/docs/providers) にあり、[`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) はアウトバウンド WebSocket 経由で VPC 専用インスタンスに到達します。

## Docker 本番デプロイ

Docker イメージには監視アプリケーション (バックエンド + フロントエンド) が含まれています。必要なもの:
1. 監視対象の Valkey/Redis インスタンス
2. データ永続化のための PostgreSQL インスタンス (またはメモリストレージを使用)

### PostgreSQL ストレージで実行```bash
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 マッピングを合わせます:```bash docker run -d
--name betterdb-monitor
-p 8080:8080
-e PORT=8080
-e DB_HOST=your-valkey-host
betterdb/monitor

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

Valkey と PostgreSQL が同じホスト上で実行されている場合：```bash
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

環境変数

変数	必須	デフォルト	説明
`DB_HOST`	はい	`localhost`	監視対象のValkey/Redisホスト
`DB_PORT`	いいえ	`6379`	Valkey/Redisポート
`DB_PASSWORD`	いいえ	-	Valkey/Redisパスワード
`DB_USERNAME`	いいえ	`default`	Valkey/Redis ACLユーザー名
`DB_TYPE`	いいえ	`auto`	データベースタイプ: `auto`、`valkey`、または `redis`
`STORAGE_TYPE`	いいえ	`memory`	ストレージバックエンド: `memory` または `postgres`
`STORAGE_URL`	条件付き	-	PostgreSQL接続URL（`STORAGE_TYPE=postgres` の場合に必須）
`PORT`	いいえ	`3001`	アプリケーションのHTTPポート
`NODE_ENV`	いいえ	`production`	Node環境
`ANOMALY_DETECTION_ENABLED`	いいえ	`true`	異常検知を有効にする
`ANOMALY_PROMETHEUS_INTERVAL_MS`	いいえ	`30000`	Prometheusサマリー更新間隔（ms）
`BETTERDB_LICENSE_KEY`	いいえ	-	オンラインライセンスキー（Pro/Enterprise）。ネットワーク経由で検証される
`BETTERDB_OFFLINE_LICENSE_FILE`	いいえ	-	エアギャップ環境のホスト向け署名済みオフラインライセンス `.jwt` へのパス（下記参照）
`BETTERDB_OFFLINE_LICENSE`	いいえ	-	インラインJWT文字列としてのオフラインライセンストークン
`BETTERDB_DATA_DIR`	いいえ	`/app/data`	永続化されたライセンス状態の保存ディレクトリ（書き込み可能なボリュームをマウントする）
`ENCRYPTION_KEY`	いいえ	-	保存時に保存された接続パスワードとSSHトンネルシークレットをエンベロープ暗号化するためのキー（最小16文字）。これがない場合、シークレットは平文で保存される
`BETTERDB_SSH_KEY_DIR`	いいえ	-	サーバー側SSH秘密鍵が配置されている必要があるディレクトリ。SSHトンネルの「サーバーファイルパス」キーソースを有効にする。接続のキーパスはこのディレクトリ内に解決される必要がある。未設定の場合はファイルベースのキーが無効になる（インラインで貼り付けたキーは引き続き機能する）
`BETTERDB_TELEMETRY`	いいえ	`true`	匿名テレメトリを無効にするには `false` に設定する

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

SSHトンネル

接続は直接接続する代わりにSSH踏み台/ジャンプホストを経由してデータベースに到達できます。これはプライベートサブネット内のValkey/Redis、ElastiCache、またはMemoryDBに役立ちます。接続を追加するときにSSHトンネル経由で接続を有効にし、SSHホスト、ポート、ユーザー名を指定します。シングルホップがサポートされています。

認証はパスワードまたは秘密鍵のいずれかです。秘密鍵は次の2つのソースのいずれかから取得されます:

キーを貼り付け（インライン）: PEMキーコンテンツが接続とともに送信されます。これは**ENCRYPTION_KEYが設定されている場合にのみ**、保存時に暗号化されて（エンベロープ暗号化）保存されます。そのキーがない場合は、接続パスワードと同様に平文で保存されます。マネージド/クラウドデプロイを含むすべての環境で動作します。
サーバーファイルパス: キーはすでにモニターサーバーのファイルシステム上にあり、パスで参照されます。これには、許可されたキーを保持するディレクトリに BETTERDB_SSH_KEY_DIR 環境変数を設定する必要があり、参照されるパスはそのディレクトリ内に解決される必要があります。これにより、APIが任意のファイルを読み取るように強制されることは決してありません。このオプションを無効にするには、BETTERDB_SSH_KEY_DIR を未設定のままにします。

オプションで、接続にSSHサーバーのホストキーフィンガープリント（SHA256:...）を固定できます。設定すると、サーバーが一致するキーを提示しない限りトンネルは拒否され、踏み台パスでの中間者攻撃を防ぎます。空白のままにすると、サーバーIDは検証されません（警告がログに記録されます）。

トンネルは 127.0.0.1 経由でデータベースに転送します。TLSが有効な場合、証明書は実際のデータベースホスト名に対して引き続き検証されます。SSHパスワード、キーパスフレーズ、インラインキーが保存時に暗号化されるように ENCRYPTION_KEY を設定します。

既知の制限 — クラスター/Sentinelトポロジ: トンネルされるのは、設定した接続のみです。クラスターおよびSentinel監視は、それらのノードがアドバタイズするアドレス（CLUSTER NODES / Sentinel）を使用して他のノードにファンアウトし、それらのノードごとの接続はトンネルを経由せず直接行われます。他のノードが踏み台経由でのみ到達可能な場合（例: プライベートサブネット内のElastiCache/MemoryDB）、ノードごとのビューは利用できません。SSHトンネルはシングルノード/プライマリ監視に使用するか、クラスターノードに直接到達できる場所にモニターを配置してください。

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

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

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

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

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

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

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

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** で実行されるため、
> 新しく作成したボリュームは（上記のように）`chown` で所有者を変更する必要があります。そうしないと、
> `EACCES … license.jwt` で永続化が失敗します。

完全なフロー、検証の優先順位、キーローテーションのランブックについては、
**[オフラインおよびエアギャップライセンス](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** と
**[設定リファレンス](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)** を参照してください。

### Docker イメージの詳細

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

### コンテナ操作```bash
docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

ストレージバックエンド

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

バックエンド	ユースケース	備考
`memory`	テスト、一時的な環境	Dockerでのデフォルト。再起動するとすべてのデータが失われます
`postgres`	本番環境	`STORAGE_TYPE=postgres` + `STORAGE_URL=postgresql://user:pass@host:port/db`
`sqlite`	ローカル開発 / CLI	Docker本番イメージには含まれていません。`STORAGE_SQLITE_FILEPATH` は任意です

Prometheusメトリクス

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

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

完全なメトリクスリファレンス: [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) および [docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/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/ を参照してください。

パッケージ	言語	レジストリ
`@betterdb/monitor`	TypeScript	npm
`@betterdb/mcp`	TypeScript	npm
`@betterdb/agent`	TypeScript	npm
`@betterdb/semantic-cache`	TypeScript	npm
`betterdb-semantic-cache`	Python	PyPI
`@betterdb/agent-cache`	TypeScript	npm
`betterdb-agent-cache`	Python	PyPI
`cache-benchmark`	Python	セマンティックキャッシュのベンチマーク用リプレイハーネス

技術スタック

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

ローカルセットアップ

前提条件: Node.js >= 20.0.0、pnpm >= 9.0.0、Docker。```bash pnpm install cp .env.example .env pnpm docker:dev # local Valkey (6380) and Redis (6382) pnpm dev # web on :5173, api on :3001

Redisの代わりにValkeyへ接続するには、`.env`で`DB_PORT=6382`を設定してください。```bash
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イメージのビルド:```bash 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の厳格モード、明示的な戻り値の型、`any` の禁止
- ESLint + Prettier を設定済み

## ライセンス

- `docs/` 配下のコンテンツは CC BY-SA 4.0 でライセンスされています。
- `proprietary/` 配下のコンテンツは商用ライセンスの対象です（`proprietary/LICENSE` を参照）。これらの機能は早期アクセス期間中は無料です。
- その他はすべて [MIT](https://github.com/betterdb-inc/monitor/blob/master/LICENSE) です。

monitor v0.33.0

カテゴリ