Skip to content
Back to search

monitor

Real-time monitoring, slowlog analysis, and audit trails for Valkey and Redis

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/BetterDB-inc/monitor with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/BetterDB-inc/monitor'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/betterdb-inc--monitor/badge.svg)](/listings/betterdb-inc--monitor)

HTML

<a href="/listings/betterdb-inc--monitor"><img src="/api/listings/betterdb-inc--monitor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

Point your browser to `http://localhost:3001`. To monitor a specific instance:

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

> **Connecting to a database on your host machine?** Inside the container > `localhost` is the container itself, not your host — so use > `host.docker.internal` as the database host. On **Docker Desktop > (macOS/Windows)** it works out of the box; on **Linux** add > `--add-host=host.docker.internal:host-gateway` to the `docker run` command so > the name resolves. The dashboard's one-click "connect to local instance" > button auto-detects this and pre-fills the right host for you.

Two image variants are published, both multi-arch (`linux/amd64`, `linux/arm64`):

| Tag | What it is | |-----|------------| | `latest`, `X.Y.Z-no-ai` | Default image - every monitoring feature included, without the dependencies for the experimental local-LLM AI Helper | | `X.Y.Z` | Adds the experimental AI Helper (bring your own Ollama; disabled by default via `AI_ENABLED`) |

See [Docker Production Deployment](#docker-production-deployment) for persistent storage, custom ports, licensing, and air-gapped setups.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 26 lines
  1. {
  2. "name": "betterdb",
  3. "description": "BetterDB plugins for Claude Code",
  4. "owner": {
  5. "name": "BetterDB Inc.",
  6. "url": "https://betterdb.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "betterdb",
  11. "source": {
  12. "source": "git-subdir",
  13. "url": "https://github.com/BetterDB-inc/monitor.git",
  14. "path": "packages/mcp/claude-plugin",
  15. "ref": "master"
  16. },
  17. "description": "Valkey and Redis observability from BetterDB Monitor",
  18. "category": "monitoring",
  19. "tags": [
  20. "valkey",
  21. "redis",
  22. "observability"
  23. ]
  24. }
  25. ]
  26. }
README.md · README · 439 lines
  1. # BetterDB Monitor
  2. [![Docker Pulls](https://img.shields.io/docker/pulls/betterdb/monitor)](https://hub.docker.com/r/betterdb/monitor)
  3. [![Docker Image Version](https://img.shields.io/docker/v/betterdb/monitor?sort=semver&label=docker)](https://hub.docker.com/r/betterdb/monitor/tags)
  4. [![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/betterdb-monitor)](https://artifacthub.io/packages/search?repo=betterdb-monitor)
  5. [![npm](https://img.shields.io/npm/v/%40betterdb%2Fmonitor?label=npm)](https://www.npmjs.com/package/@betterdb/monitor)
  6. [![npm downloads](https://img.shields.io/npm/dm/%40betterdb%2Fmonitor)](https://www.npmjs.com/package/@betterdb/monitor)
  7. [![API Tests](https://github.com/betterdb-inc/monitor/actions/workflows/api-tests.yml/badge.svg)](https://github.com/betterdb-inc/monitor/actions/workflows/api-tests.yml)
  8. [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commercial-blue)](LICENSE)
  9. [![Valkey](https://img.shields.io/badge/Valkey-8.x%20native-6a5acd)](https://valkey.io)
  10. [![Redis](https://img.shields.io/badge/Redis-6%2B%20compatible-d82c20)](https://redis.io)
  11. **The monitoring layer that Valkey deserves.**
  12. BetterDB persists what Valkey throws away - slowlogs, command patterns, client activity, anomaly signals - so you can debug what happened at 3am, not just what's happening now. Built for Valkey 8.x with native support for COMMANDLOG, CLUSTER SLOT-STATS, and per-thread I/O metrics. Redis 6+ compatible for everything else.
  13. [Website](https://betterdb.com) | [Docker Hub](https://hub.docker.com/r/betterdb/monitor) | [npm](https://www.npmjs.com/package/@betterdb/monitor) | [Documentation](https://docs.betterdb.com) | [Blog](https://betterdb.com/blog)
  14. BetterDB is built by [BetterDB Inc.](https://betterdb.com), a public benefit company operating under the [OCV Open Charter](https://github.com/OpenCoreVentures/ocv-public-benefit-company).
  15. ![BetterDB Monitor - Key Analytics with per-type key size distribution histograms](docs/assets/readme-hero.png)
  16. ## Quick Start (Docker)
  17. ```bash
  18. docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest
  19. ```
  20. Point your browser to `http://localhost:3001`. To monitor a specific instance:
  21. ```bash
  22. docker run -d \
  23. --name betterdb \
  24. -p 3001:3001 \
  25. -e DB_HOST=your-valkey-host \
  26. -e DB_PORT=6379 \
  27. -e DB_PASSWORD=your-password \
  28. betterdb/monitor:latest
  29. ```
  30. > **Connecting to a database on your host machine?** Inside the container
  31. > `localhost` is the container itself, not your host — so use
  32. > `host.docker.internal` as the database host. On **Docker Desktop
  33. > (macOS/Windows)** it works out of the box; on **Linux** add
  34. > `--add-host=host.docker.internal:host-gateway` to the `docker run` command so
  35. > the name resolves. The dashboard's one-click "connect to local instance"
  36. > button auto-detects this and pre-fills the right host for you.
  37. Two image variants are published, both multi-arch (`linux/amd64`, `linux/arm64`):
  38. | Tag | What it is |
  39. |-----|------------|
  40. | `latest`, `X.Y.Z-no-ai` | Default image - every monitoring feature included, without the dependencies for the experimental local-LLM AI Helper |
  41. | `X.Y.Z` | Adds the experimental AI Helper (bring your own Ollama; disabled by default via `AI_ENABLED`) |
  42. See [Docker Production Deployment](#docker-production-deployment) for persistent storage, custom ports, licensing, and air-gapped setups.
  43. ## Quick Start (Kubernetes / Helm)
  44. ```bash
  45. helm repo add betterdb https://docs.betterdb.com/charts
  46. helm repo update
  47. helm install betterdb-monitor betterdb/betterdb-monitor \
  48. --namespace betterdb --create-namespace \
  49. --set db.host=my-valkey.default.svc.cluster.local \
  50. --set db.password=yourpassword
  51. ```
  52. Then `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` and open `http://localhost:3001`, or enable the chart's ingress. PostgreSQL-backed history, bring-your-own Secrets, and air-gapped licensing are all covered in the [Kubernetes guide](https://docs.betterdb.com/kubernetes) and the [chart README](charts/betterdb-monitor/README.md).
  53. ## Quick Start (CLI)
  54. Run BetterDB Monitor without Docker:
  55. ```bash
  56. npx @betterdb/monitor
  57. ```
  58. On first run, an interactive setup wizard guides you through database connection, storage backend (SQLite, PostgreSQL, or in-memory), and server settings. Configuration is saved to `~/.betterdb/config.json`.
  59. ```bash
  60. npm install -g @betterdb/monitor # global install
  61. betterdb --setup # re-run setup wizard
  62. betterdb --port 8080 # override server port
  63. betterdb --db-host 1.2.3.4 # override database host
  64. betterdb --help # all options
  65. ```
  66. Requires Node.js >= 20.0.0 and a Valkey or Redis instance to monitor. For SQLite storage, also `npm install -g better-sqlite3`.
  67. ## What You Get
  68. ### See everything, keep everything
  69. - **Historical analytics** - query slowlogs, command patterns, client activity, and latency across any time range. The data that used to disappear after a log rotation.
  70. - **COMMANDLOG support** - Valkey 8.1+ exclusive. Large requests and large replies, not just the slow ones.
  71. - **MONITOR capture sessions** - record real traffic on demand: live tail, filter, replay, export to JSON/CSV, and cross-reference against connection history.
  72. - **Hot key tracking** - top keys by access frequency with rank movement over time. Key Analytics (Pro, free in early access) adds type, TTL, and size distributions from live sampling.
  73. - **Cluster visibility** - topology graphs, SLOT-STATS heatmaps, per-slot CPU and key distribution.
  74. - **Cluster auto-registration** - a cluster connection can auto-register every node as its own monitored connection, kept in sync as the cluster scales. See [docs/cluster-auto-registration.md](docs/cluster-auto-registration.md).
  75. - **CPU & I/O thread metrics** - per-thread visibility that no Redis tool can provide.
  76. - **Client analytics** - see exactly which service is responsible for what, attributed by client name and pattern.
  77. - **ACL audit trail** - track who accessed what, persisted for compliance and post-incident debugging.
  78. ### Understand and act
  79. - **Anomaly detection** (Pro, free in early access) - automatic baseline learning with correlated events and plain-English diagnoses. 20+ detectors, no manual thresholds.
  80. - **Capacity forecasting** - projected time-to-ceiling for memory, ops/sec, CPU, and fragmentation.
  81. - **Webhooks** - HMAC-signed alert deliveries with retries and a full delivery log.
  82. - **Live migration** - move between Redis and Valkey, self-hosted or managed (ElastiCache node-based or Serverless, MemoryDB, Redis Cloud, Upstash), standalone or cluster (a cluster source needs a cluster target). Three-phase analysis, execution, and validation workflow, with PSYNC-based continuous replication for near-zero-downtime cutovers when the source permits replication commands. Other RESP-compatible engines such as KeyDB and Dragonfly work in the modes listed in the [engine table](docs/migration.md#other-engines); they are not part of the test suite. See [docs/migration.md](docs/migration.md).
  83. ### Built for the AI era
  84. - **Vector search observability** - FT.SEARCH ops/sec and latency with per-index health for [valkey-search](https://github.com/valkey-io/valkey-search) and RediSearch. See [docs/vector-ai](docs/vector-ai/README.md).
  85. - **Inference latency** - p50/p95/p99 per index, with SLA breach alerts (Pro, free in early access).
  86. - **Semantic cache intelligence** (Pro, free in early access) - hit-rate health, similarity-threshold recommendations, and an approve/reject proposal workflow. Agent memory observability included.
  87. - **AI traces** - OTLP span waterfalls from your AI application, correlated with the live Valkey state underneath each request. See [docs/opentelemetry.md](docs/opentelemetry.md).
  88. ### Plugs into everything
  89. - **MCP server** - 60 tools for Claude Code, Cursor, or any MCP client via [`@betterdb/mcp`](packages/mcp).
  90. - **Prometheus endpoint** - 100+ `betterdb_*` metrics. See [docs/prometheus-metrics.md](docs/prometheus-metrics.md).
  91. - **OpenTelemetry** - ingest OTLP traces, and mirror metrics and events to any OTLP backend. See [docs/opentelemetry.md](docs/opentelemetry.md).
  92. - **REST API** - everything in the UI is an API call, documented via OpenAPI.
  93. ## Access Your Data Your Way
  94. | Interface | Details |
  95. |-----------|---------|
  96. | Web UI | `http://localhost:3001` |
  97. | MCP server | `npx -y @betterdb/mcp@1.6.0` (stdio) - create a token under Settings → MCP Tokens (required on cloud, optional on self-hosted) |
  98. | Prometheus | `http://localhost:3001/api/prometheus/metrics` |
  99. | REST API (OpenAPI) | `http://localhost:3001/docs` |
  100. | Health check | `http://localhost:3001/api/health` |
  101. > **Note**: In production builds (Docker, CLI) API routes are served under the `/api` prefix. In local development (`pnpm dev`) there is no prefix - e.g. `http://localhost:3001/health`.
  102. ## Supported Databases
  103. | Database | Minimum Version | Supported Features |
  104. |----------|----------------|-------------------|
  105. | **Valkey** | 8.0+ | All features including COMMANDLOG (8.1+) and CLUSTER SLOT-STATS |
  106. | **Redis** | 6+ | All features except the Valkey-exclusive COMMANDLOG and CLUSTER SLOT-STATS |
  107. The backend uses a unified adapter over the wire-compatible `iovalkey` client and auto-detects Valkey vs Redis from the `INFO` response (`DB_TYPE=auto`). Capabilities like COMMANDLOG and SLOT-STATS are detected per version, and the UI gracefully degrades when a feature isn't available.
  108. Managed services are supported too - guides for AWS ElastiCache, MemoryDB, Redis Cloud, and Upstash live in [docs/providers](docs/providers/), and [`@betterdb/agent`](packages/agent) reaches VPC-only instances over an outbound WebSocket.
  109. ## Docker Production Deployment
  110. The Docker image contains the monitoring application (backend + frontend). It requires:
  111. 1. A Valkey/Redis instance to monitor
  112. 2. A PostgreSQL instance for data persistence (or use memory storage)
  113. ### Run with PostgreSQL Storage
  114. ```bash
  115. docker run -d \
  116. --name betterdb-monitor \
  117. -p 3001:3001 \
  118. -e DB_HOST=your-valkey-host \
  119. -e DB_PORT=6379 \
  120. -e DB_PASSWORD=your-password \
  121. -e STORAGE_TYPE=postgres \
  122. -e STORAGE_URL=postgresql://user:pass@postgres-host:5432/dbname \
  123. betterdb/monitor
  124. ```
  125. ### Run on Custom Port
  126. Set the `PORT` environment variable and match the `-p` mapping:
  127. ```bash
  128. docker run -d \
  129. --name betterdb-monitor \
  130. -p 8080:8080 \
  131. -e PORT=8080 \
  132. -e DB_HOST=your-valkey-host \
  133. betterdb/monitor
  134. ```
  135. ### Run with Host Network (Access localhost services)
  136. If your Valkey and PostgreSQL are running on the same host:
  137. ```bash
  138. docker run -d \
  139. --name betterdb-monitor \
  140. --network host \
  141. -e DB_HOST=localhost \
  142. -e DB_PORT=6380 \
  143. -e DB_PASSWORD=devpassword \
  144. -e STORAGE_TYPE=postgres \
  145. -e STORAGE_URL=postgresql://dev:devpass@localhost:5432/postgres \
  146. betterdb/monitor
  147. ```
  148. ### Environment Variables
  149. | Variable | Required | Default | Description |
  150. |----------|----------|---------|-------------|
  151. | `DB_HOST` | Yes | `localhost` | Valkey/Redis host to monitor |
  152. | `DB_PORT` | No | `6379` | Valkey/Redis port |
  153. | `DB_PASSWORD` | No | - | Valkey/Redis password |
  154. | `DB_USERNAME` | No | `default` | Valkey/Redis ACL username |
  155. | `DB_TYPE` | No | `auto` | Database type: `auto`, `valkey`, or `redis` |
  156. | `DB_TLS` | No | `false` | Set to `true` to connect to the monitored database over TLS (required by managed providers such as Aiven or ElastiCache Serverless) |
  157. | `DB_TLS_CA_FILE` | No | - | Path to a PEM CA bundle used to verify the database server certificate. Needed when the server certificate is issued by a private CA (see [Mutual TLS](#mutual-tls-client-certificates)) |
  158. | `DB_TLS_CERT_FILE` | No | - | Path to a PEM client certificate presented to the database (mutual TLS). Use together with `DB_TLS_KEY_FILE` |
  159. | `DB_TLS_KEY_FILE` | No | - | Path to the PEM private key matching `DB_TLS_CERT_FILE` |
  160. | `DB_TLS_KEY_PASSPHRASE` | No | - | Passphrase for `DB_TLS_KEY_FILE`, if the key is encrypted |
  161. | `DB_AUTH_MODE` | No | `password` | `password` sends `AUTH` with `DB_USERNAME`/`DB_PASSWORD`; `certificate` sends no `AUTH` so the server maps the client certificate to an ACL user (Valkey `tls-auth-clients-user`). Requires `DB_TLS=true` and a client certificate + key |
  162. | `STORAGE_TYPE` | No | `memory` | Storage backend: `memory` or `postgres` |
  163. | `STORAGE_URL` | Conditional | - | PostgreSQL connection URL (required if `STORAGE_TYPE=postgres`) |
  164. | `STORAGE_SSL_CA` | No | - | Path (or trusted HTTPS URL) to a CA cert used to verify the PostgreSQL server. For managed providers with their own CA (e.g. Aiven), supply the project CA here for full chain + hostname verification. Takes precedence over `STORAGE_SSL_NO_VERIFY` |
  165. | `STORAGE_SSL_NO_VERIFY` | No | `false` | Connect to PostgreSQL over TLS **without** verifying the server certificate (encrypted but not authenticated). Convenience for managed providers that present their own CA and force `sslmode=require` when you can't supply `STORAGE_SSL_CA`. Prefer `STORAGE_SSL_CA` in production |
  166. | `PORT` | No | `3001` | Application HTTP port |
  167. | `NODE_ENV` | No | `production` | Node environment |
  168. | `ANOMALY_DETECTION_ENABLED` | No | `true` | Enable anomaly detection |
  169. | `ANOMALY_PROMETHEUS_INTERVAL_MS` | No | `30000` | Prometheus summary update interval (ms) |
  170. | `BETTERDB_LICENSE_KEY` | No | - | Online license key (Pro/Enterprise), validated over the network |
  171. | `BETTERDB_OFFLINE_LICENSE_FILE` | No | - | Path to a signed offline license `.jwt` for **air-gapped** hosts (see below) |
  172. | `BETTERDB_OFFLINE_LICENSE` | No | - | Offline license token as an inline JWT string |
  173. | `BETTERDB_DATA_DIR` | No | `/app/data` | Directory for persisted license state (mount a writable volume) |
  174. | `ENCRYPTION_KEY` | No | - | Key (min 16 chars) used to envelope-encrypt stored connection passwords, TLS private keys and SSH tunnel secrets at rest. Without it, secrets are stored in plaintext; rows found in plaintext are re-encrypted on the next start once the key is set. If the key is missing while encrypted rows exist, env-configured credentials are used in memory only and never written back unencrypted |
  175. | `BETTERDB_SSH_KEY_DIR` | No | - | Directory that server-side SSH private keys must live in. Enables the "server file path" key source for [SSH tunnels](#ssh-tunnels); a connection's key path must resolve inside it. Unset disables file-based keys (inline pasted keys still work) |
  176. | `BETTERDB_TLS_CERT_DIR` | No | - | Directory that server-side TLS files (CA bundle, client certificate, key) must live in. Enables the "server file paths" source for [mutual TLS](#mutual-tls-client-certificates) on UI-added connections; a connection's paths must resolve inside it. Unset disables file paths (pasted PEM still works) |
  177. | `BETTERDB_TELEMETRY` | No | `true` | Set `false` to disable anonymous telemetry |
  178. Full reference, including AI, webhook tuning, and health-gate thresholds: [docs/configuration.md](docs/configuration.md). For OTLP trace ingest and metrics/event export, see [docs/opentelemetry.md](docs/opentelemetry.md).
  179. ### Mutual TLS (client certificates)
  180. When **Use TLS** is on, a connection can also carry TLS material:
  181. - a **CA bundle** so the server certificate is verified against a private PKI instead of the public CA store, and
  182. - a **client certificate + private key** that BetterDB presents during the handshake (mutual TLS), for servers that run `tls-auth-clients yes`.
  183. The certificate is passed to the TLS socket exactly as supplied, so its subject (CN) is whatever your CA issued. Material is either **pasted as PEM** (the private key and passphrase are encrypted at rest when `ENCRYPTION_KEY` is set) or referenced by **server file paths** inside `BETTERDB_TLS_CERT_DIR`, the same allowlist model as SSH keys. The env-configured default connection takes the same material from `DB_TLS_CA_FILE`, `DB_TLS_CERT_FILE`, `DB_TLS_KEY_FILE` and `DB_TLS_KEY_PASSPHRASE`.
  184. **Certificate-only authentication.** Valkey can map a field of the client certificate to an ACL user (`tls-auth-clients-user`). For that mapping to hold, the client must not send `AUTH` afterwards, which would re-authenticate the session as a different user or fail outright. Choose **Client certificate (mTLS)** as the authentication method (or `DB_AUTH_MODE=certificate`) and BetterDB sends no `AUTH` at all; username and password are ignored. BetterDB then runs `ACL WHOAMI` after connecting and shows the resolved user in the connection test result and in the connection status (`authenticatedUser`), so you can confirm the certificate mapped to the intended account rather than falling back to `default`.
  185. Cluster and Sentinel nodes discovered from a seed connection reuse the seed's CA, client certificate and authentication mode. Server certificate verification is always on; there is no option to disable it.
  186. **Rotation.** File-sourced material (`BETTERDB_TLS_CERT_DIR` paths, and the `DB_TLS_*_FILE` paths of the env-configured connection) is watched for changes: the files are stat-checked at most every few seconds when a socket is opened and re-read when they changed, so a replaced certificate is presented by every new connection (reconnects, key-analytics scans, the CLI, discovered cluster nodes) without a restart. New material is checked to parse as a matching certificate and key before it is adopted, so a rotation caught between writing the two files keeps the previous pair until both are in place. Already-open sockets keep running on the old handshake until they reconnect; use `POST /connections/{id}/reconnect` to force that. While `DB_HOST` is set, the env-configured default connection and the nodes auto-registered from it are rebuilt from the current `DB_*` settings on every start, so a changed username, password, `DB_TLS`, certificate paths or `DB_AUTH_MODE` always win over the stored copy (connections you created yourself keep their own settings, even when they were adopted into the default's topology). Pasted PEM is fixed at save time; re-create the connection to rotate it.
  187. ### SSH Tunnels
  188. Connections can reach a database through an SSH bastion/jump host instead of connecting directly — useful for Valkey/Redis in a private subnet, ElastiCache, or MemoryDB. Enable **Connect via SSH tunnel** when adding a connection and provide the SSH host, port, and username. A single hop is supported.
  189. Authentication is either a password or a private key. Private keys come from one of two sources:
  190. - **Paste key** (inline): the PEM key content is submitted with the connection. It is stored encrypted at rest **only when `ENCRYPTION_KEY` is set** (envelope encryption); without that key it is stored in plaintext, like connection passwords. Works everywhere, including managed/cloud deployments.
  191. - **Server file path**: the key already lives on the monitor server's filesystem and is referenced by path. This requires setting the `BETTERDB_SSH_KEY_DIR` environment variable to the directory holding the allowed keys, and the referenced path must resolve inside it, so the API can never be coerced into reading arbitrary files. Leave `BETTERDB_SSH_KEY_DIR` unset to disable this option.
  192. Optionally pin the SSH server's **host key fingerprint** (`SHA256:...`) on the connection; when set, the tunnel is refused unless the server presents a matching key, preventing man-in-the-middle attacks on the bastion path. Left blank, the server identity is not verified (a warning is logged).
  193. The tunnel forwards to the database over `127.0.0.1`; when TLS is enabled the certificate is still validated against the real database hostname. Set `ENCRYPTION_KEY` so SSH passwords, key passphrases, and inline keys are encrypted at rest.
  194. **Known limitation — cluster/Sentinel topologies:** only the connection you configure is tunnelled. Cluster and Sentinel monitoring fan out to the other nodes using the addresses those nodes advertise (`CLUSTER NODES` / Sentinel), and those per-node connections are made directly, not through the tunnel. If the other nodes are only reachable via the bastion (e.g. ElastiCache/MemoryDB in a private subnet), per-node views will be unavailable. Use SSH tunnels for single-node/primary monitoring, or place the monitor where it can reach the cluster nodes directly.
  195. ### Licensing & Air-Gapped Support
  196. BetterDB Monitor unlocks Pro/Enterprise features in one of two ways, depending on
  197. whether the host has internet access:
  198. - **Online license key** - set `BETTERDB_LICENSE_KEY`. The monitor validates it
  199. against `betterdb.com` and caches a locally-verified **signed token**, so your
  200. tier keeps working through short outages and restarts.
  201. - **Offline / air-gapped license token** - for hosts with **no internet access at
  202. all** (see below).
  203. #### How air-gapped licensing works
  204. Every entitlement is a **signed RS256 JWT**. The monitor verifies it **locally**
  205. against public keys embedded in the image - it never has to reach a license server
  206. to trust a token. So an air-gapped host can run paid tiers with zero connectivity:
  207. 1. On an internet-connected machine, sign in at
  208. [betterdb.com/account/licenses](https://www.betterdb.com/account/licenses) and
  209. **download your offline license token** (`.jwt`, Pro/Enterprise). It contains no
  210. secrets and can't be tampered with - any edit breaks the signature.
  211. 2. Transfer it to the air-gapped host however you like (USB, config management, a
  212. Docker/Kubernetes secret mount).
  213. 3. Provide it via `BETTERDB_OFFLINE_LICENSE_FILE` (path), `BETTERDB_OFFLINE_LICENSE`
  214. (inline string), or paste it in the UI under **Settings → License → "Air-gapped
  215. environment? Activate an offline license."**
  216. When an offline token is configured and **no** `BETTERDB_LICENSE_KEY` is set, the
  217. monitor makes **zero outbound requests** - license checks, telemetry, and update
  218. pings are all disabled. It runs the granted tier until the token expires (perpetual
  219. licenses re-download yearly), then reverts to Community.
  220. ```bash
  221. # fully offline - no network required
  222. docker volume create betterdb-data
  223. docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d # volume writable by UID 1001 (one-time)
  224. docker run -d --name betterdb-monitor -p 3001:3001 \
  225. -e DB_HOST=your-valkey-host -e DB_PORT=6379 -e DB_PASSWORD=your-password \
  226. -v /path/to/betterdb-license.jwt:/run/secrets/betterdb-license.jwt:ro \
  227. -e BETTERDB_OFFLINE_LICENSE_FILE=/run/secrets/betterdb-license.jwt \
  228. -v betterdb-data:/app/data \
  229. betterdb/monitor
  230. ```
  231. Verify with `GET /api/license/status` → `source: offline-token`, `mode: offline`,
  232. `airGapped: true`.
  233. > **Persistence:** mount a writable volume at `/app/data` so the offline license and
  234. > the online outage-grace token survive restarts. The container runs as **UID 1001**,
  235. > so a freshly-created volume must be `chown`ed to it (shown above) - otherwise
  236. > persistence fails with `EACCES … license.jwt`.
  237. For the full flow, verification precedence, and key-rotation runbook see
  238. **[Offline & Air-Gapped Licenses](docs/offline-licenses.md)** and the
  239. **[Configuration reference](docs/configuration.md#license-configuration)**.
  240. ### Docker Image Details
  241. - **Base Image**: `node:20-alpine`
  242. - **Compressed size**: ~360MB (`latest` / `-no-ai`) / ~640MB (versioned image with the experimental AI Helper's local-LLM dependencies)
  243. - **Platforms**: `linux/amd64`, `linux/arm64`
  244. - **Contains**: Backend API + Frontend static files (served by Fastify)
  245. - **Excluded**: SQLite support (use PostgreSQL or Memory storage)
  246. ### Container Operations
  247. ```bash
  248. docker logs -f betterdb-monitor # follow logs
  249. docker stop betterdb-monitor # stop
  250. docker rm betterdb-monitor # remove
  251. ```
  252. ## Storage Backends
  253. BetterDB Monitor persists audit trail, analytics, captures, and anomaly data to one of four backends:
  254. | Backend | Use case | Notes |
  255. |---------|----------|-------|
  256. | `memory` | Testing, ephemeral environments | Default in Docker; all data lost on restart |
  257. | `postgres` | Production | `STORAGE_TYPE=postgres` + `STORAGE_URL=postgresql://user:pass@host:port/db` |
  258. | `turso` | Production / serverless SQLite | `STORAGE_TYPE=turso` + `STORAGE_URL=libsql://...` + `STORAGE_AUTH_TOKEN`; works in Docker |
  259. | `sqlite` | Local development / CLI | Native module stripped from the `latest` Docker image; `STORAGE_SQLITE_FILEPATH` optional |
  260. ## Prometheus Metrics
  261. Metrics are exposed at `GET /api/prometheus/metrics` in Prometheus text format: ACL audit, client connections, slowlog/commandlog patterns, memory, throughput, keyspace, replication, cluster slot stats, and Node.js runtime metrics - all prefixed `betterdb_`.
  262. ```yaml
  263. scrape_configs:
  264. - job_name: 'betterdb-monitor'
  265. metrics_path: '/api/prometheus/metrics'
  266. static_configs:
  267. - targets: ['your-monitor-host:3001']
  268. ```
  269. Full metric reference: [docs/prometheus-metrics.md](docs/prometheus-metrics.md) and [docs/prometheus-integration.md](docs/prometheus-integration.md).
  270. ## Development
  271. ### Project Structure
  272. ```
  273. betterdb-monitor/
  274. ├── apps/
  275. │ ├── api/ # NestJS backend (Fastify)
  276. │ └── web/ # React frontend (Vite)
  277. ├── packages/ # Published packages (see below)
  278. ├── docs/ # Documentation site (Jekyll)
  279. ├── docker-compose.yml # Local Valkey (port 6380) and Redis (port 6382) for testing
  280. └── package.json # Workspace root
  281. ```
  282. ### Packages
  283. This monorepo ships several standalone packages. See [`packages/`](packages/) for the full list.
  284. | Package | Language | Registry |
  285. |---|---|---|
  286. | [`@betterdb/monitor`](packages/cli) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/monitor) |
  287. | [`@betterdb/mcp`](packages/mcp) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/mcp) |
  288. | [`@betterdb/agent`](packages/agent) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/agent) |
  289. | [`@betterdb/semantic-cache`](packages/semantic-cache) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/semantic-cache) |
  290. | [`betterdb-semantic-cache`](packages/semantic-cache-py) | Python | [PyPI](https://pypi.org/project/betterdb-semantic-cache/) |
  291. | [`@betterdb/agent-cache`](packages/agent-cache) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/agent-cache) |
  292. | [`betterdb-agent-cache`](packages/agent-cache-py) | Python | [PyPI](https://pypi.org/project/betterdb-agent-cache/) |
  293. | [`cache-benchmark`](packages/cache-benchmark) | Python | Replay harness for benchmarking semantic caches |
  294. ### Tech Stack
  295. - **Backend**: NestJS with Fastify adapter, `iovalkey` for Valkey/Redis connections, TypeScript strict mode. Port **3001**.
  296. - **Frontend**: React + TypeScript, Vite, TailwindCSS, Recharts. Dev server on port **5173**.
  297. - **Monorepo**: pnpm workspaces + Turborepo.
  298. ### Local Setup
  299. Prerequisites: Node.js >= 20.0.0, pnpm >= 9.0.0, Docker.
  300. ```bash
  301. pnpm install
  302. cp .env.example .env
  303. pnpm docker:dev # local Valkey (6380) and Redis (6382)
  304. pnpm dev # web on :5173, api on :3001
  305. ```
  306. To connect to Redis instead of Valkey, set `DB_PORT=6382` in `.env`.
  307. ```bash
  308. pnpm dev:api # API only
  309. pnpm dev:web # frontend only
  310. pnpm docker:dev:down # stop local databases
  311. pnpm build # production build
  312. pnpm test # API tests
  313. ```
  314. Docker image builds:
  315. ```bash
  316. pnpm docker:build # local build
  317. pnpm docker:publish # multi-arch build & push (requires buildx)
  318. ```
  319. ### Adding New Features
  320. 1. Add new endpoints in `apps/api/src/`
  321. 2. Add corresponding API calls in `apps/web/src/api/`
  322. 3. Add shared types in `packages/shared/src/types/`
  323. ### Code Style
  324. - TypeScript strict mode, explicit return types, no `any`
  325. - ESLint + Prettier configured
  326. ## License
  327. - Content under `docs/` is licensed under CC BY-SA 4.0.
  328. - Content under `proprietary/` is covered by a commercial license (see `proprietary/LICENSE`). These features are free during early access.
  329. - Everything else is [MIT](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.