Add Monitoring dashboard, improve APIs, further cleanup (#75)

Author: ihatenodejs

.gitignore

@@ -159,4 +159,15 @@ db/
 .vscode/
 
 # JetBrains
-.idea/
+.idea/
+
+# macOS
+.DS_Store
+
+# prometheus
+prometheus/
+prometheus.yml
+!examples/prometheus.yml
+
+# grafana
+grafana/

Dockerfile

@@ -32,6 +32,9 @@ RUN echo "Running WebUI tests..." && \
 
 FROM base AS build
 WORKDIR /usr/src/app
+
+RUN apt-get update && apt-get install -y git && apt-get clean && rm -rf /var/lib/apt/lists/*
+
 COPY --from=test /usr/src/app/node_modules ./node_modules
 COPY --from=test /usr/src/app/webui/node_modules ./webui/node_modules
 COPY --from=test /usr/src/app/ ./
@@ -48,7 +51,6 @@ FROM base AS runtime
 
 RUN apt-get update && apt-get install -y \
     ffmpeg \
-    git \
     supervisor \
     python3 \
     python3-pip \

database/schema.ts

@@ -90,3 +90,52 @@ export const commandUsageTable = pgTable("command_usage", {
   index("idx_command_usage_command_name").on(table.commandName),
   index("idx_command_usage_created_at").on(table.createdAt),
 ]);
+
+export const botErrorsTable = pgTable("bot_errors", {
+  id: varchar({ length: 255 }).notNull().primaryKey(),
+  errorType: varchar({ length: 100 }).notNull(),
+  errorMessage: varchar({ length: 2000 }).notNull(),
+  errorStack: varchar(),
+  commandName: varchar({ length: 255 }),
+  chatType: varchar({ length: 50 }),
+  severity: varchar({ length: 20 }).notNull().default('error'),
+  resolved: boolean().notNull().default(false),
+  createdAt: timestamp().notNull().defaultNow(),
+  resolvedAt: timestamp(),
+}, (table) => [
+  index("idx_bot_errors_created_at").on(table.createdAt),
+  index("idx_bot_errors_error_type").on(table.errorType),
+  index("idx_bot_errors_resolved").on(table.resolved),
+  index("idx_bot_errors_severity").on(table.severity),
+]);
+
+export const telegramErrorsTable = pgTable("telegram_errors", {
+  id: varchar({ length: 255 }).notNull().primaryKey(),
+  errorCode: integer(),
+  errorDescription: varchar({ length: 1000 }).notNull(),
+  method: varchar({ length: 100 }),
+  parameters: varchar(),
+  retryCount: integer().notNull().default(0),
+  resolved: boolean().notNull().default(false),
+  createdAt: timestamp().notNull().defaultNow(),
+  lastRetryAt: timestamp(),
+}, (table) => [
+  index("idx_telegram_errors_created_at").on(table.createdAt),
+  index("idx_telegram_errors_error_code").on(table.errorCode),
+  index("idx_telegram_errors_resolved").on(table.resolved),
+]);
+
+export const systemHealthTable = pgTable("system_health", {
+  id: varchar({ length: 255 }).notNull().primaryKey(),
+  timestamp: timestamp().notNull().defaultNow(),
+  botUptime: boolean().notNull(),
+  databaseConnected: boolean().notNull(),
+  valkeyConnected: boolean().notNull(),
+  memoryUsageBytes: integer(),
+  activeUsers24h: integer(),
+  commandsLastHour: integer(),
+  errorRate: real(),
+  avgResponseTime: integer(),
+}, (table) => [
+  index("idx_system_health_timestamp").on(table.timestamp),
+]);

docs/content/docs/monitoring/admin.mdx

@@ -0,0 +1,9 @@
+---
+title: Admin Dashboard
+description: Monitor Kowalski through the admin dashboard
+icon: Dashboard
+---
+
+The suggested method of monitoring Kowalski is through the admin dashboard. You can find it at [http://localhost:3000/admin/monitoring](http://localhost:3000/admin/monitoring), where `localhost:3000` is the URL to your Kowalski instances' WebUI.
+
+At this time, it does not require documentation, though you can [submit an Issue](https://github.com/abocn/TelegramBot/issues) if you need help.

docs/content/docs/monitoring/index.mdx

@@ -0,0 +1,7 @@
+---
+title: Monitoring
+description: Different methods of monitoring Kowalski
+icon: ChartColumnIncreasing
+---
+
+You can monitor Kowalski's backend easily though a variety of ways. The best way to monitor Kowalski is through the admin dashboard, though we provide a Prometheus-compatible metrics endpoint for those looking to use tools like [Grafana](https://grafana.com/grafana/).

docs/content/docs/monitoring/prometheus.mdx

@@ -0,0 +1,19 @@
+---
+title: Prometheus
+description: Different methods of monitoring Kowalski
+icon: Prometheus
+---
+
+You can monitor Kowalski's backend easily though a variety of ways. The best way to monitor Kowalski is through the admin dashboard, though we provide a Prometheus-compatible metrics endpoint for those looking to use tools like [Grafana](https://grafana.com/grafana/).
+
+## Metrics Endpoint
+
+The /metrics endpoint runs on port `3030`, and is bundled as a part of the Telegram bot. Its code lives in the `telegram/api` directory.
+
+You can use this data to build, for instance, a custom Grafana dashboard. Or you could even make your own monitoring dashboard! The choice is really yours.
+
+## Grafana Dashboard
+
+We've included a sample Grafana dashboard in the `examples` directory of the source, which can be a great way to get started with monitoring Kowalski with Prometheus. You can find it named as `examples/monitoring/grafana.json`, and import through the Grafana UI.
+
+An example `docker-compose.monitoring.yml` file has also been provided for a quick-start of Kowalski, Prometheus, and Grafana.

docs/lib/source.ts

@@ -1,15 +1,17 @@
 import { docs } from '@/.source';
 import { loader } from 'fumadocs-core/source';
 import { icons } from 'lucide-react';
-import { SiDocker, SiYoutube } from 'react-icons/si';
-import { TbSparkles, TbServer } from "react-icons/tb";
+import { SiDocker, SiPrometheus, SiYoutube } from 'react-icons/si';
+import { TbSparkles, TbServer, TbDashboard } from "react-icons/tb";
 import { createElement, ElementType } from 'react';
 
 const customIcons: Record<string, ElementType> = {
   Docker: SiDocker,
   Sparkles: TbSparkles,
   Youtube: SiYoutube,
   Server: TbServer,
+  Dashboard: TbDashboard,
+  Prometheus: SiPrometheus,
 };
 
 export const source = loader({

docs/package.json

@@ -24,10 +24,10 @@
     "@types/react-dom": "^19.1.9",
     "typescript": "^5.9.2",
     "@types/mdx": "^2.0.13",
-    "@tailwindcss/postcss": "^4.1.12",
-    "tailwindcss": "^4.1.12",
+    "@tailwindcss/postcss": "^4.1.13",
+    "tailwindcss": "^4.1.13",
     "postcss": "^8.5.6",
-    "eslint": "^8",
+    "eslint": "^8.57.1",
     "eslint-config-next": "15.5.2"
   }
 }

examples/docker-compose.monitoring.yml

@@ -0,0 +1,71 @@
+services:
+  kowalski:
+    build: .
+    container_name: kowalski
+    volumes:
+      - ./telegram/props/lastfm.json:/usr/src/app/telegram/props/lastfm.json
+    environment:
+      - NODE_ENV=production
+    env_file:
+      - .env
+    networks:
+      - kowalski
+    depends_on:
+      - postgres
+    restart: always
+  postgres:
+    image: postgres:17
+    container_name: kowalski-postgres
+    volumes:
+      - ./db:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_USER=kowalski
+      - POSTGRES_PASSWORD=kowalski
+      - POSTGRES_DB=kowalski
+    networks:
+      - kowalski
+    restart: always
+  valkey:
+    image: valkey/valkey
+    container_name: kowalski-valkey
+    networks:
+      - kowalski
+    restart: always
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: kowalski-prometheus
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - ./prometheus:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+      - '--web.console.libraries=/etc/prometheus/console_libraries'
+      - '--web.console.templates=/etc/prometheus/consoles'
+      - '--web.enable-lifecycle'
+    networks:
+      - kowalski
+    restart: always
+  grafana:
+    image: grafana/grafana
+    container_name: kowalski-grafana
+    ports:
+      - "3001:3000"
+    networks:
+      - kowalski
+    volumes:
+      - ./grafana:/var/lib/grafana
+    restart: always
+  #docs:
+  #  build:
+  #    context: ./docs
+  #    dockerfile: Dockerfile
+  #  container_name: kowalski-docs
+  #  environment:
+  #    - NODE_ENV=production
+  #  networks:
+  #    - kowalski
+  #  restart: always
+
+networks:
+  kowalski: