# dt-pinger
**dt-pinger** is a Python script for gathering ping statistics for one or more target hosts.
It can be imported into python project, or used as a cli.
**dt-pinger** can be used to:
- identify devices that are up or down on the network
- identify and trouble shoot network issues (dropped packets, network congestion, ...)
**dt-pinger**
- Only uses standard python modules
- Tested on Windows and Linux
- Provides output in multiple formats (csv, json, text)
- Is a single python file, not requiring any additional resources
Statistics captured for each host are:
- ping timestamp
- Source hostname
- Target hostname
- Packet information (sent, received, lost)
- Round Trip Time ms (minimum, maximum, average)
---
---
## Installation
To install/use **dt-pinger**, you may:
| Use | Command |
| ------------- | --------------------------|
| github [source](https://github.com/JavaWiz1/dt-pinger) | git clone https://github.com/JavaWiz1/dt-pinger.git |
| [pip ](https://pip.pypa.io/en/stable/) | pip install dt-pinger [--user] |
| [pipx](https://pipx.pypa.io/stable/) | pipx install dt-pinger |
---
---
## CLI Usage
```
usage: dt_pinger.py [-h] [-i FILENAME] [-o {raw,csv,json,jsonf,text}] [-c COUNT] [-w WAIT] [-v] [host ...]
Ping one or more hosts, output packet and rtt data in json, csv or text format.
positional arguments:
host List of one or more hosts to ping
options:
-h, --help show this help message and exit
-i FILENAME, --input FILENAME
Input file with hostnames 1 per line
-o {raw,csv,json,jsonf,text}, --output {raw,csv,json,jsonf,text}
Output format (default text)
-c COUNT, --count COUNT
number of requests to send (default 4)
-w WAIT, --wait WAIT milliseconds to wait before timeout (default 2000)
-v, --verbose
Either host OR -i/--input parameter is REQUIRED.
```
### Parameters
You must supply **EITHER** host(s) or the -i/--input parameter **NOT BOTH**.
| parameter | Req/Opt | description |
| ------------ | ------- | -------------------------------------------------------|
| host | req | one or more host names seperated by space (i.e. host1 host2 host3 ...) |
| -i / --input | req | text file containing hostnames <ul><li>1 host per line<li>Any lines beginning with # will be ignored and treated as a comment line</li></ul> |
| -o / --output | opt | output type <ul><li>**text** default if omitted<li>**raw** will output results as raw dictionary</li<li>**json** will output an unformatted json string</li><li>**jsonf** will output a formatted json string</li><li>**csv** will create a csv for use in excel</li></ul> |
| -c / --count | opt | Number of echo packets to send, default 4 |
| -w / --wait | opt | Wait time for response (ms windows, secs linux), default 2 seconds |
#### Running from python source
When running from the source code, cd to the source directory, then run by using one of the following commands...
<ul><ul>
<li><code>python dt_pinger.py <i>host1 [[host2][host3]...]</i></code></li>
<li><code>python dt_pinger.py -i <i>hostlist.txt</i></code></li>
</ul></ul>
#### If installed via pip or pipx
The install creates an [entrypoint](https://packaging.python.org/en/latest/specifications/entry-points/) so that
the script can be called like an executable.
<ul><ul>
<li><code>dt-pinger <i>host1 [[host2][host3]...]</i></code></li>
<li><code>dt-pinger -i <i>hostlist.txt</i></code></li>
</ul></ul>
**NOTE:**
`python dt_pinger.py host1` and `dt-pinger host1` are identical.
---
---
## Examples
### CLI
Run ping statistics against 6 hosts and output in text format to the console...
```
python dt_pinger.py pc1 pc2 pc3 pc4 pc5 google.com
----------------------------------------
dt-pinger parameters
----------------------------------------
Source host : my-laptop
Target hosts : 6
Worker threads : 6
Req per host : 4
Wait timeout : 2000 (ms)
Packets RTT
Source Target Sent Recv Lost Min Max Avg Error Msg
--------------- -------------------- ---- ---- ---- ---- ---- ---- --------------------------------------
my-laptop pc1 4 4 0 2 6 3
my-laptop pc2 4 4 0 6 9 8
my-laptop pc3 4 4 0 4 5 4
my-laptop pc4 0 0 0 0 0 0 (1) offline?
my-laptop pc5 4 4 0 6 18 11
my-laptop google.com 4 4 0 29 32 31
6 hosts processed in 7.2 seconds.
```
Run ping statistics against 5 hosts and output as csv into a file...
```
python dt_pinger.py pc1 pc2 pc3 pc4 google.com -o csv > pinger.csv
----------------------------------------
dt-pinger parameters
----------------------------------------
Source host : my-laptop
Target hosts : 5
Worker threads : 5
Req per host : 4
Wait timeout : 2000 (ms)
5 hosts processed in 3.5 seconds.
```
output file contains:
```
timestamp,source,target,pkt_sent,pkt_recv,pkt_lost,rtt_min,rtt_max,rtt_avg,error
08/01/2024 10:31:58,my-laptop,pc1, 4,4,0,3,4,3,
08/01/2024 10:31:58,my-laptop,pc2, 4,4,0,4,5,4,
08/01/2024 10:31:58,my-laptop,pc3, 4,4,0,4,12,6,
08/01/2024 10:31:58,my-laptop,pc4, 0,0,0,0,0,0,(1) offline?
08/01/2024 10:31:58,my-laptop,google.com, 4,4,0,29,32,30,
```
### Used as an imported class
```python
from dt_pinger import Pinger
pinger = Pinger('google.com')
pinger.ping_targets()
print(pinger.results) # Output raw results object
pinger = Pinger(['google.com', 'pc1', 'msn.com'])
pinger.ping_targets()
pinger.output() # Output formatted text
```
the program can print formated results as follows:
```python
pinger.output() # defaults to formatted text output
pinger.output() # raw - dictionary format
pinger.output('csv') # csv - comma seperated
pinger.output('json') # json string
pinger.output('jsonf') # formatted json string
pinger.output('text') # formatted text (default)
```
```pinger.results``` is a dictionary keyed by hostname. For each host, packet and round trip time statistics are captured.
| Key | Value |
| --- | ----- |
| hostname | target hostname of device being pinged |
| hostname['packets'] | dictionary of packet statistics |
| hostname['packets']['sent'] | ping echo requests sent |
| hostname['packets']['received'] | request responses received |
| hostname['packets']['lost'] | requests lost/dropped |
| hostname['rtt_ms'] | dictionary of rtt statistics |
| hostname['rtt_ms']['min'] | round trip time minimum |
| hostname['rtt_ms']['max'] | round trip time maximum |
| hostname['rtt_ms']['avg'] | round trip time average |
| hostname['error'] | Error if ping was unsuccessful |
ex.
```
{'google.com':
{
'packets': {'sent': 4, 'received': 4, 'lost': 0},
'rtt_ms': {'min': 27, 'max': 34, 'avg': 30},
'error': ''
}
}
```
---
---
## Tips
1. Console messages are sent to stderr, output data to stdout. You can redirect stdout, to create a file with just
the csv (or json) as follows:
```
python dt_pinger.py pc1 pc2 pc3 -o csv > pinger.csv
```
or
```
python dt_pinger.py pc1 pc2 pc3 -o json > pinger.json
```
2. If installed via pip or pipx, an [entrypoint](https://packaging.python.org/en/latest/specifications/entry-points/) was created (i.e. dt-pinger.exe),
so as long as you have the proper path, you can run dt-pinger (instead of cd to proper directory and running python dt_pinger.py).<br>
**Note:** dt_pinger.py vs. dt-pinger.exe (underscore vs. hyphen)
Raw data
{
"_id": null,
"home_page": "https://github.com/JavaWiz1/dt-pinger",
"name": "dt-pinger",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "ping, network tool, cli, python",
"author": "Al DAmico",
"author_email": "JavaWiz1@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/54/6a/6be75e16c61963237ae66c3a851d41d0a24eb1fa8cbdeead1a820ca6221e/dt_pinger-0.1.3.tar.gz",
"platform": null,
"description": "# dt-pinger\n\n**dt-pinger** is a Python script for gathering ping statistics for one or more target hosts.\nIt can be imported into python project, or used as a cli. \n\n**dt-pinger** can be used to:\n- identify devices that are up or down on the network\n- identify and trouble shoot network issues (dropped packets, network congestion, ...)\n\n**dt-pinger** \n- Only uses standard python modules\n- Tested on Windows and Linux\n- Provides output in multiple formats (csv, json, text)\n- Is a single python file, not requiring any additional resources\n\nStatistics captured for each host are:\n- ping timestamp\n- Source hostname\n- Target hostname\n- Packet information (sent, received, lost)\n- Round Trip Time ms (minimum, maximum, average)\n\n---\n---\n\n## Installation\n\nTo install/use **dt-pinger**, you may: \n\n| Use | Command |\n| ------------- | --------------------------|\n| github [source](https://github.com/JavaWiz1/dt-pinger) | git clone https://github.com/JavaWiz1/dt-pinger.git |\n| [pip ](https://pip.pypa.io/en/stable/) | pip install dt-pinger [--user] |\n| [pipx](https://pipx.pypa.io/stable/) | pipx install dt-pinger | \n\n---\n---\n\n## CLI Usage\n\n```\nusage: dt_pinger.py [-h] [-i FILENAME] [-o {raw,csv,json,jsonf,text}] [-c COUNT] [-w WAIT] [-v] [host ...]\n\nPing one or more hosts, output packet and rtt data in json, csv or text format.\n\npositional arguments:\n host List of one or more hosts to ping\n\noptions:\n -h, --help show this help message and exit\n -i FILENAME, --input FILENAME\n Input file with hostnames 1 per line\n -o {raw,csv,json,jsonf,text}, --output {raw,csv,json,jsonf,text}\n Output format (default text)\n -c COUNT, --count COUNT\n number of requests to send (default 4)\n -w WAIT, --wait WAIT milliseconds to wait before timeout (default 2000)\n -v, --verbose\n\nEither host OR -i/--input parameter is REQUIRED.\n```\n\n### Parameters\n\nYou must supply **EITHER** host(s) or the -i/--input parameter **NOT BOTH**.\n\n| parameter | Req/Opt | description |\n| ------------ | ------- | -------------------------------------------------------|\n| host | req | one or more host names seperated by space (i.e. host1 host2 host3 ...) |\n| -i / --input | req | text file containing hostnames <ul><li>1 host per line<li>Any lines beginning with # will be ignored and treated as a comment line</li></ul> |\n| -o / --output | opt | output type <ul><li>**text** default if omitted<li>**raw** will output results as raw dictionary</li<li>**json** will output an unformatted json string</li><li>**jsonf** will output a formatted json string</li><li>**csv** will create a csv for use in excel</li></ul> |\n| -c / --count | opt | Number of echo packets to send, default 4 |\n| -w / --wait | opt | Wait time for response (ms windows, secs linux), default 2 seconds |\n\n\n#### Running from python source\n\nWhen running from the source code, cd to the source directory, then run by using one of the following commands...\n<ul><ul>\n <li><code>python dt_pinger.py <i>host1 [[host2][host3]...]</i></code></li>\n <li><code>python dt_pinger.py -i <i>hostlist.txt</i></code></li>\n</ul></ul>\n\n\n#### If installed via pip or pipx\n\nThe install creates an [entrypoint](https://packaging.python.org/en/latest/specifications/entry-points/) so that\nthe script can be called like an executable. \n<ul><ul>\n <li><code>dt-pinger <i>host1 [[host2][host3]...]</i></code></li>\n <li><code>dt-pinger -i <i>hostlist.txt</i></code></li>\n</ul></ul>\n\n**NOTE:** \n `python dt_pinger.py host1` and `dt-pinger host1` are identical.\n\n---\n---\n\n## Examples\n\n### CLI\nRun ping statistics against 6 hosts and output in text format to the console...\n```\npython dt_pinger.py pc1 pc2 pc3 pc4 pc5 google.com\n\n----------------------------------------\ndt-pinger parameters\n----------------------------------------\n Source host : my-laptop\n Target hosts : 6\n Worker threads : 6\n Req per host : 4\n Wait timeout : 2000 (ms)\n\n Packets RTT\nSource Target Sent Recv Lost Min Max Avg Error Msg\n--------------- -------------------- ---- ---- ---- ---- ---- ---- --------------------------------------\nmy-laptop pc1 4 4 0 2 6 3\nmy-laptop pc2 4 4 0 6 9 8\nmy-laptop pc3 4 4 0 4 5 4\nmy-laptop pc4 0 0 0 0 0 0 (1) offline?\nmy-laptop pc5 4 4 0 6 18 11 \nmy-laptop google.com 4 4 0 29 32 31\n\n6 hosts processed in 7.2 seconds.\n```\n\nRun ping statistics against 5 hosts and output as csv into a file...\n```\npython dt_pinger.py pc1 pc2 pc3 pc4 google.com -o csv > pinger.csv\n\n----------------------------------------\ndt-pinger parameters\n----------------------------------------\n Source host : my-laptop\n Target hosts : 5\n Worker threads : 5\n Req per host : 4\n Wait timeout : 2000 (ms)\n\n\n5 hosts processed in 3.5 seconds.\n```\noutput file contains:\n```\ntimestamp,source,target,pkt_sent,pkt_recv,pkt_lost,rtt_min,rtt_max,rtt_avg,error\n08/01/2024 10:31:58,my-laptop,pc1, 4,4,0,3,4,3,\n08/01/2024 10:31:58,my-laptop,pc2, 4,4,0,4,5,4,\n08/01/2024 10:31:58,my-laptop,pc3, 4,4,0,4,12,6,\n08/01/2024 10:31:58,my-laptop,pc4, 0,0,0,0,0,0,(1) offline?\n08/01/2024 10:31:58,my-laptop,google.com, 4,4,0,29,32,30,\n```\n\n\n### Used as an imported class\n\n```python\nfrom dt_pinger import Pinger\n\npinger = Pinger('google.com')\npinger.ping_targets()\nprint(pinger.results) # Output raw results object\n\npinger = Pinger(['google.com', 'pc1', 'msn.com'])\npinger.ping_targets()\npinger.output() # Output formatted text\n```\n\nthe program can print formated results as follows:\n\n```python\npinger.output() # defaults to formatted text output\npinger.output() # raw - dictionary format\npinger.output('csv') # csv - comma seperated\npinger.output('json') # json string\npinger.output('jsonf') # formatted json string\npinger.output('text') # formatted text (default)\n```\n\n```pinger.results``` is a dictionary keyed by hostname. For each host, packet and round trip time statistics are captured.\n\n| Key | Value |\n| --- | ----- |\n| hostname | target hostname of device being pinged |\n| hostname['packets'] | dictionary of packet statistics |\n| hostname['packets']['sent'] | ping echo requests sent |\n| hostname['packets']['received'] | request responses received |\n| hostname['packets']['lost'] | requests lost/dropped |\n| hostname['rtt_ms'] | dictionary of rtt statistics |\n| hostname['rtt_ms']['min'] | round trip time minimum |\n| hostname['rtt_ms']['max'] | round trip time maximum |\n| hostname['rtt_ms']['avg'] | round trip time average |\n| hostname['error'] | Error if ping was unsuccessful |\n\nex.\n```\n{'google.com': \n {\n 'packets': {'sent': 4, 'received': 4, 'lost': 0}, \n 'rtt_ms': {'min': 27, 'max': 34, 'avg': 30}, \n 'error': ''\n }\n}\n```\n\n---\n---\n## Tips\n1. Console messages are sent to stderr, output data to stdout. You can redirect stdout, to create a file with just \nthe csv (or json) as follows:\n```\npython dt_pinger.py pc1 pc2 pc3 -o csv > pinger.csv\n```\nor\n```\npython dt_pinger.py pc1 pc2 pc3 -o json > pinger.json\n```\n\n2. If installed via pip or pipx, an [entrypoint](https://packaging.python.org/en/latest/specifications/entry-points/) was created (i.e. dt-pinger.exe), \n so as long as you have the proper path, you can run dt-pinger (instead of cd to proper directory and running python dt_pinger.py).<br>\n **Note:** dt_pinger.py vs. dt-pinger.exe (underscore vs. hyphen)",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Ping tester",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/JavaWiz1/dt-pinger",
"Repository": "https://github.com/JavaWiz1/dt-pinger"
},
"split_keywords": [
"ping",
" network tool",
" cli",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93867c21a2aecf5242f2470176e25320f63bb88a7cc9a4ebb36f72cb751967ac",
"md5": "5ec84cabd585766d64601f2b3c40ca54",
"sha256": "ae376d388e7d0e7395685dd38b60fea22c1abfa6e79ac2b11de77081c0db24b4"
},
"downloads": -1,
"filename": "dt_pinger-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ec84cabd585766d64601f2b3c40ca54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 9800,
"upload_time": "2024-08-12T03:32:05",
"upload_time_iso_8601": "2024-08-12T03:32:05.235956Z",
"url": "https://files.pythonhosted.org/packages/93/86/7c21a2aecf5242f2470176e25320f63bb88a7cc9a4ebb36f72cb751967ac/dt_pinger-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "546a6be75e16c61963237ae66c3a851d41d0a24eb1fa8cbdeead1a820ca6221e",
"md5": "43f96415a0df4efb735d81d807db7a1a",
"sha256": "eca0663b4862578a306e0481f54ad8ca76f3179bf91bc663e226a05249300dcc"
},
"downloads": -1,
"filename": "dt_pinger-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "43f96415a0df4efb735d81d807db7a1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 9241,
"upload_time": "2024-08-12T03:32:06",
"upload_time_iso_8601": "2024-08-12T03:32:06.793107Z",
"url": "https://files.pythonhosted.org/packages/54/6a/6be75e16c61963237ae66c3a851d41d0a24eb1fa8cbdeead1a820ca6221e/dt_pinger-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 03:32:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JavaWiz1",
"github_project": "dt-pinger",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dt-pinger"
}
JSON
