BetterDB Monitor

طبقة المراقبة التي يستحقها Valkey.

BetterDB يحفظ ما يتجاهله Valkey - سجلات الاستعلامات البطيئة (slowlogs)، أنماط الأوامر، نشاط العملاء، إشارات الحالات الشاذة - حتى تتمكن من تصحيح الأخطاء لما حدث في الساعة 3 صباحًا، وليس فقط ما يحدث الآن. مبني لـ Valkey 8.x مع دعم أصلي لـ COMMANDLOG وCLUSTER SLOT-STATS ومقاييس I/O لكل خيط. متوافق مع Redis 6+ لكل ما عدا ذلك.

الموقع | Docker Hub | npm | التوثيق | المدونة

تم بناء BetterDB بواسطة BetterDB Inc.، وهي شركة منفعة عامة تعمل بموجب OCV Open Charter.

بدء سريع (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)

شغّل BetterDB Monitor دون Docker:

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.

ما الذي ستحصل عليه

شاهد كل شيء واحتفظ بكل شيء

• تحليلات تاريخية - استعلم عن سجلات الاستعلامات البطيئة وأنماط الأوامر ونشاط العملاء وزمن الاستجابة عبر أي نطاق زمني. البيانات التي كانت تختفي بعد تدوير السجلات.
• دعم COMMANDLOG - حصري لـ Valkey 8.1+. الطلبات الكبيرة والردود الكبيرة، وليس البطيئة فقط.
• جلسات التقاط MONITOR - سجّل حركة المرور الحقيقية عند الطلب: تتبّع مباشر (live tail)، تصفية، إعادة تشغيل (replay)، تصدير إلى JSON/CSV، وإسناد مرجعي متقاطع مع سجل الاتصالات.
• تتبع المفاتيح الساخنة - أهم المفاتيح حسب تكرار الوصول مع تغيّر الترتيب بمرور الوقت. تحليلات المفاتيح (Pro، مجانية في الوصول المبكر) تضيف توزيعات النوع وTTL والحجم من أخذ العينات المباشر.
• رؤية المجموعات (Cluster) - رسوم بيانية للطوبولوجيا، خرائط حرارية لـ SLOT-STATS، وتوزيع CPU والمفاتيح لكل فتحة (slot).
• مقاييس خيوط CPU وI/O - رؤية لكل خيط لا يوفرها أي أداة Redis.
• تحليلات العملاء - اعرف بالضبط أي خدمة مسؤولة عن ماذا، منسوبة حسب اسم العميل والنمط.
• مسار تدقيق ACL - تتبّع من وصل إلى ماذا، مع الحفظ للامتثال وتصحيح الأخطاء بعد الحوادث.

افهم وتصرّف

• اكتشاف الحالات الشاذة (Pro، مجاني في الوصول المبكر) - تعلّم تلقائي للخط الأساسي مع أحداث مترابطة وتشخيصات بلغة واضحة ومبسطة. أكثر من 20 كاشفًا، دون عتبات يدوية.
• التنبؤ بالسعة - الوقت المتوقع للوصول إلى السقف للذاكرة والعمليات في الثانية وCPU والتجزئة.
• Webhooks - تسليم تنبيهات موقّعة بـ HMAC مع إعادة محاولة وسجل تسليم كامل.
• الترحيل المباشر - الانتقال بين Redis وValkey عبر سير عمل من ثلاث مراحل: التحليل والتنفيذ والتحقق.

مبني لعصر الذكاء الاصطناعي

• مراقبة البحث المتجهي - عمليات FT.SEARCH في الثانية وزمن الاستجابة مع صحة لكل فهرس لـ valkey-search وRediSearch. انظر docs/vector-ai.
• زمن استجابة الاستدلال - p50/p95/p99 لكل فهرس، مع تنبيهات اختراق SLA (Pro، مجاني في الوصول المبكر).
• ذكاء الذاكرة المؤقتة الدلالية (Pro، مجاني في الوصول المبكر) - صحة معدل النجاح، توصيات عتبة التشابه، وسير عمل اقتراحات بالموافقة/الرفض. تشمل مراقبة ذاكرة الوكيل.
• تتبعات الذكاء الاصطناعي - مخططات شلال OTLP للمدد (spans) من تطبيق الذكاء الاصطناعي الخاص بك، مرتبطة بحالة Valkey المباشرة تحت كل طلب.

يتكامل مع كل شيء

• خادم MCP - 60 أداة لـ Claude Code أو Cursor أو أي عميل MCP عبر @betterdb/mcp.
• نقطة نهاية Prometheus - أكثر من 100 مقياس betterdb_*. انظر docs/prometheus-metrics.md.
• OpenTelemetry - عكس المقاييس والأحداث إلى أي خلفية OTLP.
• REST API - كل شيء في الواجهة هو استدعاء API، موثّق عبر OpenAPI.

الوصول إلى بياناتك بالطريقة التي تناسبك

ملاحظة: في الإصدارات الإنتاجية (Docker, CLI) تُقدَّم مسارات API تحت بادئة /api. في التطوير المحلي (pnpm dev) لا توجد بادئة - مثل http://localhost:3001/health.

قواعد البيانات المدعومة

يستخدم الخلفي محوّلًا موحّدًا فوق عميل iovalkey المتوافق على مستوى البروتوكول ويكتشف تلقائيًا Valkey مقابل Redis من استجابة INFO (DB_TYPE=auto). تُكتشف القدرات مثل COMMANDLOG وSLOT-STATS حسب الإصدار، وتتراجع الواجهة برشاقة عندما لا تكون الميزة متاحة.

الخدمات المدارة مدعومة أيضًا - أدلة AWS ElastiCache وMemoryDB وRedis Cloud وUpstash موجودة في docs/providers، و@betterdb/agent يصل إلى النسخ التي لا تتوفر إلا عبر VPC عبر WebSocket صادر.

النشر الإنتاجي عبر 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 وضبط webhook وعتبات بوابة الصحة: docs/configuration.md.

الترخيص ودعم البيئات المعزولة (Air-Gapped)

يفتح BetterDB Monitor ميزات Pro/Enterprise بإحدى طريقتين، اعتمادًا على ما إذا كان المضيف متصلًا بالإنترنت:

• مفتاح ترخيص عبر الإنترنت - عيّن BETTERDB_LICENSE_KEY. يتحقق المراقب منه مقابل betterdb.com ويخزّن مؤقتًا رمزًا موقّعًا يتم التحقق منه محليًا، لذا تبقى فئتك تعمل أثناء الانقطاعات القصيرة وإعادة التشغيل.
• رمز ترخيص دون اتصال / بيئة معزولة - للمضيفات التي لا تملك أي وصول للإنترنت إطلاقًا (انظر أدناه).

كيف يعمل الترخيص في البيئات المعزولة

كل ترخيص هو JWT موقّع بخوارزمية RS256. يتحقق منه المراقب محليًا مقابل مفاتيح عامة مدمجة في الصورة - لا يحتاج أبدًا إلى الوصول إلى خادم ترخيص للثقة برمز. لذا يمكن لمضيف معزول تشغيل الفئات المدفوعة دون أي اتصال:

1. على جهاز متصل بالإنترنت، سجّل الدخول إلى betterdb.com/account/licenses ونزّل رمز الترخيص دون اتصال الخاص بك (.jwt، Pro/Enterprise). لا يحتوي على أسرار ولا يمكن العبث به - أي تعديل يكسر التوقيع.
2. انقله إلى المضيف المعزول بالطريقة التي تريدها (USB، إدارة الإعدادات، تركيب سر Docker/Kubernetes).
3. وفّره عبر BETTERDB_OFFLINE_LICENSE_FILE (مسار) أو BETTERDB_OFFLINE_LICENSE (سلسلة مباشرة) أو الصقه في الواجهة ضمن الإعدادات → الترخيص → "بيئة معزولة عن الشبكة؟ فعّل ترخيصًا دون اتصال".

عندما يتم ضبط رمز دون اتصال ولا يتم تعيين 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، لذا يجب تنفيذ chown على وحدة تخزين جديدة لتكون مملوكة له (كما هو موضح أعلاه) - وإلا فسيفشل الحفظ مع EACCES … license.jwt.

للتدفق الكامل وأولوية التحقق ودليل تدوير المفاتيح انظر التراخيص دون اتصال والمعزولة و مرجع الإعدادات.

تفاصيل صورة Docker

• الصورة الأساسية: node:20-alpine
• الحجم المضغوط: ~360MB (latest / -no-ai) / ~640MB (الصورة المرقّمة مع تبعيات نموذج اللغة المحلي للمساعد الذكي التجريبي)
• المنصات: 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

تُعرض المقاييس في GET /api/prometheus/metrics بصيغة نصوص Prometheus: تدقيق ACL، اتصالات العملاء، أنماط slowlog/commandlog، الذاكرة، الإنتاجية، keyspace، النسخ المتماثل، إحصائيات فتحات المجموعة، ومقاييس بيئة تشغيل 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، وiovalkey لاتصالات Valkey/Redis، ووضع TypeScript الصارم. المنفذ 3001.
• الواجهة الأمامية: React + TypeScript، Vite، TailwindCSS، Recharts. خادم التطوير على المنفذ 5173.
• المستودع الأحادي: pnpm workspaces + 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

للاتصال بـ Redis بدل Valkey، عيّن DB_PORT=6382 في .env.

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. أضف استدعاءات API المقابلة في apps/web/src/api/
3. أضف الأنواع المشتركة في packages/shared/src/types/

نمط الكود

• وضع TypeScript الصارم، أنواع إرجاع صريحة، دون any
• ESLint + Prettier مضبوطان

الترخيص

• المحتوى تحت docs/ مرخّص بموجب CC BY-SA 4.0.
• المحتوى تحت proprietary/ مغطى بترخيص تجاري (انظر proprietary/LICENSE). هذه الميزات مجانية خلال الوصول المبكر.
• كل ما عدا ذلك هو MIT.