Network Performance Monitor

A comprehensive network performance monitoring tool that continuously tests and tracks your network's performance over time.

by Liam Helmer

Features

• Continuous Monitoring: Runs as a daemon, performing tests at regular intervals
• Multiple Test Types:
  • DNS resolution tests (Google, Cloudflare, OpenDNS)
  • Ping tests to multiple servers
  • Website response time tests
  • Internet speed tests (download/upload/ping)
• Network Awareness: Tracks which network (WiFi SSID or interface) each test was performed on
• Anomaly Detection: Automatically triggers speed tests when network issues are detected
• Web UI Dashboard: Real-time charts and statistics with:
  • Logarithmic scale for latency visualization
  • Anomaly highlighting and labeling
  • Average line indicators
  • Network filtering by WiFi SSID or interface
  • Auto-refresh capability with countdown timer
  • Time range selection (1 hour to all data)
  • Manual speed test trigger button
  • Four key metrics: Avg Ping Latency, Avg Website Response, Avg Download/Upload Speed
  • Network-aware caching (1-minute cache for UI requests)
• Smart Logging:
  • Debug level for individual successful tests
  • Info level for summaries and important events
  • Error level for all failures
  • Local timezone timestamps
• Data Persistence: SQLite database for historical data
• Configurable: Customizable test intervals and targets via JSON config

Prerequisites

• Node.js 16+ and npm
• Python 3 with speedtest-cli installed:

  pip install speedtest-cli
  # or on macOS with Homebrew:
  brew install speedtest-cli

Installation

Quick Start with npx (Recommended)

You can run the network performance monitor directly without installation:

npx network-performance-monitor

Or use the shorter alias:

npx npm-monitor

Global Installation

Install globally for regular use:

npm install -g network-performance-monitor

Then run:

network-performance-monitor
# or
npm-monitor

Manual Installation

1. Clone the repository:

   git clone https://github.com/liamhelmer/network-performance-monitor.git
   cd network-performance-monitor

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Usage

Starting the Daemon

Start the network performance monitor daemon:

# If installed via npm/npx:
network-performance-monitor start
# or with custom port
network-performance-monitor start --port 8080

# If cloned from repository:
npm run start
# or with custom port
npm run start -- --port 8080

Test Mode

For testing and development, you can run with immediate speed tests at custom intervals:

# Run with test mode - speed test every 10 seconds
network-performance-monitor start --test-mode --speed-test-interval 10000

# Or from repository
npm run start -- --test-mode --speed-test-interval 10000

The daemon will:

• Run DNS, ping, and website tests every 60 seconds
• Run speed tests at the top of every hour (no speed test on startup)
• Automatically trigger speed tests when anomalies are detected
• Start a web UI on port 3000 (or specified port)
• Log to ~/.network-performance-monitor/network-monitor.log
• Cache network detection for 1 minute to reduce overhead

Managing the Daemon

# Check if daemon is running
npm run status
# or with npm/npx install:
network-performance-monitor status

# Stop the daemon
npm run stop
# or with npm/npx install:
network-performance-monitor stop

# Restart the daemon
npm run restart
# or with custom port
npm run restart -- --port 8080
# or with npm/npx install:
network-performance-monitor restart --port 8080

# Restart in test mode
network-performance-monitor restart --test-mode --speed-test-interval 10000

Web UI

Access the web dashboard at http://localhost:3000 (or your specified port) to view:

• Real-time performance graphs for ping latency, website response time, and speed tests
• Time-range aware averages (not fixed 30-day)
• Network-specific data filtering
• Time range selection (1 hour to all data) - defaults to 1 hour view
• Manual speed test trigger with visual feedback
• Repository link in the title

CLI Commands

Run Tests Once

node dist/src/index.js run-once

Test Mode (Rapid Testing)

Run tests with custom intervals for testing:

node dist/src/index.js test -r 5 -s 30 -d 300

Options:

• -r, --regular <seconds>: Regular check interval (default: 1)
• -s, --speedtest <seconds>: Speed test interval (default: 10)
• -d, --duration <seconds>: Test duration (default: 60)

Running Tests

# Run all tests
npm run test:all

# Run scheduled speed test regression tests
npm run test:scheduled

# Run standard tests
npm test

UI Only Mode

Run just the web UI without the daemon:

node dist/src/index.js ui --port 3000

Configuration

Create a configuration file at one of these locations:

• ./network-monitor.config.json
• ~/.network-performance-monitor/config.json
• /etc/network-performance-monitor/config.json

Example configuration:

{
  "intervals": {
    "regularCheck": 60000,
    "speedTest": 3600000
  },
  "dns": {
    "servers": ["8.8.8.8", "1.1.1.1", "208.67.222.222"],
    "query": "google.com"
  },
  "websites": [
    "https://www.google.com",
    "https://www.cloudflare.com",
    "https://www.amazon.com"
  ]
}

Data Storage

• Database: ~/.network-performance-monitor/performance.db
• Logs: ~/.network-performance-monitor/network-monitor.log
• PID file: ~/.network-performance-monitor/network-monitor.pid

Network Detection

The tool automatically detects your current network:

• WiFi: Uses SSID name (e.g., "DragonsDen")
• Ethernet/Other: Uses interface and gateway (e.g., "eth0 (192.168.1.1)")

All test results are tagged with the network name, allowing you to:

• Filter results by network in the web UI
• Compare performance across different networks
• Track network-specific issues

Logging

The logging system uses multiple levels:

• Debug: Individual successful test results (console only)
• Info: Summary messages, daemon status, speed test results
• Warn: Anomaly detections
• Error: Test failures and errors

Log files only contain info level and above, keeping them concise and focused on important events. All timestamps use local timezone for easier troubleshooting.

Development

Project Structure

├── src/               # TypeScript source files
├── dist/              # Compiled JavaScript
├── public/            # Web UI files
├── test/              # Test files
└── docs/              # Documentation

Building

npm run build

Testing

npm test

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Troubleshooting

Daemon won't start

• Check if it's already running: npm run status
• Check the log file for errors
• Ensure port 3000 (or specified port) is available

Speed tests failing

• Ensure speedtest-cli is installed: pip install speedtest-cli
• Run speedtest-cli --json manually to test
• Check Python version (Python 3 required)

No data showing in UI

• Ensure daemon is running: npm run status
• Check if data exists: sqlite3 ~/.network-performance-monitor/performance.db "SELECT COUNT(*) FROM ping_results;"
• Check browser console for errors

License

MIT License - see LICENSE file for details

Author

Liam Helmer

• GitHub: @liamhelmer