telegraf/plugins/inputs/ping/README.md

# Ping Input plugin

This input plugin will measures the round-trip

### Configuration:

```
# NOTE: this plugin forks the ping command. You may need to set capabilities
# via setcap cap_net_raw+p /bin/ping
[[inputs.ping]]
## List of urls to ping
urls = ["www.google.com"] # required
## number of pings to send per collection (ping -c <COUNT>)
# count = 1
## interval, in s, at which to ping. 0 == default (ping -i <PING_INTERVAL>)
## Not available in Windows.
# ping_interval = 1.0
## per-ping timeout, in s. 0 == no timeout (ping -W <TIMEOUT>)
# timeout = 1.0
## total-ping deadline, in s. 0 == no deadline (ping -w <DEADLINE>)
# deadline = 10
## interface or source address to send ping from (ping -I <INTERFACE/SRC_ADDR>)
## on Darwin and Freebsd only source address possible: (ping -S <SRC_ADDR>)
# interface = ""
```

### Measurements & Fields:

- packets_transmitted ( from ping output )
- reply_received ( increasing only on valid metric from echo replay, eg. 'Destination net unreachable' reply will increment packets_received but not reply_received )
- packets_received ( from ping output )
- percent_reply_loss ( compute from packets_transmitted and reply_received )
- percent_packets_loss ( compute from packets_transmitted and packets_received )
- errors ( when host can not be found or wrong parameters is passed to application )
- response time
    - average_response_ms ( compute from minimum_response_ms and maximum_response_ms )
    - minimum_response_ms ( from ping output )
    - maximum_response_ms ( from ping output )
- result_code
    - 0: success
    - 1: no such host
    - 2: ping error

### Tags:

- host
- url

### Example Output:

```
$ ./telegraf --config telegraf.conf --input-filter ping --test
* Plugin: ping, Collection 1
ping,host=WIN-PBAPLP511R7,url=www.google.com result_code=0i,average_response_ms=7i,maximum_response_ms=9i,minimum_response_ms=7i,packets_received=4i,packets_transmitted=4i,percent_packet_loss=0,percent_reply_loss=0,reply_received=4i 1469879119000000000
```
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00			`# Ping Input plugin`
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00
			`This input plugin will measures the round-trip`

ping: fix typo in README (#2163) 2016-12-14 19:47:48 +00:00			`### Configuration:`
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			```
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00			`# NOTE: this plugin forks the ping command. You may need to set capabilities`
			`# via setcap cap_net_raw+p /bin/ping`
			`[[inputs.ping]]`
			`## List of urls to ping`
			`urls = ["www.google.com"] # required`
			`## number of pings to send per collection (ping -c <COUNT>)`
			`# count = 1`
			`## interval, in s, at which to ping. 0 == default (ping -i <PING_INTERVAL>)`
Document that ping_interval is non-linux only 2017-06-16 20:32:04 +00:00			`## Not available in Windows.`
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00			`# ping_interval = 1.0`
			`## per-ping timeout, in s. 0 == no timeout (ping -W <TIMEOUT>)`
			`# timeout = 1.0`
Support deadline in ping plugin (#3783) 2018-02-16 04:11:07 +00:00			`## total-ping deadline, in s. 0 == no deadline (ping -w <DEADLINE>)`
			`# deadline = 10`
Add support for setting bsd source address to the ping input (#3726) 2018-01-29 22:01:00 +00:00			`## interface or source address to send ping from (ping -I <INTERFACE/SRC_ADDR>)`
			`## on Darwin and Freebsd only source address possible: (ping -S <SRC_ADDR>)`
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00			`# interface = ""`
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			```
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			`### Measurements & Fields:`
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			`- packets_transmitted ( from ping output )`
			`- reply_received ( increasing only on valid metric from echo replay, eg. 'Destination net unreachable' reply will increment packets_received but not reply_received )`
			`- packets_received ( from ping output )`
			`- percent_reply_loss ( compute from packets_transmitted and reply_received )`
			`- percent_packets_loss ( compute from packets_transmitted and packets_received )`
Perform DNS lookup before ping (#3385) 2017-10-26 20:35:37 +00:00			`- errors ( when host can not be found or wrong parameters is passed to application )`
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			`- response time`
			`- average_response_ms ( compute from minimum_response_ms and maximum_response_ms )`
			`- minimum_response_ms ( from ping output )`
			`- maximum_response_ms ( from ping output )`
Perform DNS lookup before ping (#3385) 2017-10-26 20:35:37 +00:00			`- result_code`
			`- 0: success`
			`- 1: no such host`
Add result_code value for errors running ping command (#4550) 2018-08-23 20:50:19 +00:00			`- 2: ping error`
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			`### Tags:`
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00
			`- host`
			`- url`
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00
			`### Example Output:`
Update ping-input-plugin Readme (#2651) 2017-04-13 00:46:48 +00:00
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			```
Fix telegraf example arguments (#2788) Many of the examples provided within documentation are using a single dash for the command line arguments, but the telegraf executable explicitly has two dashes. There are also some inconsistencies with the ordering of the command line argument examples. I've ordered them so that the examples will show: config, config-directory, input-filter, test 2017-05-12 22:22:29 +00:00			`$ ./telegraf --config telegraf.conf --input-filter ping --test`
Fix problem with metrics when ping return Destination net unreachable ( windows ) (#1561) * Fix problem with metrics when ping return Destination net unreachable Add test case TestUnreachablePingGather Add percent_reply_loss Fix some other tests * Add errors measurment * fir problem with ping reply "TTL expired in transit" ( use regex for more specific condition - TTL in line but it's a not valid replay ) add test case for "TTL expired in transit" - TestTTLExpiredPingGather 2016-08-09 07:27:30 +00:00			`* Plugin: ping, Collection 1`
Perform DNS lookup before ping (#3385) 2017-10-26 20:35:37 +00:00			`ping,host=WIN-PBAPLP511R7,url=www.google.com result_code=0i,average_response_ms=7i,maximum_response_ms=9i,minimum_response_ms=7i,packets_received=4i,packets_transmitted=4i,percent_packet_loss=0,percent_reply_loss=0,reply_received=4i 1469879119000000000`
ping: fix typo in README (#2163) 2016-12-14 19:47:48 +00:00			```