Metadata-Version: 2.4
Name: ntpxyz
Version: 0.1.1
Summary: The NTP Statistics Toolkit
License-Expression: MIT
License-File: LICENSE
Keywords: ntp,ntpd,statistics,monitoring,time-synchronization,loopstats,sysstats,usestats,allantools,allan-deviation,plots,visualization
Author: Bronson Trevor
Author-email: bronson.trevor@gmail.com
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Networking :: Time Synchronization
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Intended Audience :: System Administrators
Classifier: Development Status :: 4 - Beta
Requires-Dist: allantools (>=2024.6)
Requires-Dist: matplotlib (>=3.10.0)
Requires-Dist: numpy (>=2.3.5)
Requires-Dist: pandas (>=2.3.0)
Requires-Dist: requests (>=2.32.5)
Project-URL: Documentation, https://github.com/brontsor/ntpxyz#readme
Project-URL: Homepage, https://github.com/brontsor/ntpxyz
Project-URL: Issues, https://github.com/brontsor/ntpxyz/issues
Project-URL: Repository, https://github.com/brontsor/ntpxyz
Description-Content-Type: text/markdown

# ntpxyz: The NTP Statistics Toolkit

ntpxyz is a lightweight Python tool for parsing and visualizing statistics from NTP servers. It processes standard NTP stats logs—currently loopstats (clock sync), sysstats (network traffic), and usestats (host utilization)—then generates clear, insightful plots using Matplotlib. Designed for both interactive use and automated batch runs, ntpxyz helps monitor NTP server health with minimal fuss.

Whether you're troubleshooting sync issues, analyzing traffic patterns, or checking resource usage, ntpxyz turns raw logs into actionable visuals. It supports command-line options, JSON configs for defaults, and even Telegram notifications for remote or DMZ setups.

[![PyPI version](https://badge.fury.io/py/ntpxyz.svg)](https://badge.fury.io/py/ntpxyz)  <!-- Placeholder; update post-PyPI -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Example Plots

### loopstats

![loopstats](./examples/plots/host-001/ntpxyz_loopstats.png)

### sysstats

![sysstats](./examples/plots/host-001/ntpxyz_sysstats.png)

### usestats

![usestats](./examples/plots/host-001/ntpxyz_usestats.png)

## Features

- **Supported Stats**: Loopstats (offset, drift, Allan deviation), sysstats (packets, errors, efficiency), usestats (CPU, memory, I/O).
- **Flexible Input**: Parse single files or scan directories; filter by rolling periods (e.g., last week, month).
- **Output Options**: Save plots as PNG, PDF, or SVG; send via Telegram for unattended alerts.
- **Configurable**: CLI flags or `~/.config/ntpxyz/config.json` for overrides (e.g., save dir, Telegram tokens).
- **Robust**: Handles date conversions from NTP's MJD format; basic validation and error logging.

Roadmap includes more stats types, better date filtering, data exports, and comparisons—see [roadmap.md](docs/roadmap.md) for details.

## Installation

ntpxyz requires Python 3.11+. Install via pip:

```bash
pip install ntpxyz
```

From source (clone and install editable for dev):

```bash
git clone https://github.com/brontsor/ntpxyz.git
cd ntpxyz
poetry install  # Or pip install -e .
```

Dependencies: allantools, matplotlib, numpy, pandas, requests (all handled by Poetry/pip).

## Usage

Run with `ntpxyz` (or `python -m ntpxyz`). Provide at least one input source: `--loadconfig`, `--scandir`, or `--scanfile`.

```text
usage: ntpxyz [-h] [-v] [-c CFG] [-p TIME] [-s DIR] [-f FMT] [-n NAME] [-d DIR] [-l FILE]
              [-y TYPE] [-t]

ntpxyz - The NTP Statistics Toolkit

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -c, --loadconfig CFG  load values from ConFiG file (e.g., ~/.config/ntpxyz/config.json)
  -p, --period TIME     specify a TIME period for scandir (e.g., rolling-week)
  -s, --savedir DIR     DIRectory to save output files (default: current dir)
  -f, --saveformat FMT  ForMaT of output: pdf, png, svg (default: png)
  -n, --savename NAME   prefix for output file NAME (default: ntpxyz)
  -d, --scandir DIR     scan a DIRectory for stats files and parse all valid matches
  -l, --scanfile FILE   path to a specific ntp statistics FILE (overrides scandir)
  -y, --statstype TYPE  override detected stats type: loopstats, sysstats, usestats
  -t, --telegram        send plot(s) to Telegram (requires config with chat_id/telegram_token)

One of --loadconfig, --scandir, or --scanfile is required. CLI flags override config values.
```

### Examples

Process a directory of logs for the last week:

```bash
ntpxyz --scandir /var/log/ntpstats --period rolling-week --saveformat png
```

This scans for all supported stats types, generates plots, and saves them in the current directory as `ntpxyz_loopstats.png`, etc.

Load from config and send to Telegram:

```bash
ntpxyz --loadconfig ~/.config/ntpxyz/config.json --telegram
```

Example `config.json`. Note that passing in an option via CLI overrides the config file value.

```json
{
  "scandir": "/var/log/ntpstats",
  "period": "rolling-month",
  "telegram_token": "your-bot-token",
  "chat_id": "your-chat-id",
  "telegram": true
}
```

Single file with custom name:

```bash
ntpxyz --scanfile /var/log/ntpstats/loopstats.202601 --savename my_ntp_plots
```

For setup details on Telegram, see [telegram_setup.md](docs/telegram_setup.md).

### Known Limitations

- Periods only apply to `--scandir`.
- Telegram may hit file size limits for PDFs; use PNG.
- More stats types (e.g., peerstats) in future releases.

Example outputs and logs: Check the `examples/` directory for sample data and plots.

## Contributing

Contributions welcome! Fork the repo, create a feature branch (`git checkout -b feature/my-addition`), commit atomically, and open a PR. Run `pre-commit run --all-files` before pushing.

Install dev deps: `poetry install --only dev`.

Test: `poetry run pytest`.

Lint/Typecheck: `poetry run ruff check .`, `poetry run mypy .`, `poetry run pyright`.

See [roadmap.md](docs/roadmap.md) for priorities.

## License

MIT License—see [LICENSE](LICENSE) for details.

---

Questions? Open an issue or reach out. Happy wandering!

