223 lines
6.7 KiB
Markdown
223 lines
6.7 KiB
Markdown
---
|
|
description: "Telegraf plugin for collecting metrics from Ping"
|
|
menu:
|
|
telegraf_v1_ref:
|
|
parent: input_plugins_reference
|
|
name: Ping
|
|
identifier: input-ping
|
|
tags: [Ping, "input-plugins", "configuration", "network"]
|
|
introduced: "v0.1.8"
|
|
os_support: "freebsd, linux, macos, solaris, windows"
|
|
related:
|
|
- /telegraf/v1/configure_plugins/
|
|
- https://github.com/influxdata/telegraf/tree/v1.36.1/plugins/inputs/ping/README.md, Ping Plugin Source
|
|
---
|
|
|
|
# Ping Input Plugin
|
|
|
|
This plugin collects metrics on ICMP ping packets including the round-trip time,
|
|
response times and other packet statistics.
|
|
|
|
> [!NOTE]
|
|
> When using the `exec` method the `ping` command must be available on the
|
|
> systems and executable by Telegraf.
|
|
|
|
**Introduced in:** Telegraf v0.1.8
|
|
**Tags:** network
|
|
**OS support:** all
|
|
|
|
## Global configuration options <!-- @/docs/includes/plugin_config.md -->
|
|
|
|
In addition to the plugin-specific configuration settings, plugins support
|
|
additional global and plugin configuration settings. These settings are used to
|
|
modify metrics, tags, and field or create aliases and configure ordering, etc.
|
|
See the [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.
|
|
|
|
[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins
|
|
|
|
## Configuration
|
|
|
|
```toml @sample.conf
|
|
# Ping given url(s) and return statistics
|
|
[[inputs.ping]]
|
|
## Hosts to send ping packets to.
|
|
urls = ["example.org"]
|
|
|
|
## Method used for sending pings, can be either "exec" or "native". When set
|
|
## to "exec" the systems ping command will be executed. When set to "native"
|
|
## the plugin will send pings directly.
|
|
##
|
|
## While the default is "exec" for backwards compatibility, new deployments
|
|
## are encouraged to use the "native" method for improved compatibility and
|
|
## performance.
|
|
# method = "exec"
|
|
|
|
## Number of ping packets to send per interval. Corresponds to the "-c"
|
|
## option of the ping command.
|
|
# count = 1
|
|
|
|
## Time to wait between sending ping packets in seconds. Operates like the
|
|
## "-i" option of the ping command.
|
|
# ping_interval = 1.0
|
|
|
|
## If set, the time to wait for a ping response in seconds. Operates like
|
|
## the "-W" option of the ping command.
|
|
# timeout = 1.0
|
|
|
|
## If set, the total ping deadline, in seconds. Operates like the -w option
|
|
## of the ping command.
|
|
# deadline = 10
|
|
|
|
## Interface or source address to send ping from. Operates like the -I or -S
|
|
## option of the ping command.
|
|
# interface = ""
|
|
|
|
## Percentiles to calculate. This only works with the native method.
|
|
# percentiles = [50, 95, 99]
|
|
|
|
## Specify the ping executable binary.
|
|
# binary = "ping"
|
|
|
|
## Arguments for ping command. When arguments is not empty, the command from
|
|
## the binary option will be used and other options (ping_interval, timeout,
|
|
## etc) will be ignored.
|
|
# arguments = ["-c", "3"]
|
|
|
|
## Use only IPv4 addresses when resolving a hostname. By default, both IPv4
|
|
## and IPv6 can be used.
|
|
# ipv4 = false
|
|
|
|
## Use only IPv6 addresses when resolving a hostname. By default, both IPv4
|
|
## and IPv6 can be used.
|
|
# ipv6 = false
|
|
|
|
## Number of data bytes to be sent. Corresponds to the "-s"
|
|
## option of the ping command. This only works with the native method.
|
|
# size = 56
|
|
```
|
|
|
|
### Ping methods
|
|
|
|
This plugin has two main methods of operation, the `exec` and `native` mode.
|
|
The latter is the recommended method as it provides better system compatibility
|
|
and performance. However, for backwards compatibility the `exec` method is the
|
|
default.
|
|
|
|
When using the `exec` method, most ping command implementations are supported,
|
|
one notable exception being the GNU `inetutils` ping. You may instead use the
|
|
iputils-ping implementation:
|
|
|
|
```sh
|
|
apt-get install iputils-ping
|
|
```
|
|
|
|
For the `native` method a corresponding ICMP packet is sent and the results are
|
|
reported in native Go by the Telegraf process, eliminating the need to execute
|
|
the system `ping` command. Therefore, this method doesn't have external
|
|
dependencies.
|
|
|
|
### File Limit
|
|
|
|
Since this plugin runs the ping command, it may need to open multiple files per
|
|
host. The number of files used is lessened with the `native` option but still
|
|
many files are used. With a large host list you may receive a `too many open
|
|
files` error.
|
|
|
|
To increase this limit on platforms using systemd the recommended method is to
|
|
use the "drop-in directory", usually located at
|
|
`/etc/systemd/system/telegraf.service.d`.
|
|
|
|
You can create or edit a drop-in file in the correct location using:
|
|
|
|
```sh
|
|
systemctl edit telegraf
|
|
```
|
|
|
|
Increase the number of open files:
|
|
|
|
```ini
|
|
[Service]
|
|
LimitNOFILE=8192
|
|
```
|
|
|
|
Restart Telegraf:
|
|
|
|
```sh
|
|
systemctl restart telegraf
|
|
```
|
|
|
|
### Linux Permissions
|
|
|
|
When using the `native` method, Telegraf will attempt to use privileged raw ICMP
|
|
sockets. On most systems, doing so requires `CAP_NET_RAW` capabilities or for
|
|
Telegraf to be run as root.
|
|
|
|
With systemd:
|
|
|
|
```sh
|
|
systemctl edit telegraf
|
|
```
|
|
|
|
```ini
|
|
[Service]
|
|
CapabilityBoundingSet=CAP_NET_RAW
|
|
AmbientCapabilities=CAP_NET_RAW
|
|
```
|
|
|
|
```sh
|
|
systemctl restart telegraf
|
|
```
|
|
|
|
Without systemd:
|
|
|
|
```sh
|
|
setcap cap_net_raw=eip /usr/bin/telegraf
|
|
```
|
|
|
|
Reference [`man 7 capabilities`]() for more information about
|
|
setting capabilities.
|
|
|
|
[man 7 capabilities]: http://man7.org/linux/man-pages/man7/capabilities.7.html
|
|
|
|
### Other OS Permissions
|
|
|
|
When using `method = "native"`, you will need permissions similar to the
|
|
executable ping program for your OS.
|
|
|
|
## Metrics
|
|
|
|
- ping
|
|
- tags:
|
|
- url
|
|
- fields:
|
|
- packets_transmitted (integer)
|
|
- packets_received (integer)
|
|
- percent_packet_loss (float)
|
|
- ttl (integer, Not available on Windows)
|
|
- average_response_ms (float)
|
|
- minimum_response_ms (float)
|
|
- maximum_response_ms (float)
|
|
- standard_deviation_ms (float, Available on Windows only with method = "native")
|
|
- percentile\<N\>_ms (float, Where `<N>` is the percentile specified in `percentiles`. Available with method = "native" only)
|
|
- errors (float, Windows only)
|
|
- reply_received (integer, Windows with method = "exec" only)
|
|
- percent_reply_loss (float, Windows with method = "exec" only)
|
|
- result_code (int, success = 0, no such host = 1, ping error = 2)
|
|
|
|
### reply_received vs packets_received
|
|
|
|
On Windows systems with `method = "exec"`, the "Destination net unreachable"
|
|
reply will increment `packets_received` but not `reply_received`*.
|
|
|
|
### ttl
|
|
|
|
There is currently no support for TTL on windows with `"native"`; track
|
|
progress at <https://github.com/golang/go/issues/7175> and
|
|
<https://github.com/golang/go/issues/7174>
|
|
|
|
## Example Output
|
|
|
|
```text
|
|
ping,url=example.org average_response_ms=23.066,ttl=63,maximum_response_ms=24.64,minimum_response_ms=22.451,packets_received=5i,packets_transmitted=5i,percent_packet_loss=0,result_code=0i,standard_deviation_ms=0.809 1535747258000000000
|
|
```
|