Skip to main content

​
Description

The ping probe checks host reachability using ICMP echo (unprivileged datagram socket). If ICMP is unavailable (missing CAP_NET_RAW or net.ipv4.ping_group_range doesn’t cover the agent’s user), it automatically falls back to TCP connect.

​
Config fields

FieldTypeRequiredDefaultDescription
typestringYes—Must be "ping"
hoststringYes—Host or IP to ping
countintNo3Number of pings (1–10). Values > 10 are clamped
methodstringNo"" (auto)"icmp": ICMP only. "tcp_fallback": TCP only. Empty: try ICMP first, fall back to TCP
fallbackPortintNo443TCP port for fallback (1–65535)

​
Metrics

MetricTypeUnitLabelsDescription
vms.ping.statusstatus—methodup or down
vms.ping.latency_msgaugemsmethodAverage latency
vms.agent.permission_missinggauge—capability=CAP_NET_RAWEmitted when ICMP is blocked and probe uses TCP fallback

​
Example config

{
  "type": "ping",
  "host": "10.0.0.10",
  "count": 3,
  "fallbackPort": 443
}

​
Notes

  • ICMP unavailability is detected once at construction, not re-probed every run.
  • When ICMP is blocked, the probe emits vms.agent.permission_missing{capability=CAP_NET_RAW} every run so the gap is visible on dashboards.
  • To enable native ICMP on Linux: grant CAP_NET_RAW to the binary or expand net.ipv4.ping_group_range.