Skip to content

README.md

Latest commit

 

History

History
178 lines (131 loc) · 7.46 KB

README.md

File metadata and controls

178 lines (131 loc) · 7.46 KB

vshosting-monitor

CI Node.js License: MIT

Node.js CLI tool that connects to the vshosting.cloud public API (/api/public/...) and prints a table with server health (CPU, RAM, Disk). Includes a Slack notification script that fires when any server exceeds a configured threshold.

Only GET requests are issued against the API (the single exception is POST /auth/login used to obtain an access token).

Requirements

  • Node.js >= 20 (uses built-in fetch and AbortSignal.timeout), or
  • Docker + Docker Compose

Installation

npm install
cp .env.example .env
# fill in VSHOSTING_EMAIL and VSHOSTING_PASSWORD

Usage

Print server table

npm start
# or: node src/index.js

# only show hostnames containing "db":
npm start -- --name=db

# glob wildcards work too:
npm start -- --name='db-*.prod'
npm start -- --name='web??.example.com'

Example output

Signing in... OK
Fetching user info... OK
Clients: 1
  - client 01HXXX...: 3 server(s)

┌────────────────────┬──────────┬─────────┬──────┬──────┬──────┬───────┬────────────────┐
│ Hostname           │ Location │ Service │ CPU  │ RAM  │ Disk │ Cores │ OS             │
├────────────────────┼──────────┼─────────┼──────┼──────┼──────┼───────┼────────────────┤
│ web01.example.com  │ prg      │ MVE     │ 12%  │ 47%  │ 33%  │ 4     │ Debian 12      │
│ db01.example.com   │ prg      │ MVE     │ 78%  │ 82%  │ 61%  │ 8     │ Debian 12      │
│ cache01.example.com│ brn      │ MVE     │ 4%   │ 91%  │ 12%  │ 2     │ Ubuntu 22.04   │
└────────────────────┴──────────┴─────────┴──────┴──────┴──────┴───────┴────────────────┘

WARNING: 1 server(s) have at least one metric >= 90%

Colors:

  • green: metric < 75 %
  • yellow: 75 - 89 %
  • red: >= 90 %

Send Slack notification on threshold breach

npm run notify                  # single check, posts to Slack if anything is over
npm run notify -- --dry-run     # prints the Slack payload only
npm run notify -- --interval=60 # poll forever, every 60 seconds
npm run notify -- --name=db     # only alert on hostnames matching "db"

A notification is sent when any of the following holds for any server:

  • cpuUsage > 70 %
  • memoryUsage > 80 %
  • maxDiskSpaceQuotaUsage > 90 %

Thresholds can be overridden via env vars (see Configuration). One aggregated Slack message is sent per check that contains every breaching server with a per-metric breakdown.

Watch mode (--interval) applies an exponential backoff on iteration errors (doubling up to 30 minutes) to avoid hammering the upstream API or Slack when something is down.

Scheduling with cron

If you prefer system cron over the built-in watch mode (--interval), run the script as a stateless one-shot. Each invocation logs in, checks once, posts to Slack if anything breaches, then exits.

Edit your crontab (crontab -e) and add, for example:

# Run every 5 minutes; log to a file you can rotate.
*/5 * * * * cd /opt/vshosting-monitor && /usr/bin/node src/notify.js >> /var/log/vshosting-notify.log 2>&1

Notes:

  • Use an absolute path to node — cron's PATH is minimal. Find yours with command -v node.
  • cd into the project directory so dotenv picks up .env.
  • The script is stateless, so cron runs are safe to overlap or miss without state drift.
  • Only the hostname filter from NAME_FILTER (env) applies in this mode — pass --name=<pattern> after src/notify.js if you need a CLI override.
  • Docker equivalent: */5 * * * * docker compose -f /opt/vshosting-monitor/docker-compose.yml run --rm notify.

Because each run reauthenticates, do not schedule it more often than once a minute.

Configuration

Variable Description
VSHOSTING_EMAIL Login email
VSHOSTING_PASSWORD Login password
VSHOSTING_BASE_URL API base URL (default https://admin.vshosting.cloud)
SLACK_WEBHOOK_URL Slack incoming webhook URL (required for npm run notify)
ALERT_CPU_THRESHOLD CPU alert threshold in % (default 70)
ALERT_RAM_THRESHOLD RAM alert threshold in % (default 80)
ALERT_DISK_THRESHOLD Disk alert threshold in % (default 90)
NOTIFY_INTERVAL_SECONDS When set, notify runs in a loop with this interval (used by Docker)
NAME_FILTER Hostname filter (substring or */? glob); --name=<pattern> overrides

Docker

A Dockerfile and docker-compose.yml are included.

# one-shot table view
docker compose run --rm monitor

# long-running notify watcher (re-checks every NOTIFY_INTERVAL_SECONDS)
docker compose up -d notify
docker compose logs -f notify

Both services read .env automatically.

How it works

  1. POST /api/public/auth/login - obtain accessToken.
  2. GET /api/public/user/info - resolve which client accounts the user belongs to (clientUserList[].clientId).
  3. For each clientId: GET /api/public/client/{clientId}/server - returns server list (ServerLight) with serverStats (cpuUsage, memoryUsage, maxDiskSpaceQuotaUsage).
  4. The CLI renders the table; the notify script evaluates thresholds and posts to Slack.

All HTTP requests have a 15-second timeout.

Project layout

.
├── src/
│   ├── api.js        # VshostingClient: login, user info, server list
│   ├── filter.js     # hostname filter (substring + glob)
│   ├── evaluator.js  # pure threshold evaluation + Slack payload builder
│   ├── index.js      # CLI table renderer (npm start)
│   └── notify.js     # Slack notifier (npm run notify)
├── tests/
│   ├── filter.test.js
│   └── evaluator.test.js
├── .github/workflows/ci.yml
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── CLAUDE.md         # guide for AI assistants working on this repo
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
└── README.md

Development

npm install
npm run check    # node --check on all source files
npm test         # run unit tests

See CONTRIBUTING.md for project conventions.

License

MIT © be-lenka