pingmon-0.1.8 is not a library.

Pingmon - Real-time Ping Monitor with Timeout Notifications

Real-time network monitoring tool with beautiful ASCII/bar charts, TTL display, statistics, and intelligent timeout notifications.

Screenshot

Features

✨ Two Chart Types:

pingmon - Line chart using ASCII characters
pingmon2 - Vertical bar chart with filled blocks

📊 Real-time Visualization:

Live latency chart that updates every ping
Automatic terminal width detection
Customizable chart height and width

📈 Comprehensive Statistics:

Min/Max/Average latency
Standard deviation
Packet loss percentage
Sent/Received/Lost packet counts
TTL (Time To Live) display

🎨 Beautiful Output:

Color-coded status indicators
Clean, modern interface
Multiple display modes (dynamic, static, chart-only)

🔔 Smart timeout notifications via Growl

Installation

From crates.io

cargo install pingmon

From source

# Install Rust if not already installed

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh


# Clone the repository

git clone https://github.com/cumulus13/pingmon.git

cd pingmon


# Build both binaries

cargo build --release


# Binaries will be in target/release/

# - pingmon (ASCII line chart)

# - pingmon-bar (bar chart)

The binaries will be in target/release/:

pingmon (line chart)
pingmon2 (bar chart)

Usage

Basic Usage

# Using ASCII line chart (default)

pingmon 8.8.8.8


# Using bar chart

pingmon-bar 8.8.8.8


# With custom interval

pingmon google.com -i 0.5


# Chart-only mode (minimal display)

pingmon 1.1.1.1 --chart-only


# Static mode (line-by-line output)

pingmon 8.8.8.8 --static-mode

Timeout Configuration

1. Via Command Line

# Set 2-minute threshold before notification

pingmon 8.8.8.8 --timeout-threshold 120


# Short form

pingmon 8.8.8.8 -t 120

2. Via Environment Variable

# Linux/macOS

export PINGMON_TIMEOUT=120

pingmon 8.8.8.8


# Windows

set PINGMON_TIMEOUT=120

pingmon.exe 8.8.8.8

3. Via Configuration File

Create a configuration file in one of the supported locations (see Configuration File Locations below).

Configuration File Locations

Windows:

%USERPROFILE%\.pingmon\.env
%USERPROFILE%\.pingmon\pingmon.toml
%USERPROFILE%\.pingmon\pingmon.json
%USERPROFILE%\.pingmon\pingmon.ini
%USERPROFILE%\.pingmon\pingmon.yml
%APPDATA%\.pingmon\ (all formats above)

Linux/macOS:

~/.pingmon/.env
~/.pingmon/pingmon.toml
~/.pingmon/pingmon.json
~/.pingmon/pingmon.ini
~/.pingmon/pingmon.yml
~/.config/.pingmon/ (all formats above)
~/.config/ (all formats above)

Configuration File Formats

Format .env:

PINGMON_TIMEOUT=120

Format .toml:

pingmon_timeout = 120

Format .json:

{
  "pingmon_timeout": 120
}

Format .ini:

pingmon_timeout=120

Format .yml/.yaml:

pingmon_timeout: 120

Configuration Priority

The system uses timeout values with the following priority (highest to lowest):

Command line argument (--timeout-threshold or -t)
Environment variable (PINGMON_TIMEOUT)
Config file (first found in search order)
Default value (60 seconds)

Command Line Options

pingmon (ASCII Line Chart)

USAGE:
    pingmon [OPTIONS] [HOST]

ARGS:
    <HOST>    Target host to ping [default: 8.8.8.8]

OPTIONS:
    -c, --chart-only                     Chart-only mode: minimal display with chart
    -h, --help                           Print help information
    -H, --height <HEIGHT>                Chart height [default: 15]
    -i, --interval <INTERVAL>            Interval between pings (seconds) [default: 1.0]
    -s, --static-mode                    Static mode: line-by-line output without chart
    -t, --timeout-threshold <SECONDS>    Timeout threshold before sending notification
    -V, --version                        Print version information
    -W, --width <WIDTH>                  Chart width (0 = auto) [default: 0]

pingmon-bar (Bar Chart)

USAGE:
    pingmon-bar [OPTIONS] [HOST]

ARGS:
    <HOST>    Target host to ping [default: 8.8.8.8]

OPTIONS:
    -c, --chart-only                     Chart-only mode: minimal display with chart
    -h, --help                           Print help information
    -H, --height <HEIGHT>                Chart height [default: 12]
    -i, --interval <INTERVAL>            Interval between pings (seconds) [default: 1.0]
    -s, --static-mode                    Static mode: line-by-line output without chart
    -t, --timeout-threshold <SECONDS>    Timeout threshold before sending notification
    -V, --version                        Print version information
    -W, --width <WIDTH>                  Chart width (0 = auto) [default: 0]

Examples

# Ping with custom chart size

pingmon 8.8.8.8 -H 20 -W 100


# Fast pinging (every 0.5 seconds)

pingmon google.com -i 0.5


# Static mode (no chart, just lines)

pingmon cloudflare.com --static-mode


# Chart-only mode (minimal display)

pingmon-bar 1.1.1.1 --chart-only


# Tall bar chart

pingmon-bar -H 25

How Timeout Notification Works

Timeout Detection Logic

First timeout detected → Timer starts
Timeout persists → Duration counter increments
Threshold reached (e.g., 60s) → Notification sent
Connection recovers → Timer resets, counter clears
Notification sent once per continuous timeout period

Example Scenarios

Scenario 1: Brief Timeout (< threshold)

0s  - Ping OK
1s  - TIMEOUT (timer starts)
2s  - TIMEOUT (2s elapsed)
3s  - Ping OK (timer resets, NO notification sent)

✅ No notification - timeout was brief

Scenario 2: Extended Timeout (≥ threshold)

0s  - Ping OK
1s  - TIMEOUT (timer starts)
2s  - TIMEOUT (2s)
...
60s - TIMEOUT (60s) → **📢 NOTIFICATION SENT**
61s - TIMEOUT (61s)
62s - Ping OK (timer resets)

✅ Notification sent - threshold exceeded

Scenario 3: Repeated Timeouts

0s  - TIMEOUT (timer starts)
...
60s - TIMEOUT (60s) → **📢 NOTIFICATION SENT**
70s - Ping OK (timer resets)
71s - TIMEOUT (new timer starts)
...
131s - TIMEOUT (60s) → **📢 NOTIFICATION SENT AGAIN**

✅ Multiple notifications - each for separate timeout period

Display Modes

1. Dynamic Mode (Default)

Complete statistics
Real-time chart
Status indicators
All metrics visible

Full-featured display with header, statistics, and chart.

=== Real-time Ping Monitor: 8.8.8.8 ===

Latency:  20.07 ms  | TTL:  112  | Status:  CONNECTED 

Statistics:
  Sent: 45 | Received: 45 | Lost: 0 (0.0%)
  Min: 18.23ms | Avg: 20.15ms | Max: 25.67ms | StdDev: 1.45ms

Latency History (ms):
[ASCII chart here]

2. Static Mode (`-s`, `--static-mode`)

Line-by-line output
No terminal manipulation
Ideal for logging

Simple line-by-line output, perfect for logging.

Pinging 8.8.8.8 ...
seq=1 20.07ms ttl=112 (loss=0.0% avg=20.07ms)
seq=2 19.85ms ttl=112 (loss=0.0% avg=19.96ms)
seq=3 21.34ms ttl=112 (loss=0.0% avg=20.42ms)

3. Chart-Only Mode (`-c`, `--chart-only`)

Minimal status line
Larger chart display
Perfect for monitoring

Minimal display with just status and chart.

Latency:  20.07 ms  | TTL:  112  | Status:  CONNECTED  | Host: 8.8.8.8

Latency History (ms):
[ASCII chart here]

Chart Types

Line Chart (`pingmon`)

Latency History (ms):
   25.0 ┤     ╭╮    
   20.0 ┤ ╭───╯╰─╮  
   15.0 ┼─╯      ╰─
   10.0 ┤

Bar Chart (`pingmon2 / bar`)

Latency History (ms):
  39.6 │    █    █
  26.4 │█████████████
  13.2 │█████████████
   0.0  └──────────────

Requirements

Rust: 1.70.0 or later
Operating System: Linux, macOS, or Windows
Privileges: May require administrator/root for ICMP ping
- Linux/macOS: Requires sudo or CAP_NET_RAW capability
- Windows: Run as Administrator

Growl Notifications

Windows/Linux: Growl for Windows or compatible
macOS: Growl or compatible notification system
Notifications fail gracefully if Growl is unavailable

Linux Capability Setup (Recommended)

Instead of using sudo every time, you can set the capability:

# After installation

sudo setcap cap_net_raw+ep $(which pingmon)

sudo setcap cap_net_raw+ep $(which pingmon-bar)

How It Works

pingmon uses:

surge-ping for efficient ICMP ping implementation
rasciichart for beautiful ASCII line charts
colored for terminal color output
tokio for async runtime
Custom bar chart rendering for filled graphs

The tool automatically:

Detects terminal width and adjusts chart size
Handles both IPv4 and IPv6 addresses
Resolves hostnames to IP addresses
Displays TTL (Time To Live) values
Calculates comprehensive statistics

Stopping the Monitor

Press Ctrl+C to stop. Final statistics will be displayed:

✓ Stopped

Final Statistics:
  Packets: Sent = 45, Received = 45, Lost = 0 (0.0%)
  Latency: Min = 18.23ms, Avg = 20.15ms, Max = 25.67ms, StdDev = 1.45ms

Troubleshooting

Ping Fails

Linux: Run with sudo for raw socket access
Windows: Run as Administrator
Check firewall settings for ICMP

Notifications Not Working

Verify Growl is installed and running
Check notification settings in Growl
Notifications fail silently if Growl unavailable

Config File Not Found

Check file is in correct location
Verify file permissions
Run with --timeout-threshold to bypass config file

Wrong Timeout Value Used

Check priority:

CLI argument overrides everything
Environment variable overrides config file
Config file overrides default
Default is 60 seconds

Permission Denied

Linux/macOS:

# Option 1: Use sudo

sudo pingmon 8.8.8.8


# Option 2: Set capability (recommended)

sudo setcap cap_net_raw+ep ~/.cargo/bin/pingmon

Windows:

Run Command Prompt or PowerShell as Administrator

Host Not Found

Make sure the hostname is correct:

pingmon google.com  # Correct

pingmon gogle.com   # Will fail - typo

Building

# Development build

cargo build


# Release build (optimized)

cargo build --release


# Build specific binary

cargo build --release --bin pingmon

cargo build --release --bin pingmon2

Dependencies

New Dependencies (v0.1.6)

serde - Configuration deserialization
serde_json - JSON config support
toml - TOML config support
serde_yaml - YAML config support
dirs - Cross-platform directory paths

Existing Dependencies

surge-ping - ICMP ping implementation
colored - Terminal colors
term_size - Terminal size detection
ctrlc - Ctrl+C handler
rand - Random number generation
rasciichart - ASCII chart rendering
gntp - Growl notification protocol
tokio - Async runtime
clap - Command-line argument parsing

Testing

Test with Different Configurations

# Test with environment variable

PINGMON_TIMEOUT=30 cargo run --bin pingmon -- 8.8.8.8


# Test with config file

mkdir -p ~/.pingmon

echo "pingmon_timeout = 30" > ~/.pingmon/pingmon.toml

cargo run --bin pingmon -- 8.8.8.8


# Test with CLI argument (highest priority)

cargo run --bin pingmon -- 8.8.8.8 --timeout-threshold 30


# Test bar chart version

cargo run --bin pingmon-bar -- 8.8.8.8 -t 45

Test Timeout Notification

# Monitor a host, then disconnect network after 30s

pingmon 8.8.8.8 -t 30


# Monitor local address, stop service to trigger timeout

pingmon 192.168.1.1 -t 45

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

👤 Author

Hadi Cahyadi

Support me on Patreon

Changelog

v0.1.6 (2025-01-28)

✨ Added intelligent timeout notification system
✨ Added flexible configuration system (env vars + config files)
✨ Added timeout duration display in UI
✨ Support for multiple config file formats (.env, .toml, .json, .ini, .yml)
📝 Updated documentation with timeout notification examples
🔧 Improved notification reliability

v0.1.5

Previous stable release

v0.1.0 (Initial Release)

Real-time ping monitoring with ASCII charts
Two chart types: line and bar
Comprehensive statistics
Multiple display modes
Auto terminal width detection
TTL display
Color-coded output

Tips

For Continuous Monitoring: Use chart-only mode for cleaner display
```
pingmon 8.8.8.8 --chart-only
```

For Logging: Use static mode and redirect output

pingmon 8.8.8.8 --static-mode >> ping.log

Custom Thresholds: Adjust based on your network stability

# Stable network: longer threshold

pingmon 8.8.8.8 -t 300  # 5 minutes


# Unstable network: shorter threshold

pingmon 8.8.8.8 -t 30   # 30 seconds

Multiple Monitors: Run different instances for different hosts

# Terminal 1

pingmon google.com -t 60


# Terminal 2

pingmon-bar 1.1.1.1 -t 60

Support

For issues, questions, or suggestions:

Open an issue on GitHub
Email: cumulus13@gmail.com

pingmon 0.1.8