BetterDB Monitor

Valkey에 걸맞은 모니터링 계층.

BetterDB는 Valkey가 버려버리는 것들 - slowlog, 명령 패턴, 클라이언트 활동, 이상 징후 신호 - 을 영속화하여, 새벽 3시에 무슨 일이 있었는지 디버깅할 수 있게 해줍니다. 단순히 지금 무슨 일이 일어나고 있는지가 아니라 말이죠. COMMANDLOG, CLUSTER SLOT-STATS, 스레드별 I/O 메트릭을 기본 지원하는 Valkey 8.x를 위해 만들어졌습니다. 그 외의 모든 기능은 Redis 6+와 호환됩니다.

웹사이트 | Docker Hub | npm | 문서 | 블로그

BetterDB는 OCV Open Charter에 따라 운영되는 공익 기업인 BetterDB Inc.가 만들었습니다.

빠른 시작 (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를 추가하여 이름이 해석되도록 하세요. 대시보드의 원클릭 "로컬 인스턴스에 연결" 버튼은 이를 자동으로 감지하여 올바른 호스트를 미리 채워줍니다.

두 가지 이미지 변형이 게시되며, 둘 다 멀티 아키텍처(linux/amd64, linux/arm64)를 지원합니다:

태그	설명
latest, X.Y.Z-no-ai	기본 이미지 - 실험적 로컬 LLM AI Helper용 의존성 없이 모든 모니터링 기능 포함
X.Y.Z	실험적 AI Helper 추가 (자체 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

그런 다음 `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001`를 실행하고 `http://localhost:3001`을 열거나, 차트의 ingress를 활성화하세요. PostgreSQL 기반 히스토리, bring-your-own 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, 단편화에 대한 한계 도달 예상 시간.
- **웹훅** - 재시도 및 전체 전송 로그를 갖춘 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 상태와 상관됩니다. [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md)를 참조하세요.

### 모든 것에 연결

- **MCP 서버** - [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp)를 통해 Claude Code, Cursor 또는 모든 MCP 클라이언트를 위한 60개 도구.
- **Prometheus 엔드포인트** - 100개 이상의 `betterdb_*` 메트릭. [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md)를 참조하세요.
- **OpenTelemetry** - OTLP 트레이스를 수집하고, 메트릭과 이벤트를 모든 OTLP 백엔드로 미러링합니다. [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md)를 참조하세요.
- **REST API** - UI의 모든 것이 API 호출이며, OpenAPI로 문서화되어 있습니다.

## 원하는 방식으로 데이터에 접근

| 인터페이스 | 세부 정보 |
|-----------|---------|
| 웹 UI | `http://localhost:3001` |
| MCP 서버 | `npx @betterdb/mcp` (stdio) - Settings → MCP Tokens에서 토큰 생성 (클라우드에서는 필수, 셀프 호스팅에서는 선택) |
| 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` 응답에서 Valkey와 Redis를 자동 감지합니다(`DB_TYPE=auto`). 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 인스턴스 (또는 메모리 저장소 사용)