# NLM: Network Latency Monitor
<!--toc:start-->
- [Installation](#installation)
- [Installation via pip](#installation-via-pip)
- [Install from Source](#install-from-source)
- [Usage](#usage)
- [Configuration](#configuration)
- [Running the Program](#running-the-program)
- [Usage Examples](#usage-examples)
- [Contributing](#contributing)
- [How to Contribute](#how-to-contribute)
- [License](#license)
- [Roadmap](#roadmap)
- [Support](#support)
- [Acknowledgments](#acknowledgments)
- [Documentation](#documentation)
<!--toc:end-->
[](https://pypi.org/project/network-latency-monitor/)
[](https://pypi.org/project/network-latency-monitor/)
[](https://opensource.org/licenses/MIT)
NLM is a tool designed to monitor network latency across specified IP
addresses, providing real-time feedback through progress bars and
latency graphs.
It also collects data, and plots graphs using `seaborn` to visualize latency data.
Real-time charts are drawn in the terminal using `asciichartpy`.
**Features include:**
- **Asynchronous Ping Monitoring**: Efficiently pings multiple IP
addresses simultaneously.
- **Real-time ASCII-based Latency Graphs**: Visualizes latency data
directly in the terminal.
- **OS-specific Directory Management**: Manages logs, results, and
plots in OS-specific directories.
- **Comprehensive Documentation**: Generated from code docstrings for
accuracy and consistency.
## Installation
You can install **NLM** (Network Latency Monitor) using
`pip` from PyPI.
### Installation via pip
```bash
pip install network-latency-monitor
```
### Install from Source
To install **NLM** from source, follow these steps:
**Prerequisites**
- Python
- Poetry
1. **Clone the Repository**
```bash
git clone https://github.com/yourusername/network-latency-monitor.git
cd network-latency-monitor
```
2. **Install Dependencies with Poetry**
```bash
poetry install
```
3. **Activate the Virtual Environment**
```bash
poetry shell
```
4. **Verify Installation**
```bash
poetry shell
poetry run nlm --help
```
4. **Build the Documentation (Optional)**
```bash
cd docs
make html
```
5. **View the Documentation**
Open `docs/build/html/index.html` in your web browser
After installing **NLM**, you can start monitoring network latency.
## Usage
### Configuration
Before running NLM, configure your settings in the
[config.yaml]{.title-ref} file.
**Sample `config.yaml`:**
```yaml
"duration": 10800,
"ip_addresses": ["8.8.8.8"],
"ping_interval": 1, # in seconds
"latency_threshold": 200.0, # in ms
"no_aggregation": False,
"no_segmentation": False,
"file": None, # Optional: Specify a ping result file to process
"clear": False, # Set to True to clear all data
"clear_results": False, # Set to True to clear results folder
"clear_plots": False, # Set to True to clear plots folder
"clear_logs": False, # Set to True to clear logs folder
"yes": False, # Set to True to auto-confirm prompts
"verbosity": 0 # 0: Normal, 1: Verbose, 2: Debug
```
The `config.yaml` file is auto-generated the first time that
the program is run. It is saved in default directories based on your
operating system.
For Linux users: `/home/username/.config/network_latency_monitor/config.yaml`
For Windows users: `%APPDATA%\nlm\config.yaml`
For MacOS users: `~/Library/Application Support/nlm/config.yaml`
### Running the Program
**Running from Source**
If you have installed from source using [poetry]{.title-ref}, then you
can run the program using [poetry run]{.title-ref}.
To run the program with all default parameters (as obtained from [config.yaml]{.title-ref}):
```bash
poetry run nlm
```
**Running from Pip Installation**
If you are running the program after installing it through
`pip`, you can run it simply by:
```bash
nlm
```
This will run the program with default parameters as obtained from
`config.yaml`.
To view all command-line options and a simple guide, run
```bash
nlm --help
```
### Usage Examples
- Monitor two IP addresses for 1 hour with a 2-second interval between pings:
```bash
nlm 8.8.8.8 1.1.1.1 --duration 3600 --ping-interval 2
```
- Process an existing ping results file and disable data aggregation:
```bash
nlm --file results/ping_results_8.8.8.8.txt --no-aggregation
```
- Clear all data (results, plots, logs) without confirmation:
```bash
nlm --clear --yes
```
- Monitor a single IP address with a custom latency threshold:
```bash
nlm 8.8.4.4 --latency-threshold 150.0
```
- Regenerate the default `config.yaml` file:
```bash
nlm --regen-config
```
- Disable segmentation of latency plots:
```bash
nlm 8.8.8.8 --no-segmentation
```
- Monitor a single IP for 2 hours, with default settings:
```bash
nlm 8.8.8.8 --duration 7200
```
- Run the program with default parameters, but no output to the terminal:
```bash
nlm -q
```
- Run the program with log-level information printed to the terminal:
```bash
nlm -v
```
- Run the program with debug-level logs printed to the terminal:
```bash
nlm -vv
```
- Clear only the plots folder:
```bash
nlm --clear-plots
```
## Contributing
Contributions are welcome! If you have suggestions for new features, bug fixes, or improvements, feel free to open an issue or submit a pull request.
### How to Contribute
1. **Fork the repository** to your GitHub account.
2. **Clone your fork** locally:
```bash
git clone https://github.com/yourusername/network-latency-monitor.git
cd network-latency-monitor
```
3. Monitor a single IP for 2 hours, with default settings:
```bash
git checkout -b feature-branch-name
```
4. Make your changes and ensure the code passes any pre-existing tests or linters.
5. Push your changes to your forked repository:
```bash
git push origin feature-branch-name
```
6. Submit a pull request to the `main` branch.
## License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more details.
## Roadmap
The following features and improvements are planned for future releases of **NLM (Network Latency Monitor)**:
1. **Add Support for Multiple Protocols**: Extend support for protocols beyond ICMP (e.g., TCP, UDP) to enable more comprehensive network monitoring.
2. **Data Export Options**: Allow users to export monitoring data in multiple formats such as CSV, JSON, and XML for easier data processing and analysis.
3. **Custom Results and Plots Directory**:
Add command-line options to specify custom directories for storing results and plots, making the tool more flexible for use in shell scripts and automated environments.
4. **Improved Plotting Options** (Future): Enhance plotting capabilities with customizable graph styles, better scaling, and export options to PNG and other formats.
## Support
If you encounter any issues, feel free to open an issue on [GitHub Issues](https://github.com/m-usaid99/Network-Latency-Monitor/issues).
## Acknowledgments
- [asciichartpy](https://github.com/kroitor/asciichart) for the ASCII-based chart rendering.
- [Poetry](https://python-poetry.org/) for Python packaging and dependency management.
## Documentation
Full documentation for **NLM (Network Latency Monitor)** is available at [Read the Docs](https://network-latency-monitor.readthedocs.io/en/latest/).
The documentation includes:
- **Installation Instructions**: Step-by-step guide for installing the tool.
- **Usage Examples**: Detailed usage examples and advanced configurations.
- **API Reference**: Auto-generated API reference from code docstrings.
For detailed information, visit the [NLM Documentation](https://network-latency-monitor.readthedocs.io/en/latest/).
Raw data
{
"_id": null,
"home_page": "https://github.com/m-usaid99/Network-Latency-Monitor",
"name": "network-latency-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "network, latency, monitoring, ping",
"author": "Muhammad Usaid Rehman",
"author_email": "rehman.usaid@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b8/63/828debfefdc1c837a37016ba0c628fe7fb9e94eafc58a550a7b97803d217/network_latency_monitor-0.2.2.tar.gz",
"platform": null,
"description": "# NLM: Network Latency Monitor\n\n<!--toc:start-->\n\n- [Installation](#installation)\n - [Installation via pip](#installation-via-pip)\n - [Install from Source](#install-from-source)\n- [Usage](#usage)\n - [Configuration](#configuration)\n- [Running the Program](#running-the-program)\n - [Usage Examples](#usage-examples)\n- [Contributing](#contributing)\n - [How to Contribute](#how-to-contribute)\n- [License](#license)\n- [Roadmap](#roadmap)\n- [Support](#support)\n- [Acknowledgments](#acknowledgments)\n- [Documentation](#documentation)\n<!--toc:end-->\n\n\n[](https://pypi.org/project/network-latency-monitor/)\n[](https://pypi.org/project/network-latency-monitor/)\n[](https://opensource.org/licenses/MIT)\n\nNLM is a tool designed to monitor network latency across specified IP\naddresses, providing real-time feedback through progress bars and\nlatency graphs.\n\nIt also collects data, and plots graphs using `seaborn` to visualize latency data.\nReal-time charts are drawn in the terminal using `asciichartpy`.\n\n**Features include:**\n\n- **Asynchronous Ping Monitoring**: Efficiently pings multiple IP\n addresses simultaneously.\n- **Real-time ASCII-based Latency Graphs**: Visualizes latency data\n directly in the terminal.\n- **OS-specific Directory Management**: Manages logs, results, and\n plots in OS-specific directories.\n- **Comprehensive Documentation**: Generated from code docstrings for\n accuracy and consistency.\n\n## Installation\n\nYou can install **NLM** (Network Latency Monitor) using\n`pip` from PyPI.\n\n### Installation via pip\n\n```bash\npip install network-latency-monitor\n```\n\n### Install from Source\n\nTo install **NLM** from source, follow these steps:\n\n**Prerequisites**\n\n- Python\n- Poetry\n\n1. **Clone the Repository**\n\n```bash\ngit clone https://github.com/yourusername/network-latency-monitor.git\ncd network-latency-monitor\n```\n\n2. **Install Dependencies with Poetry**\n\n```bash\n poetry install\n```\n\n3. **Activate the Virtual Environment**\n\n```bash\npoetry shell\n```\n\n4. **Verify Installation**\n\n```bash\npoetry shell\npoetry run nlm --help\n```\n\n4. **Build the Documentation (Optional)**\n\n```bash\ncd docs\nmake html\n```\n\n5. **View the Documentation**\n\n Open `docs/build/html/index.html` in your web browser\n\nAfter installing **NLM**, you can start monitoring network latency.\n\n## Usage\n\n### Configuration\n\nBefore running NLM, configure your settings in the\n[config.yaml]{.title-ref} file.\n\n**Sample `config.yaml`:**\n\n```yaml\n\"duration\": 10800,\n\"ip_addresses\": [\"8.8.8.8\"],\n\"ping_interval\": 1, # in seconds\n\"latency_threshold\": 200.0, # in ms\n\"no_aggregation\": False,\n\"no_segmentation\": False,\n\"file\": None, # Optional: Specify a ping result file to process\n\"clear\": False, # Set to True to clear all data\n\"clear_results\": False, # Set to True to clear results folder\n\"clear_plots\": False, # Set to True to clear plots folder\n\"clear_logs\": False, # Set to True to clear logs folder\n\"yes\": False, # Set to True to auto-confirm prompts\n\"verbosity\": 0 # 0: Normal, 1: Verbose, 2: Debug\n```\n\nThe `config.yaml` file is auto-generated the first time that\nthe program is run. It is saved in default directories based on your\noperating system.\n\nFor Linux users: `/home/username/.config/network_latency_monitor/config.yaml`\nFor Windows users: `%APPDATA%\\nlm\\config.yaml`\nFor MacOS users: `~/Library/Application Support/nlm/config.yaml`\n\n### Running the Program\n\n**Running from Source**\n\nIf you have installed from source using [poetry]{.title-ref}, then you\ncan run the program using [poetry run]{.title-ref}.\n\nTo run the program with all default parameters (as obtained from [config.yaml]{.title-ref}):\n\n```bash\npoetry run nlm\n```\n\n**Running from Pip Installation**\n\nIf you are running the program after installing it through\n`pip`, you can run it simply by:\n\n```bash\nnlm\n```\n\nThis will run the program with default parameters as obtained from\n`config.yaml`.\n\nTo view all command-line options and a simple guide, run\n\n```bash\nnlm --help\n```\n\n### Usage Examples\n\n- Monitor two IP addresses for 1 hour with a 2-second interval between pings:\n\n ```bash\n nlm 8.8.8.8 1.1.1.1 --duration 3600 --ping-interval 2\n ```\n\n- Process an existing ping results file and disable data aggregation:\n\n ```bash\n nlm --file results/ping_results_8.8.8.8.txt --no-aggregation\n ```\n\n- Clear all data (results, plots, logs) without confirmation:\n\n ```bash\n nlm --clear --yes\n ```\n\n- Monitor a single IP address with a custom latency threshold:\n\n ```bash\n nlm 8.8.4.4 --latency-threshold 150.0\n ```\n\n- Regenerate the default `config.yaml` file:\n\n ```bash\n nlm --regen-config\n ```\n\n- Disable segmentation of latency plots:\n\n ```bash\n nlm 8.8.8.8 --no-segmentation\n ```\n\n- Monitor a single IP for 2 hours, with default settings:\n\n ```bash\n nlm 8.8.8.8 --duration 7200\n ```\n\n- Run the program with default parameters, but no output to the terminal:\n\n ```bash\n nlm -q\n ```\n\n- Run the program with log-level information printed to the terminal:\n\n ```bash\n nlm -v\n ```\n\n- Run the program with debug-level logs printed to the terminal:\n\n ```bash\n nlm -vv\n ```\n\n- Clear only the plots folder:\n\n ```bash\n nlm --clear-plots\n ```\n\n## Contributing\n\nContributions are welcome! If you have suggestions for new features, bug fixes, or improvements, feel free to open an issue or submit a pull request.\n\n### How to Contribute\n\n1. **Fork the repository** to your GitHub account.\n\n2. **Clone your fork** locally:\n\n ```bash\n git clone https://github.com/yourusername/network-latency-monitor.git\n cd network-latency-monitor\n ```\n\n3. Monitor a single IP for 2 hours, with default settings:\n\n ```bash\n git checkout -b feature-branch-name\n ```\n\n4. Make your changes and ensure the code passes any pre-existing tests or linters.\n\n5. Push your changes to your forked repository:\n\n ```bash\n git push origin feature-branch-name\n ```\n\n6. Submit a pull request to the `main` branch.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more details.\n\n## Roadmap\n\nThe following features and improvements are planned for future releases of **NLM (Network Latency Monitor)**:\n\n1. **Add Support for Multiple Protocols**: Extend support for protocols beyond ICMP (e.g., TCP, UDP) to enable more comprehensive network monitoring.\n\n2. **Data Export Options**: Allow users to export monitoring data in multiple formats such as CSV, JSON, and XML for easier data processing and analysis.\n\n3. **Custom Results and Plots Directory**:\n Add command-line options to specify custom directories for storing results and plots, making the tool more flexible for use in shell scripts and automated environments.\n\n4. **Improved Plotting Options** (Future): Enhance plotting capabilities with customizable graph styles, better scaling, and export options to PNG and other formats.\n\n## Support\n\nIf you encounter any issues, feel free to open an issue on [GitHub Issues](https://github.com/m-usaid99/Network-Latency-Monitor/issues).\n\n## Acknowledgments\n\n- [asciichartpy](https://github.com/kroitor/asciichart) for the ASCII-based chart rendering.\n- [Poetry](https://python-poetry.org/) for Python packaging and dependency management.\n\n## Documentation\n\nFull documentation for **NLM (Network Latency Monitor)** is available at [Read the Docs](https://network-latency-monitor.readthedocs.io/en/latest/).\n\nThe documentation includes:\n\n- **Installation Instructions**: Step-by-step guide for installing the tool.\n- **Usage Examples**: Detailed usage examples and advanced configurations.\n- **API Reference**: Auto-generated API reference from code docstrings.\n\nFor detailed information, visit the [NLM Documentation](https://network-latency-monitor.readthedocs.io/en/latest/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Monitor your network latency using real-time plots and cumulative plots",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://network-latency-monitor.readthedocs.io/en/latest/",
"Homepage": "https://github.com/m-usaid99/Network-Latency-Monitor",
"Repository": "https://github.com/m-usaid99/Network-Latency-Monitor"
},
"split_keywords": [
"network",
" latency",
" monitoring",
" ping"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "67d3b450387527dc1cf2f39138028ea59c503159296f913da74f743ce1edec6e",
"md5": "5bc2eb2817ceb09cae83d047d8f83422",
"sha256": "44f07b92adc99f30eb66bde1ead118750906315f14f8a48ad381f30b2e8ab810"
},
"downloads": -1,
"filename": "network_latency_monitor-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5bc2eb2817ceb09cae83d047d8f83422",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 30735,
"upload_time": "2024-10-16T16:44:32",
"upload_time_iso_8601": "2024-10-16T16:44:32.466840Z",
"url": "https://files.pythonhosted.org/packages/67/d3/b450387527dc1cf2f39138028ea59c503159296f913da74f743ce1edec6e/network_latency_monitor-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b863828debfefdc1c837a37016ba0c628fe7fb9e94eafc58a550a7b97803d217",
"md5": "571a32daa790c3c51d007bdda1f1f1c0",
"sha256": "a5f99e94d147520af321d4373059ba99160a715d51a6725b84e6480c7b8450d1"
},
"downloads": -1,
"filename": "network_latency_monitor-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "571a32daa790c3c51d007bdda1f1f1c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 27397,
"upload_time": "2024-10-16T16:44:34",
"upload_time_iso_8601": "2024-10-16T16:44:34.049627Z",
"url": "https://files.pythonhosted.org/packages/b8/63/828debfefdc1c837a37016ba0c628fe7fb9e94eafc58a550a7b97803d217/network_latency_monitor-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-16 16:44:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "m-usaid99",
"github_project": "Network-Latency-Monitor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "appdirs",
"specs": [
[
"==",
"1.4.4"
]
]
},
{
"name": "asciichartpy",
"specs": [
[
"==",
"1.5.25"
]
]
},
{
"name": "contourpy",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "cycler",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "fonttools",
"specs": [
[
"==",
"4.54.1"
]
]
},
{
"name": "ipaddress",
"specs": [
[
"==",
"1.0.23"
]
]
},
{
"name": "kiwisolver",
"specs": [
[
"==",
"1.4.7"
]
]
},
{
"name": "markdown-it-py",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.9.2"
]
]
},
{
"name": "mdurl",
"specs": [
[
"==",
"0.1.2"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.1.2"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.3"
]
]
},
{
"name": "pillow",
"specs": [
[
"==",
"10.4.0"
]
]
},
{
"name": "pygments",
"specs": [
[
"==",
"2.18.0"
]
]
},
{
"name": "pyparsing",
"specs": [
[
"==",
"3.1.4"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "pytz",
"specs": [
[
"==",
"2024.2"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.9.2"
]
]
},
{
"name": "seaborn",
"specs": [
[
"==",
"0.13.2"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"75.1.0"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "tzdata",
"specs": [
[
"==",
"2024.2"
]
]
}
],
"lcname": "network-latency-monitor"
}
JSON
