---
title: Telegraf Documentation
description: Telegraf plugin for collecting metrics from Ping
url: https://docs.influxdata.com/telegraf/v1/input-plugins/ping/
estimated_tokens: 3413
product: Telegraf
version: v1
---

-   Telegraf v0.1.8+

# Ping Input Plugin

This plugin collects metrics on ICMP ping packets including the round-trip time, response times and other packet statistics.

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

Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.

## Configuration

```toml
# 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. Operates like the "-i" option
  ## of the ping command.
  # ping_interval = "1s"

  ## If set, the time to wait for a ping response.  Operates like the "-W"
  ## option of the ping command (for "exec" method only)
  # timeout = "1s"

  ## If set, the total ping deadline. Operates like the "-w" option of the ping
  ## command.  Use this option to control timeout behavior when using the
  ## "native" method.
  # deadline = "10s"

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

  ## Size of the packets to send. Corresponds to the "-s" option of the ping
  ## command. This only works with the native method.
  # size = "56B"
```

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

With `method = "native"`, the `timeout` option is ignored. Use `deadline` to control the total runtime instead.

### 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`](http://man7.org/linux/man-pages/man7/capabilities.7.html) for more information about setting capabilities.

### 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](https://github.com/golang/go/issues/7175) and [https://github.com/golang/go/issues/7174](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
```

#### Related

-   [Configure plugins](/telegraf/v1/configure_plugins/)
-   [Ping Plugin Source](https://github.com/influxdata/telegraf/tree/v1.38.4/plugins/inputs/ping/README.md)