| 1 | plugin_name: go.d.plugin |
| 2 | modules: |
| 3 | - meta: |
| 4 | id: collector-go.d.plugin-ping |
| 5 | plugin_name: go.d.plugin |
| 6 | module_name: ping |
| 7 | monitored_instance: |
| 8 | name: Ping |
| 9 | link: "" |
| 10 | icon_filename: globe.svg |
| 11 | categories: |
| 12 | - data-collection.synthetic-testing |
| 13 | keywords: |
| 14 | - ping |
| 15 | related_resources: |
| 16 | integrations: |
| 17 | list: [] |
| 18 | info_provided_to_referring_integrations: |
| 19 | description: "" |
| 20 | overview: |
| 21 | data_collection: |
| 22 | metrics_description: | |
| 23 | This module measures round-trip time and packet loss by sending ping messages to network hosts. |
| 24 | |
| 25 | There are two operational modes: |
| 26 | |
| 27 | - **Privileged** (send raw ICMP ping, default). Requires the necessary permissions ([CAP_NET_RAW](https://man7.org/linux/man-pages/man7/capabilities.7.html) on Linux, `setuid` bit on other systems). |
| 28 | |
| 29 | These permissions are **automatically** set during Netdata installation. However, if you need to set them manually: |
| 30 | - set `CAP_NET_RAW` (Linux only). |
| 31 | ```bash |
| 32 | sudo setcap CAP_NET_RAW=eip <INSTALL_PREFIX>/usr/libexec/netdata/plugins.d/go.d.plugin |
| 33 | ``` |
| 34 | - set `setuid` bit (Other OS). |
| 35 | ```bash |
| 36 | sudo chmod 4750 <INSTALL_PREFIX>/usr/libexec/netdata/plugins.d/go.d.plugin |
| 37 | ``` |
| 38 | |
| 39 | - **Unprivileged** (send UDP ping, Linux only). Requires configuring [ping_group_range](https://www.man7.org/linux/man-pages/man7/icmp.7.html): |
| 40 | |
| 41 | This configuration is **not set automatically** and requires manual configuration. |
| 42 | |
| 43 | ```bash |
| 44 | sudo sysctl -w net.ipv4.ping_group_range="0 2147483647" |
| 45 | ``` |
| 46 | |
| 47 | To persist the change add `net.ipv4.ping_group_range=0 2147483647` to `/etc/sysctl.conf` and execute `sudo sysctl -p`. |
| 48 | method_description: "" |
| 49 | supported_platforms: |
| 50 | include: [] |
| 51 | exclude: [] |
| 52 | multi_instance: true |
| 53 | additional_permissions: |
| 54 | description: "" |
| 55 | default_behavior: |
| 56 | auto_detection: |
| 57 | description: "" |
| 58 | limits: |
| 59 | description: "" |
| 60 | performance_impact: |
| 61 | description: "" |
| 62 | setup: |
| 63 | prerequisites: |
| 64 | list: [] |
| 65 | configuration: |
| 66 | file: |
| 67 | name: go.d/ping.conf |
| 68 | options: |
| 69 | description: | |
| 70 | The following options can be defined globally: update_every, autodetection_retry. |
| 71 | folding: |
| 72 | title: Config options |
| 73 | enabled: true |
| 74 | list: |
| 75 | - name: update_every |
| 76 | description: Data collection interval (seconds). |
| 77 | default_value: 5 |
| 78 | required: false |
| 79 | group: Collection |
| 80 | - name: autodetection_retry |
| 81 | description: Autodetection retry interval (seconds). Set 0 to disable. |
| 82 | default_value: 0 |
| 83 | required: false |
| 84 | group: Collection |
| 85 | |
| 86 | - name: hosts |
| 87 | description: List of hosts to ping. |
| 88 | default_value: "[]" |
| 89 | required: true |
| 90 | group: Target |
| 91 | |
| 92 | - name: network |
| 93 | description: "DNS resolution mode. Options: `ip` (IPv4 or IPv6), `ip4` (IPv4 only), `ip6` (IPv6 only)." |
| 94 | default_value: ip |
| 95 | required: false |
| 96 | group: Ping Settings |
| 97 | - name: interface |
| 98 | description: "Network interface to use for ICMP echo requests (e.g., `eth0`, `wlan0`)." |
| 99 | default_value: "" |
| 100 | required: false |
| 101 | group: Ping Settings |
| 102 | - name: privileged |
| 103 | description: "Ping packet type. `yes` = raw ICMP ping, `no` = unprivileged UDP ping." |
| 104 | default_value: yes |
| 105 | required: true |
| 106 | group: Ping Settings |
| 107 | - name: packets |
| 108 | description: Number of ping packets to send per iteration. |
| 109 | default_value: 5 |
| 110 | required: false |
| 111 | group: Ping Settings |
| 112 | - name: interval |
| 113 | description: Interval between sending ping packets. |
| 114 | default_value: 100ms |
| 115 | required: false |
| 116 | group: Ping Settings |
| 117 | |
| 118 | - name: jitter_ewma_samples |
| 119 | description: EWMA smoothing factor for jitter calculation. Higher values = smoother, slower response. |
| 120 | default_value: 16 |
| 121 | required: false |
| 122 | group: Jitter Settings |
| 123 | - name: jitter_sma_window |
| 124 | description: Number of iterations for SMA jitter calculation. |
| 125 | default_value: 10 |
| 126 | required: false |
| 127 | group: Jitter Settings |
| 128 | |
| 129 | - name: vnode |
| 130 | description: Associates this data collection job with a [Virtual Node](https://learn.netdata.cloud/docs/netdata-agent/configuration/organize-systems-metrics-and-alerts#virtual-nodes). |
| 131 | default_value: "" |
| 132 | required: false |
| 133 | group: Virtual Node |
| 134 | examples: |
| 135 | folding: |
| 136 | title: Config |
| 137 | enabled: true |
| 138 | list: |
| 139 | - name: IPv4 hosts |
| 140 | description: An example configuration. |
| 141 | config: | |
| 142 | jobs: |
| 143 | - name: example |
| 144 | hosts: |
| 145 | - 192.0.2.0 |
| 146 | - 192.0.2.1 |
| 147 | - name: Unprivileged mode |
| 148 | description: An example configuration. |
| 149 | config: | |
| 150 | jobs: |
| 151 | - name: example |
| 152 | privileged: no |
| 153 | hosts: |
| 154 | - 192.0.2.0 |
| 155 | - 192.0.2.1 |
| 156 | - name: Multi-instance |
| 157 | description: | |
| 158 | > **Note**: When you define multiple jobs, their names must be unique. |
| 159 | |
| 160 | Multiple instances. |
| 161 | config: | |
| 162 | jobs: |
| 163 | - name: example1 |
| 164 | hosts: |
| 165 | - 192.0.2.0 |
| 166 | - 192.0.2.1 |
| 167 | |
| 168 | - name: example2 |
| 169 | packets: 10 |
| 170 | hosts: |
| 171 | - 192.0.2.3 |
| 172 | - 192.0.2.4 |
| 173 | troubleshooting: |
| 174 | problems: |
| 175 | list: [] |
| 176 | alerts: |
| 177 | - name: ping_host_reachable |
| 178 | metric: ping.host_packet_loss |
| 179 | info: "network host ${label:host} reachability status" |
| 180 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/ping.conf |
| 181 | - name: ping_packet_loss |
| 182 | metric: ping.host_packet_loss |
| 183 | info: "packet loss percentage to the network host ${label:host} over the last 10 minutes" |
| 184 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/ping.conf |
| 185 | - name: ping_host_latency |
| 186 | metric: ping.host_rtt |
| 187 | info: "average latency to the network host ${label:host} over the last 10 seconds" |
| 188 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/ping.conf |
| 189 | metrics: |
| 190 | folding: |
| 191 | title: Metrics |
| 192 | enabled: false |
| 193 | description: "" |
| 194 | availability: [] |
| 195 | scopes: |
| 196 | - name: host |
| 197 | description: These metrics refer to the remote host. |
| 198 | labels: |
| 199 | - name: host |
| 200 | description: remote host |
| 201 | metrics: |
| 202 | - name: ping.host_rtt |
| 203 | description: Ping round-trip time |
| 204 | unit: milliseconds |
| 205 | chart_type: area |
| 206 | dimensions: |
| 207 | - name: min |
| 208 | - name: max |
| 209 | - name: avg |
| 210 | - name: ping.host_std_dev_rtt |
| 211 | description: Ping round-trip time standard deviation |
| 212 | unit: milliseconds |
| 213 | chart_type: line |
| 214 | dimensions: |
| 215 | - name: std_dev |
| 216 | - name: ping.host_jitter |
| 217 | description: Ping latency jitter |
| 218 | unit: milliseconds |
| 219 | chart_type: line |
| 220 | dimensions: |
| 221 | - name: mean |
| 222 | - name: ewma |
| 223 | - name: sma |
| 224 | - name: ping.host_rtt_variance |
| 225 | description: Ping round-trip time variance |
| 226 | unit: ms² |
| 227 | chart_type: line |
| 228 | dimensions: |
| 229 | - name: variance |
| 230 | - name: ping.host_packet_loss |
| 231 | description: Ping packet loss |
| 232 | unit: percentage |
| 233 | chart_type: line |
| 234 | dimensions: |
| 235 | - name: loss |
| 236 | - name: ping.host_packets |
| 237 | description: Ping packets transferred |
| 238 | unit: packets |
| 239 | chart_type: line |
| 240 | dimensions: |
| 241 | - name: received |
| 242 | - name: sent |