statpulse

A collection of Bash scripts for ping monitoring, hostname logging, statistics analysis, and Telegram notifications.

---

Scripts Overview

Script	Purpose
ping_google.sh	Ping Google 10 times and log results
ping_stats.sh	Analyse a ping log file and print statistics
log_hostname.sh	Log current timestamp and hostname to a file
hostname_stats.sh	Analyse a hostname log file and print statistics
send_stats_telegram.sh	Send statistics from any log file to a Telegram chat
log_cron_start.sh	Record when cron first starts after a boot or reboot

---

Log File Naming

All log files use the format yyyy-mm-dd-hh.txt (e.g. 2026-04-29-14.txt), one file per hour.

---

Setup

chmod +x *.sh

Copy .env and set your preferred log directories:

# .env
PING_DEST_DIR=/var/log/statpulse/pinglog
PING_FALLBACK_DIR=/tmp/statpulse/pinglog

HOSTNAME_DEST_DIR=/var/log/statpulse/hostlog
HOSTNAME_FALLBACK_DIR=/tmp/statpulse/hostlog

CRONSTART_DEST_DIR=/var/log/statpulse/cronstart
CRONSTART_FALLBACK_DIR=/tmp/statpulse/cronstart

Each logger sources .env from its own directory at runtime. If .env is absent or a variable is unset, the built-in defaults shown above are used.

---

ping_google.sh

Pings google.com 10 times, writing each result with an ISO 8601 timestamp to the current hour's log file.

• Primary path: PING_DEST_DIR from .env (default /var/log/statpulse/pinglog/)
• Secondary (fallback) path: PING_FALLBACK_DIR from .env (default /tmp/statpulse/pinglog/)

Usage:

./ping_google.sh

Log format:

2026-04-29T14:32:01+00:00 64 bytes from 142.250.74.46: icmp_seq=1 ttl=117 time=12.3 ms
2026-04-29T14:32:02+00:00 Request timeout for icmp_seq 2

---

ping_stats.sh

Reads a ping log file and prints statistics: total, successful and failed pings, min/max/avg RTT. Failed ping lines are shown in detail.

Usage:

./ping_stats.sh                                            # current hour
./ping_stats.sh 2026-04-29-14.txt                         # specific file
./ping_stats.sh $(date -d '1 hour ago' +%Y-%m-%d-%H).txt  # one hour earlier

Sample output:

==============================
 Ping Statistics: 2026-04-29-14.txt
==============================
 Total pings : 10
 Successful  : 8
 Failed      : 2
 Min RTT     : 10.123 ms
 Max RTT     : 45.678 ms
 Avg RTT     : 22.456 ms

==============================
 Failed Ping Details
==============================
 2026-04-29T14:05:01+00:00 Request timeout for icmp_seq 5
 2026-04-29T14:05:08+00:00 Request timeout for icmp_seq 8
==============================

---

log_hostname.sh

Appends the current ISO timestamp, hostname, and path label (primary or secondary) to the current hour's log file.

• Primary path: HOSTNAME_DEST_DIR from .env (default /var/log/statpulse/hostlog/)
• Secondary (fallback) path: HOSTNAME_FALLBACK_DIR from .env (default /tmp/statpulse/hostlog/)

Usage:

./log_hostname.sh

Log format:

2026-04-29T14:32:01+00:00 myserver [primary: /var/log/hostlog/2026-04-29-14.txt]
2026-04-29T14:45:12+00:00 myserver [secondary: /tmp/hostlog/2026-04-29-14.txt]

---

hostname_stats.sh

Reads a hostname log file and prints statistics: total entries, primary path count, secondary path count. Secondary path events are shown in detail.

Usage:

./hostname_stats.sh                                            # current hour
./hostname_stats.sh 2026-04-29-14.txt                         # specific file
./hostname_stats.sh $(date -d '1 hour ago' +%Y-%m-%d-%H).txt  # one hour earlier

Sample output:

==============================
 Hostname Log Stats: 2026-04-29-14.txt
==============================
 Total entries : 10
 Primary path  : 8
 Secondary path: 2

==============================
 Secondary Path Details
==============================
 2026-04-29T14:05:01+00:00 myserver [secondary: /tmp/hostlog/2026-04-29-14.txt]
 2026-04-29T14:08:44+00:00 myserver [secondary: /tmp/hostlog/2026-04-29-14.txt]
==============================

---

log_cron_start.sh

Records a timestamped entry every time cron starts after a boot or reboot. Intended to be triggered via @reboot in crontab so there is a permanent, searchable record of when cron became active.

• Primary path: CRONSTART_DEST_DIR from .env (default /var/log/statpulse/cronstart/)
• Secondary (fallback) path: CRONSTART_FALLBACK_DIR from .env (default /tmp/statpulse/cronstart/)

Usage:

./log_cron_start.sh

Log format:

2026-04-29T14:01:03+00:00 myserver boot=2026-04-29 14:00:51 [primary: /var/log/cronstart/cron_starts.log]

Each line contains:

• ISO 8601 timestamp of when the @reboot job ran
• Hostname
• System boot time (from who -b)
• Path label and full log path

---

send_stats_telegram.sh

Reads a log file, builds statistics, and sends a formatted HTML message to a Telegram chat. Automatically detects whether the log is a ping log or a hostname log.

Configuration

Edit telegram.conf before first use:

BOT_TOKEN="your_bot_token_here"
CHAT_ID="your_chat_id_here"

To create a bot, message @BotFather on Telegram.
To get your chat ID, message @userinfobot.

Usage

./send_stats_telegram.sh                                            # auto-detect, current hour
./send_stats_telegram.sh 2026-04-29-14.txt                         # specific file, auto-detect
./send_stats_telegram.sh 2026-04-29-14.txt ping                    # force ping mode
./send_stats_telegram.sh 2026-04-29-14.txt hostname                # force hostname mode
./send_stats_telegram.sh $(date -d '1 hour ago' +%Y-%m-%d-%H).txt  # one hour earlier

Modes

Mode	Description
auto (default)	Detects log type by content
ping	Forces ping statistics
hostname	Forces hostname statistics

---

Automating with Cron

# Record cron start time on every boot or reboot
@reboot /path/to/log_cron_start.sh

# Ping Google every 10 minutes
*/10 * * * * /path/to/ping_google.sh

# Log hostname every 5 minutes
*/5 * * * * /path/to/log_hostname.sh

# Send ping stats to Telegram at end of each hour
59 * * * * /path/to/send_stats_telegram.sh $(date +\%Y-\%m-\%d-\%H).txt ping

# Send hostname stats to Telegram at end of each hour
58 * * * * /path/to/send_stats_telegram.sh $(date +\%Y-\%m-\%d-\%H).txt hostname

To view the boot start history:

cat /var/log/cronstart/cron_starts.log

---

Testing

Tests are written with bats-core and live in the tests/ directory.

Install bats

git clone https://github.com/bats-core/bats-core.git
sudo ./bats-core/install.sh /usr/local

Run all tests

bash tests/run_tests.sh

Run a single test file

bats tests/test_ping_stats.bats

Test files

File	Script under test	Coverage
test_ping_stats.bats	ping_stats.sh	Missing file, empty file, all-success, RTT min/max/avg, all-fail, no RTT when all fail, no details when all succeed, mixed, blank lines
test_hostname_stats.bats	hostname_stats.sh	Missing file, empty file, all-primary, secondary counts and details, no secondary section, multiple secondary, blank lines
test_log_hostname.bats	log_hostname.sh	Directory creation, filename format, .env respected, hostname in entry, primary label, ISO timestamp, append on repeated runs, fallback path
test_log_cron_start.bats	log_cron_start.sh	Directory creation, log filename, .env respected, hostname, primary label, ISO timestamp, boot= field, append on repeated runs, fallback path
test_ping_google.bats	ping_google.sh	Directory creation, filename format, .env respected, fallback path, 10 lines written, timestamp per line, ping result per line — ping is mocked
test_send_stats_telegram.bats	send_stats_telegram.sh	Missing conf, missing BOT_TOKEN/CHAT_ID, missing log file, send in ping/hostname/auto modes, default auto mode, message content — curl is mocked

---

Dependencies

• bash
• ping
• curl — required for Telegram notifications
• awk — for RTT calculations
• grep with Perl regex support (-P flag)