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)

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

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

영구 저장소, 사용자 지정 포트, 라이선스 및 에어갭(네트워크 분리) 구성은 Docker 프로덕션 배포를 참조하세요.

빠른 시작(CLI)

Docker 없이 BetterDB Monitor 실행:

npx @betterdb/monitor

첫 실행 시 대화형 설정 마법사가 데이터베이스 연결, 저장소 백엔드(SQLite, PostgreSQL 또는 인메모리) 및 서버 설정을 안내합니다. 구성은 ~/.betterdb/config.json에 저장됩니다.

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도 필요합니다.

제공 기능

모든 것을 확인하고, 모든 것을 보관하세요

• 과거 분석 - 모든 시간 범위에 걸쳐 slowlog, 커맨드 패턴, 클라이언트 활동 및 지연 시간을 조회할 수 있습니다. 로그 순환 후 사라지곤 했던 데이터입니다.
• 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 및 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의 모든 기능은 OpenAPI로 문서화된 API 호출입니다.

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

참고: 프로덕션 빌드(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 내보내기, 웹훅 튜닝 및 상태 게이트 임계값을 포함한 전체 참조: docs/configuration.md.

라이선스 및 에어갭 지원

BetterDB Monitor는 호스트의 인터넷 접속 여부에 따라 다음 두 가지 방식 중 하나로 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가 설정되지 않은 경우, 모니터는 아웃바운드 요청을 전혀 보내지 않습니다 - 라이선스 확인, 텔레메트리 및 업데이트 핑이 모두 비활성화됩니다. 토큰이 만료될 때까지(영구 라이선스는 매년 재다운로드) 부여된 티어로 실행된 후 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        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

저장소 백엔드

BetterDB Monitor는 감사 추적, 분석, 캡처 및 이상 징후 데이터를 다음 세 가지 백엔드 중 하나에 영속화합니다:

Prometheus 메트릭

메트릭은 Prometheus 텍스트 형식으로 GET /api/prometheus/metrics에서 제공됩니다: 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/를 참조하세요.

기술 스택

• 백엔드: NestJS + Fastify 어댑터, Valkey/Redis 연결용 iovalkey, TypeScript strict 모드. 포트 3001.
• 프론트엔드: React + TypeScript, Vite, TailwindCSS, Recharts. 개발 서버 포트 5173.
• 모노레포: pnpm 워크스페이스 + 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입니다.