network-performance-monitor/README.md

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

# Network Performance Monitor

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

**by [Liam Helmer](https://github.com/liamhelmer)**

## 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:
  ```bash
  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:

```bash
npx network-performance-monitor
```

Or use the shorter alias:
```bash
npx npm-monitor
```

### Global Installation

Install globally for regular use:

```bash
npm install -g network-performance-monitor
```

Then run:
```bash
network-performance-monitor
# or
npm-monitor
```

### Manual Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/liamhelmer/network-performance-monitor.git
   cd network-performance-monitor
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the project:
   ```bash
   npm run build
   ```

## Usage

### Starting the Daemon

Start the network performance monitor daemon:
```bash
# 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:
```bash
# 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

```bash
# 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
```bash
node dist/src/index.js run-once
```

#### Test Mode (Rapid Testing)
Run tests with custom intervals for testing:
```bash
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
```bash
# 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:
```bash
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:
```json
{
  "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
```bash
npm run build
```

### Testing
```bash
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](https://github.com/liamhelmer)