andreas/heartbeat
Public Access
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 44 Wiki Activity

update README

Browse Source
This commit is contained in:
Andreas Wrede
2026-04-09 08:33:25 -04:00
parent 79bf00abfd
commit cc458e8972
1 changed files with 54 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+54 -35
View File
@@ -76,7 +76,7 @@ See [docs/NAGIOS_INTEGRATION.md](docs/NAGIOS_INTEGRATION.md) for complete integr
### Creating Custom Plugins ### Creating Custom Plugins
```python ```python
from hbd.plugin import MonitorPlugin from hbd.client.plugin import MonitorPlugin
class DiskMonitorPlugin(MonitorPlugin): class DiskMonitorPlugin(MonitorPlugin):
name = "disk_monitor" name = "disk_monitor"
@@ -89,7 +89,7 @@ class DiskMonitorPlugin(MonitorPlugin):
} }
``` ```
Place plugins in `hbd/plugins/` and they'll be automatically discovered and loaded by the client. Place plugins in `hbd/client/plugins/` and they'll be automatically discovered and loaded by the client.
--- ---
@@ -368,7 +368,7 @@ See [docs/HTTP_API.md](docs/HTTP_API.md) for complete API documentation includin
Prerequisites: Prerequisites:
- Python 3.10+ (project uses language features from recent Python) - Python 3.11+ (project uses language features from recent Python)
- `nsupdate` (for DNS updates) if using dynamic DNS - `nsupdate` (for DNS updates) if using dynamic DNS
Install dependencies (recommended into a venv): Install dependencies (recommended into a venv):
@@ -389,7 +389,7 @@ hbd -c .hb.yaml -f -v
You can also run it directly via the package entrypoint after installation: You can also run it directly via the package entrypoint after installation:
```bash ```bash
python -m hbd.cli -c /path/to/config.yaml python -m hbd.server.cli -c /path/to/config.yaml
``` ```
### Running the Client ### Running the Client
@@ -397,14 +397,23 @@ python -m hbd.cli -c /path/to/config.yaml
The heartbeat client (`hbc`) sends periodic heartbeats and plugin data to the server: The heartbeat client (`hbc`) sends periodic heartbeats and plugin data to the server:
```bash ```bash
# Basic usage pointing to server # Basic usage pointing to server (host is a positional argument)
python -m hbd.hbc --server your-server.example.com hbc your-server.example.com
# With custom configuration # Run as daemon with a config file
python -m hbd.hbc --server 192.168.1.100 --port 50003 --interval 30 hbc -d -c /etc/hbc.yaml your-server.example.com
# Run with specific plugins enabled/disabled # Send a one-off boot message
python -m hbd.hbc --server hbd.local --disable-plugin os_info hbc --boot your-server.example.com
# Verbose output
hbc -v your-server.example.com
```
You can also run it via the module entrypoint:
```bash
python -m hbd.client.main your-server.example.com
``` ```
Client configuration can also be specified in YAML: Client configuration can also be specified in YAML:
@@ -438,23 +447,23 @@ This repository includes a ready-to-use `.vscode/launch.json` with configuration
- Ensure the **Python** extension is installed and select the project `.venv` as the interpreter (bottom-left of VS Code). - Ensure the **Python** extension is installed and select the project `.venv` as the interpreter (bottom-left of VS Code).
- Use **F5** and pick one of these configurations from the Run view: - Use **F5** and pick one of these configurations from the Run view:
- **Python: Run hbd (module)** — runs `hbd.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended). - **Python: Run hbd (module)** — runs `hbd.server.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended).
- **Python: Run hbd with debugpy (listen)** — launches `debugpy` and `hbd` together; useful when you want the process to listen for a debugger. - **Python: Run hbd with debugpy (listen)** — launches `debugpy` and `hbd` together; useful when you want the process to listen for a debugger.
- **Python: Attach (localhost:5678)** — attach the debugger to a running process started with `debugpy`. - **Python: Attach (localhost:5678)** — attach the debugger to a running process started with `debugpy`.
To start `hbd` manually and wait for the debugger to attach, run: To start `hbd` manually and wait for the debugger to attach, run:
```bash ```bash
PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.cli -c .hb.yaml -f -v PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.server.cli -c .hb.yaml -f -v
``` ```
Set breakpoints in modules such as `hbd/udp.py`, `hbd/dns.py`, or `hbd/server.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code. Set breakpoints in modules such as `hbd/server/udp.py`, `hbd/server/dns.py`, or `hbd/server/main.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code.
--- ---
## 🛠 Configuration ## 🛠 Configuration
`hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/config.py`): `hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/server/config.py`):
- `hb_port`: UDP port to listen for heartbeats (default: 50003) - `hb_port`: UDP port to listen for heartbeats (default: 50003)
- `hbd_port`: internal control port (default: 50004) - `hbd_port`: internal control port (default: 50004)
@@ -487,29 +496,39 @@ nsupdate_bin: /usr/bin/nsupdate
pushsrv: pushover pushsrv: pushover
``` ```
> Tip: `config.DEFAULTS` in `hbd/config.py` contains the canonical defaults and accepted configuration keys. > Tip: `SERVER_DEFAULTS` in `hbd/server/config.py` contains the canonical defaults and accepted configuration keys.
--- ---
## 🔧 Architecture & Modules ## 🔧 Architecture & Modules
- `hbd.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data) The package is organized into three subpackages:
- `hbd.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
- `hbd.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`). **`hbd.common`** — shared code used by both client and server:
The DNS worker now runs as an `asyncio` task and the package exposes a - `hbd.common.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data)
small thread-safe bridge so legacy synchronous code can `put()` updates - `hbd.common.utils` — small utility helpers (`shortname`, `dur`, `initlog`)
into the queue; there is no longer a permanently-blocking background
`threading.Thread`. **`hbd.server`** — the heartbeat daemon (`hbd`):
- `hbd.notify` — email and push notification helpers - `hbd.server.cli` — CLI entrypoint and argument parsing
- `hbd.ws` — WebSocket server and thread-safe broadcast helpers - `hbd.server.main` — async orchestration to run UDP/HTTP/WSS components
- `hbd.http` — HTTP handler factory for the status UI/API - `hbd.server.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
- `hbd.journal` — message journal with size-based log rotation and backup management - `hbd.server.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`).
- `hbd.plugin` — plugin framework with base classes, registry, and dynamic loader The DNS worker runs as an `asyncio` task and the package exposes a small thread-safe bridge
- `hbd.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner) so legacy synchronous code can `put()` updates into the queue.
- `hbd.hbc` — heartbeat client that sends heartbeats and plugin data to server - `hbd.server.notify` — email and push notification helpers
- `hbd.utils` — small utility helpers (`shortname`, `dur`, `initlog`) - `hbd.server.ws` — WebSocket server and thread-safe broadcast helpers
- `hbd.cli` — CLI entrypoint and argument parsing - `hbd.server.http` — HTTP handler factory for the status UI/API
- `hbd.server` — async orchestration to run UDP/HTTP/WSS components - `hbd.server.journal` — message journal with size-based log rotation and backup management
- `hbd.server.threshold` — threshold alerting engine
- `hbd.server.monitor` — host state monitoring
- `hbd.server.hbdclass` — `Host` class and shared server state
- `hbd.server.config` — configuration loader and defaults
**`hbd.client`** — the heartbeat client (`hbc`):
- `hbd.client.main` — client entrypoint; sends heartbeats and plugin data to the server
- `hbd.client.plugin` — plugin framework with base classes, registry, and dynamic loader
- `hbd.client.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner)
- `hbd.client.config` — client configuration loader
This modular layout makes the code easier to test and maintain. This modular layout makes the code easier to test and maintain.
@@ -517,12 +536,12 @@ This modular layout makes the code easier to test and maintain.
- The main runtime is asyncio-based. Services (UDP listener, HTTP server, WebSocket server, monitor, and DNS worker) run as asyncio tasks. - The main runtime is asyncio-based. Services (UDP listener, HTTP server, WebSocket server, monitor, and DNS worker) run as asyncio tasks.
- On SIGINT/SIGTERM the server triggers a graceful shutdown: it cancels active tasks, signals the DNS worker via a sentinel, and cleans up resources before exit. - On SIGINT/SIGTERM the server triggers a graceful shutdown: it cancels active tasks, signals the DNS worker via a sentinel, and cleans up resources before exit.
- The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.hbdclass.Host.dnsQ`. - The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.server.hbdclass.Host.dnsQ`.
**Templates & Static Files** **Templates & Static Files**
- Template files are located under `hbd/templates` by default. The HTTP server resolves templates relative to the `hbd` package but the path can be overridden with the `templates_dir` config key. - Template files are located under `hbd/server/templates`. The HTTP server resolves templates relative to the `hbd.server` package but the path can be overridden with the `templates_dir` config key.
- Static assets (CSS/JS/images) are served from `hbd/static` via the `/static/<path>` HTTP route. Place your static files in that directory or configure the HTTP server as needed. - Static assets (CSS/JS/images) are served from `hbd/server/static` via the `/static/<path>` HTTP route.
--- ---