브라우저에서 `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

그런 다음 `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

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](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) - 설정 → 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

### 호스트 네트워크로 실행 (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

`GET /api/license/status`로 확인 → `source: offline-token`, `mode: offline`,
`airGapped: true`.

> **지속성(Persistence):** `/app/data`에 쓰기 가능한 볼륨을 마운트하여 오프라인 라이선스와
> 온라인 장애 유예 토큰이 재시작 후에도 유지되도록 하세요. 컨테이너는 **UID 1001**로 실행되므로,
> 새로 생성된 볼륨은 해당 UID로 `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 이미지 세부 정보

- **기본 이미지(Base Image)**: `node:20-alpine`
- **압축 크기**: 약 360MB(`latest` / `-no-ai`) / 약 640MB(실험적 AI Helper의 로컬 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

전체 메트릭 참조: [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

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

### 새 기능 추가

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)입니다.