Skip to content

Commit 4d93bb8

Browse files
KingPinKingPin
KingPin
authored and
KingPin
committed
docs: overhaul README with detailed features, quick start, requirements, and comprehensive configuration.
1 parent b966cd0 commit 4d93bb8

1 file changed

Lines changed: 174 additions & 100 deletions

File tree

‎README.md‎

Lines changed: 174 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,222 @@
11
# PingPanda
22

3-
PingPanda is a versatile monitoring script that performs periodic checks for DNS resolution, ping responses, website availability, and SSL certificate expiry. It logs the results to a specified directory and can send notifications to Slack, Microsoft Teams, and Discord.
3+
**PingPanda** is a high-performance, asynchronous network monitoring tool that performs concurrent checks for DNS resolution, ICMP ping, website availability, and SSL certificate expiry. Built with Python's `asyncio`, it efficiently monitors multiple targets in parallel and sends notifications to Slack, Microsoft Teams, and Discord.
44

5-
## Extended documentation
5+
## Features
66

7-
This README covers core usage and common configuration. Extended documentation (adaptive backoff, filtering, and other deep-dives) has been moved to the `docs/` folder:
7+
- **Concurrent Monitoring**: AsyncIO-powered checks run in parallel for maximum efficiency
8+
- **DNS Resolution Checks**: Verify domain name resolution with `aiodns`
9+
- **ICMP Ping Checks**: Monitor host reachability with `aioping`
10+
- **Website Availability**: Check HTTP/HTTPS endpoints with `aiohttp`
11+
- **SSL Certificate Monitoring**: Track certificate expiry dates
12+
- **Smart Notifications**: Threshold-based alerts with recovery notifications
13+
- **Advanced Statistics**: Track uptime, downtime, response times, and flapping detection
14+
- **Adaptive Backoff**: Circuit breaker pattern to reduce load on failing targets
15+
- **Prometheus Metrics**: Optional metrics export for monitoring dashboards
16+
- **Flexible Logging**: Configurable log levels, rotation, and filtering
817

9-
- `docs/ADAPTIVE_BACKOFF.md` — detailed behavior and examples for adaptive backoff and circuit breaker
10-
- `docs/FILTERING_FEATURES.md` — filtering options and developer notes
18+
## Quick Start
1119

12-
Refer to those files for advanced configuration examples (statistics, flapping detection, persistence).
13-
### Check Targets
20+
### Local Installation
1421

15-
- **DOMAINS**: Comma-separated list of domains to check DNS for (default: google.com)
16-
- **PING_IPS**: Comma-separated list of IPs to ping (default: 1.1.1.1)
17-
- **CHECK_WEBSITE**: Comma-separated list of websites to check (default: empty)
18-
- **SSL_CHECK_DOMAINS**: Comma-separated list of domains to check SSL expiry (default: google.com)
22+
```bash
23+
# Install dependencies
24+
pip install -r requirements.txt
1925

20-
### Check Configuration
26+
# Run with default settings
27+
python pingpanda.py
2128

22-
- **SUCCESS_HTTP_CODES**: Comma-separated list of HTTP status codes considered successful (default: 200)
23-
- **SSL_WARN_DAYS**: Days threshold for SSL certificate warning (default: 30)
24-
- **SSL_CRITICAL_DAYS**: Days threshold for critical SSL alerts (default: 7)
29+
# Run with verbose output
30+
python pingpanda.py --verbose
31+
```
2532

26-
### Notification Settings
33+
### Docker Compose
2734

28-
- **SLACK_WEBHOOK_URL**: Slack webhook URL for notifications (default: empty)
29-
- **TEAMS_WEBHOOK_URL**: Microsoft Teams webhook URL for notifications (default: empty)
30-
- **DISCORD_WEBHOOK_URL**: Discord webhook URL for notifications (default: empty)
31-
- **ALERT_THRESHOLD**: Number of consecutive failures before alerting (default: 3)
32-
- **NOTIFY_RECOVERY**: Whether to send notifications when services recover (default: true)
33-
34-
### Advanced Statistics Configuration
35-
36-
- **ENABLE_ADVANCED_STATS**: Enable detailed ping statistics tracking (default: false)
37-
- **SUMMARY_INTERVAL**: Interval in seconds for statistics summaries (default: 0 - disabled)
38-
- **ENABLE_STATS_LOGGING**: Enable logging statistics to file (default: false)
39-
- **STATS_LOG_FILE**: Path to statistics log file (default: pingpanda_stats.csv)
40-
- **STATS_LOG_FORMAT**: Format for stats logging - 'csv' or 'json' (default: csv)
41-
- **LOG_ROTATION_SIZE**: Size in bytes for stats log rotation (default: 10485760 - 10MB)
42-
- **FLAPPING_THRESHOLD**: Number of status changes to trigger flapping detection (default: 0 - disabled)
43-
- **FLAPPING_WINDOW**: Time window in seconds for flapping detection (default: 300)
44-
- **PERSIST_STATS**: Save statistics across restarts (default: false)
45-
- **STATS_PERSISTENCE_FILE**: File to store persistent statistics (default: pingpanda_stats.pkl)
46-
47-
### Filtering Options
48-
49-
- **SHOW_ONLY_SUCCESS**: Show only successful check results (default: false)
50-
- **SHOW_ONLY_FAILURE**: Show only failed check results (default: false)
51-
```markdown
52-
# PingPanda
35+
```bash
36+
docker-compose up -d
37+
```
5338

54-
PingPanda is a lightweight network monitoring tool that performs periodic checks for DNS resolution, ICMP ping, website availability, and SSL certificate expiry. It logs results, tracks status for threshold-based alerts, and can send notifications to Slack, Teams, and Discord.
39+
## Requirements
5540

56-
## Quick links
41+
PingPanda requires Python 3.10+ and the following dependencies:
5742

58-
- Documentation folder: `docs/` (adaptive backoff, filtering, developer notes)
59-
- Core code: `pingpanda_core/` (app orchestration, checks, notifications, persistence, stats, backoff)
60-
- CLI entrypoint: `pingpanda.py`
43+
- `aiohttp>=3.9.0` - Async HTTP client for website checks
44+
- `aiodns>=3.1.0` - Async DNS resolver
45+
- `aioping>=0.4.0` - Async ICMP ping
46+
- `slack-sdk>=3.34.0` - Slack notifications
47+
- `prometheus-client>=0.17.0` - Metrics export
6148

62-
## Features
49+
**Note**: ICMP ping requires elevated privileges. Run with `sudo` or grant `CAP_NET_RAW` capability:
50+
```bash
51+
sudo setcap cap_net_raw+ep $(which python3)
52+
```
6353

64-
- DNS resolution checks
65-
- Ping checks (ICMP)
66-
- Website availability checks
67-
- SSL certificate expiry checks
68-
- Configurable logging and rotation
69-
- Notification support: Slack, Teams, Discord
70-
- Optional Prometheus metrics export
54+
## Configuration
7155

72-
## Configuration summary
56+
PingPanda is configured via environment variables or a configuration file.
7357

74-
PingPanda is configured primarily via environment variables. See `pingpanda_core/app.py` and the `docs/` folder for full details. Key variables include:
58+
### Core Settings
7559

76-
- `LOG_DIR`, `LOG_FILE`, `LOG_LEVEL`, `MAX_LOG_SIZE`
77-
- `INTERVAL`, `VERBOSE`, `RETRY_COUNT`
78-
- `ENABLE_PING`, `ENABLE_DNS`, `ENABLE_WEBSITE_CHECK`, `ENABLE_SSL_CHECK`
79-
- `DOMAINS`, `PING_IPS`, `CHECK_WEBSITE`, `SSL_CHECK_DOMAINS`
80-
- `SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`, `DISCORD_WEBHOOK_URL`, `ALERT_THRESHOLD`
60+
| Variable | Description | Default |
61+
|----------|-------------|---------|
62+
| `INTERVAL` | Check interval in seconds | `15` |
63+
| `RETRY_COUNT` | Number of retry attempts | `3` |
64+
| `VERBOSE` | Enable verbose logging | `false` |
65+
| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` |
66+
| `LOG_DIR` | Directory for log files | `/logs` |
67+
| `LOG_FILE` | Log file name | `pingpanda.log` |
8168

82-
For advanced options (statistics, adaptive backoff, filtering) see the files in `docs/`.
69+
### Check Targets
8370

84-
## Getting started
71+
| Variable | Description | Default |
72+
|----------|-------------|---------|
73+
| `ENABLE_DNS` | Enable DNS checks | `true` |
74+
| `ENABLE_PING` | Enable ping checks | `true` |
75+
| `ENABLE_WEBSITE_CHECK` | Enable website checks | `false` |
76+
| `ENABLE_SSL_CHECK` | Enable SSL certificate checks | `false` |
77+
| `DOMAINS` | Comma-separated domains for DNS checks | `google.com` |
78+
| `PING_IPS` | Comma-separated IPs for ping checks | `1.1.1.1` |
79+
| `CHECK_WEBSITE` | Comma-separated URLs for website checks | _(empty)_ |
80+
| `SSL_CHECK_DOMAINS` | Comma-separated domains for SSL checks | `google.com` |
8581

86-
Run locally:
82+
### Notification Settings
8783

88-
```bash
89-
pip install -r requirements.txt
90-
# PingPanda
84+
| Variable | Description | Default |
85+
|----------|-------------|---------|
86+
| `SLACK_WEBHOOK_URL` | Slack webhook URL | _(empty)_ |
87+
| `TEAMS_WEBHOOK_URL` | Microsoft Teams webhook URL | _(empty)_ |
88+
| `DISCORD_WEBHOOK_URL` | Discord webhook URL | _(empty)_ |
89+
| `ALERT_THRESHOLD` | Consecutive failures before alerting | `3` |
90+
| `NOTIFY_RECOVERY` | Send recovery notifications | `true` |
91+
| `NOTIFICATION_RETRY_ATTEMPTS` | Retry attempts for failed notifications | `3` |
92+
| `NOTIFICATION_RETRY_BACKOFF_SECONDS` | Backoff between notification retries | `1.0` |
9193

92-
PingPanda is a lightweight network monitoring tool that performs periodic checks for DNS resolution, ICMP ping, website availability, and SSL certificate expiry. It logs results, tracks status for threshold-based alerts, and can send notifications to Slack, Microsoft Teams, and Discord.
94+
### Advanced Features
9395

94-
## Quick links
96+
#### Statistics & Monitoring
9597

96-
- Documentation folder: `docs/` (adaptive backoff, filtering, developer notes)
97-
- Core code: `pingpanda_core/` (app orchestration, checks, notifications, persistence, stats, backoff)
98-
- CLI entrypoint: `pingpanda.py`
98+
| Variable | Description | Default |
99+
|----------|-------------|---------|
100+
| `ENABLE_ADVANCED_STATS` | Enable detailed statistics tracking | `false` |
101+
| `SUMMARY_INTERVAL_SECONDS` | Interval for statistics summaries (0=disabled) | `0` |
102+
| `STORE_STATS_LOG` | Log statistics to file | `false` |
103+
| `STATS_LOG_FILE` | Statistics log file path | `pingpanda_stats.csv` |
104+
| `STATS_LOG_FORMAT` | Log format: `csv` or `json` | `csv` |
105+
| `PERSIST_STATS` | Save statistics across restarts | `false` |
106+
| `FLAP_THRESHOLD` | Status changes to trigger flapping alert | `5` |
107+
| `FLAP_WINDOW_SECONDS` | Time window for flapping detection | `300` |
99108

100-
## Features
109+
#### Adaptive Backoff & Circuit Breaker
101110

102-
- DNS resolution checks
103-
- Ping checks (ICMP)
104-
- Website availability checks
105-
- SSL certificate expiry checks
106-
- Configurable logging and rotation
107-
- Notification support: Slack, Teams, Discord
108-
- Optional Prometheus metrics export
111+
| Variable | Description | Default |
112+
|----------|-------------|---------|
113+
| `ENABLE_ADAPTIVE_BACKOFF` | Enable adaptive backoff for failing targets | `true` |
114+
| `BACKOFF_MIN_SECONDS` | Minimum backoff time | `10.0` |
115+
| `BACKOFF_MAX_SECONDS` | Maximum backoff time | `300.0` |
116+
| `CIRCUIT_BREAKER_THRESHOLD` | Failures to open circuit | `5` |
117+
| `CIRCUIT_BREAKER_COOLDOWN_SECONDS` | Circuit cooldown period | `60.0` |
109118

110-
## Configuration summary
119+
#### Filtering
111120

112-
PingPanda is configured primarily via environment variables. See `pingpanda_core/app.py` and the `docs/` folder for full details. Key variables include:
121+
| Variable | Description | Default |
122+
|----------|-------------|---------|
123+
| `SHOW_ONLY_SUCCESS` | Show only successful results | `false` |
124+
| `SHOW_ONLY_FAILURE` | Show only failed results | `false` |
113125

114-
- `LOG_DIR`, `LOG_FILE`, `LOG_LEVEL`, `MAX_LOG_SIZE`
115-
- `INTERVAL`, `VERBOSE`, `RETRY_COUNT`
116-
- `ENABLE_PING`, `ENABLE_DNS`, `ENABLE_WEBSITE_CHECK`, `ENABLE_SSL_CHECK`
117-
- `DOMAINS`, `PING_IPS`, `CHECK_WEBSITE`, `SSL_CHECK_DOMAINS`
118-
- `SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`, `DISCORD_WEBHOOK_URL`, `ALERT_THRESHOLD`
126+
#### Prometheus Metrics
119127

120-
For advanced options (statistics, adaptive backoff, filtering) see the files in `docs/`.
128+
| Variable | Description | Default |
129+
|----------|-------------|---------|
130+
| `ENABLE_PROMETHEUS` | Enable Prometheus metrics export | `false` |
131+
| `PROMETHEUS_PORT` | Metrics server port | `9090` |
121132

122-
## Getting started
133+
## Configuration File
123134

124-
Run locally:
135+
You can also use a configuration file:
125136

126137
```bash
127-
pip install -r requirements.txt
128-
python pingpanda.py --verbose
138+
python pingpanda.py -c config.conf
129139
```
130140

131-
Run with Docker Compose:
141+
Example `config.conf`:
142+
```ini
143+
INTERVAL=30
144+
DOMAINS=google.com,github.com,example.com
145+
PING_IPS=1.1.1.1,8.8.8.8
146+
ENABLE_WEBSITE_CHECK=true
147+
CHECK_WEBSITE=https://google.com,https://github.com
148+
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
149+
ALERT_THRESHOLD=2
150+
ENABLE_ADVANCED_STATS=true
151+
SUMMARY_INTERVAL_SECONDS=300
152+
```
132153

133-
```bash
134-
docker-compose up -d
154+
## Extended Documentation
155+
156+
For detailed information on advanced features:
157+
158+
- **[Adaptive Backoff](docs/ADAPTIVE_BACKOFF.md)** - Circuit breaker behavior and examples
159+
- **[Filtering Features](docs/FILTERING_FEATURES.md)** - Output filtering options
160+
161+
## Architecture
162+
163+
PingPanda uses an async architecture for efficient concurrent monitoring:
164+
165+
```
166+
pingpanda.py (CLI entry point)
167+
└── pingpanda_core/
168+
├── app.py - AsyncIO orchestration & event loop
169+
├── checks.py - Async check implementations
170+
├── notifications.py - Async notification delivery
171+
├── stats.py - Statistics tracking & flapping detection
172+
├── backoff.py - Adaptive backoff & circuit breaker
173+
└── persistence.py - State persistence
135174
```
136175

137-
## Tests & CI
176+
## Testing
138177

139-
- Tests live under `tests/` and use `pytest`.
140-
- CI workflow `.github/workflows/docker-image.yml` runs linting and tests before building images.
178+
Run the test suite:
179+
180+
```bash
181+
# Install test dependencies
182+
pip install -r requirements.txt
183+
184+
# Run all tests
185+
pytest
186+
187+
# Run with coverage
188+
pytest --cov=pingpanda_core
189+
```
190+
191+
## Docker Deployment
192+
193+
The included `docker-compose.yml` provides a ready-to-use deployment:
194+
195+
```yaml
196+
services:
197+
pingpanda:
198+
build: .
199+
environment:
200+
- DOMAINS=google.com,github.com
201+
- PING_IPS=1.1.1.1,8.8.8.8
202+
- SLACK_WEBHOOK_URL=${SLACK_WEBHOOK_URL}
203+
volumes:
204+
- ./logs:/logs
205+
cap_add:
206+
- NET_RAW # Required for ICMP ping
207+
```
141208
142209
## Contributing
143210
144-
Contributions are welcome. Please open an issue or submit a PR. See the `docs/` folder for developer notes.
211+
Contributions are welcome! Please:
212+
213+
1. Fork the repository
214+
2. Create a feature branch
215+
3. Make your changes with tests
216+
4. Submit a pull request
217+
218+
See the `docs/` folder for developer notes.
145219

146220
## License
147221

148-
This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.
222+
This project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)