# 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.

⭐ Telegraf v0.1.8
🏷️ network
💻 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][CONFIGURATION.md] 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`][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
```
