Skip to content

Check network-io

Overview

Monitors network I/O throughput per interface over time. Calculates bytes per second from cumulative counters using SQLite state persistence between runs. Alerts only if bandwidth thresholds have been exceeded for a configurable number of consecutive check runs (default: 5), suppressing short spikes. Also reports packet rates, errors, and drops per interface.

Important Notes:

  • --count=5 (the default) while checking every minute means that the check reports a warning if any of your interfaces were above a threshold in the last 5 minutes
  • Interfaces starting with lo are ignored by default; use --ignore to exclude additional interfaces

Data Collection:

  • Uses psutil.net_io_counters() to collect bytes sent/received, packets, errors, and drops per interface
  • Uses SQLite state persistence between runs to calculate deltas (bytes per second)
  • On the first run, returns "Waiting for more data." until at least two measurements are available
  • After a system reboot, counter values may be lower than the previous measurement. The check detects this (negative delta) and returns "Waiting for more data." until the next valid measurement pair.
  • The all-time maximum throughput per interface is stored in the cache and never decreases automatically

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/network-io
Nagios/Icinga Check Name check_network_io
Check Interval Recommendation Every minute
Can be called without parameters Yes
Runs on Cross-platform
Compiled for Windows Yes
3rd Party Python modules psutil
Uses SQLite DBs $TEMP/linuxfabrik-monitoring-plugins-network-io.db

Help

usage: network-io [-h] [-V] [--always-ok] [--count COUNT] [--critical CRIT]
                  [--ignore IGNORE] [--warning WARN]

Monitors network I/O throughput per interface over time. Calculates bytes per
second from cumulative counters using SQLite state persistence between runs.
Alerts only if bandwidth thresholds have been exceeded for a configurable
number of consecutive check runs (default: 5), suppressing short spikes. Also
reports packet rates, errors, and drops per interface.

options:
  -h, --help       show this help message and exit
  -V, --version    show program's version number and exit
  --always-ok      Always returns OK.
  --count COUNT    Number of consecutive checks the threshold must be exceeded
                   before alerting. Default: 5
  --critical CRIT  CRIT threshold for network I/O rx/tx rate over the entire
                   period as a percentage of the maximum network I/O rate.
                   Default: >= 90
  --ignore IGNORE  Ignore network interfaces starting with this string. Can be
                   specified multiple times. Example: `--ignore tun`. Default:
                   ['lo']
  --warning WARN   WARN threshold for network I/O rx/tx rate over the entire
                   period as a percentage of the maximum network I/O rate.
                   Default: >= 80

Usage Examples

./network-io --ignore lo --warning 80 --critical 90 --count 5

Output:

wlp0s20f3: 28.1MiB/s rx, 5.6KiB/s tx (current)

Interface ! rxtx-max/s ! rx1/s   ! tx1/s  ! rx5/s    ! tx5/s  ! rxtx5/s  
----------+------------+---------+--------+----------+--------+----------
tun0      ! 10.0MiB    ! 0.0B    ! 0.0B   ! 2.8B     ! 7.8B   ! 10.6B    
tun2      ! 10.0MiB    ! 183.0B  ! 106.0B ! 2.9B     ! 7.9B   ! 10.8B    
wlp0s20f3 ! 30.0MiB    ! 28.1MiB ! 5.6KiB ! 25.1 MiB ! 2.9KiB ! 25.1MiB [WARNING]

The first line always shows the interface with the currently highest throughput. The table columns mean:

  • rxtx-max/s: The maximum throughput ever measured for this interface.
  • rx1/s, tx1/s: The current throughput (receive and transmit).
  • rx5/s, tx5/s: The averaged throughput over the last 5 measured values.
  • rxtx5/s: The combined rx+tx throughput over the period. This is what gets compared against the threshold.

States

  • OK if throughput over the measured period is below the warning threshold for all interfaces.
  • OK with "Waiting for more data." on the first run or after a reboot.
  • WARN or CRIT if the throughput over the last n measured values exceeds the specified percentage of the all-time maximum throughput.
  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Per interface:

Name Type Description
\<interface>_bytes_recv Continuous Counter Number of bytes received.
\<interface>_bytes_recv_per_second1 Bytes Current bytes received per second.
\<interface>_bytes_recv_per_second15 Bytes Averaged bytes received per second over the configured count.
\<interface>_bytes_sent Continuous Counter Number of bytes sent.
\<interface>_bytes_sent_per_second1 Bytes Current bytes sent per second.
\<interface>_bytes_sent_per_second15 Bytes Averaged bytes sent per second over the configured count.
\<interface>_dropin Continuous Counter Total number of incoming packets which were dropped.
\<interface>_dropout Continuous Counter Total number of outgoing packets which were dropped (always 0 on macOS and BSD).
\<interface>_errin Continuous Counter Total number of errors while receiving.
\<interface>_errout Continuous Counter Total number of errors while sending.
\<interface>_packets_recv Continuous Counter Number of packets received.
\<interface>_packets_sent Continuous Counter Number of packets sent.
\<interface>_throughput1 None Current bytes per second (bytes_recv_per_second1 + bytes_sent_per_second1).
\<interface>_throughput15 None Averaged bytes per second over the configured count.

Troubleshooting

Waiting for more data. This is expected on the first run or after a reboot. The check needs at least two measurements to calculate a delta. Wait for the next check interval.

Credits, License