PingProber

A lightweight, production-ready ICMP latency exporter for Prometheus.

English · 简体中文

PingProber probes configured IPv4 and IPv6 addresses at fixed intervals and exports the latest successful round-trip latency through a Prometheus /metrics endpoint. It is designed for simple, predictable deployment on Linux hosts.

Features

• IPv4 and IPv6 ICMP Echo probing
• One shared raw ICMP socket per address family
• Static labels for both the logical source and each target
• Staggered scheduling within the interval - timeout window
• No concurrent probes to the same target
• One focused application metric: pingprober_latency_ms
• Strict configuration validation, health checks, and graceful shutdown

Install

The installer supports Linux systems with systemd on amd64 and arm64. It requires root privileges, curl, and sha256sum.

Install the latest stable release:

curl -fsSL https://raw.githubusercontent.com/OVINC-CN/PingProber/main/support-files/install.sh | sudo bash

Install a specific stable or prerelease version:

curl -fsSL https://raw.githubusercontent.com/OVINC-CN/PingProber/main/support-files/install.sh | sudo bash -s -- v1.2.3

The installer:

• downloads the matching GitHub Release and verifies its SHA-256 checksum;
• installs the binary at /usr/local/bin/pingprober;
• creates /etc/pingprober/config.yaml on first install;
• preserves and validates the existing configuration during upgrades;
• installs, enables, and starts pingprober.service.

Check the service after installation:

sudo systemctl status pingprober
sudo journalctl -u pingprober -f

Configuration

Edit /etc/pingprober/config.yaml when installed with the script, or copy config.example.yaml for a source build:

server:
  listen: ":9115"

source:
  name: "prober-shanghai-a"
  tags:
    dc: "shanghai-a"
    region: "cn-east"

probe:
  interval: 10s
  timeout: 3s

targets:
  - address: "10.0.0.1"
    tags:
      dc: "beijing-a"
      env: "prod"

  - address: "2001:db8::10"
    tags:
      dc: "singapore-a"
      env: "prod"

Field	Required	Default	Description
server.listen	No	:9115	HTTP listen address; the port must be between 1 and 65535
source.name	Yes	—	Logical UTF-8 source identifier, up to 128 bytes with no control characters
source.tags	No	{}	Static source tags, with up to 16 keys
probe.interval	Yes	—	Interval between probe starts for each target; initial probes are evenly staggered within interval - timeout
probe.timeout	No	3s	Timeout for one probe; it must be shorter than interval
targets[].address	Yes	—	IPv4 or IPv6 unicast address; hostnames are unsupported, and IPv6 link-local addresses require a %interface zone
targets[].tags	No	{}	Static target tags, with up to 16 distinct keys across all targets

A configuration can contain up to 1,000 unique targets, and each tag value can contain up to 256 bytes. Unknown YAML fields, duplicate addresses, multicast or unspecified addresses, invalid tag keys, and multiple YAML documents cause validation to fail.

source is a logical identifier and does not bind ICMP traffic to a local IP. The operating system routing table selects the actual outbound address.

Validate changes before restarting the service:

sudo /usr/local/bin/pingprober --config /etc/pingprober/config.yaml --check-config
sudo systemctl restart pingprober

Endpoints

PingProber listens on :9115 by default:

Endpoint	Purpose
GET /metrics	Prometheus metrics
GET /healthz	Process health check
GET /readyz	Readiness check

Prometheus

PingProber uses an isolated registry and exposes one application metric:

# HELP pingprober_latency_ms Latest successful ICMP round-trip latency in milliseconds.
# TYPE pingprober_latency_ms gauge
pingprober_latency_ms{ip_version="4",source="prober-shanghai-a",source_dc="shanghai-a",source_region="cn-east",target="10.0.0.1",target_dc="beijing-a",target_env="prod"} 12.346

• Values are measured in milliseconds and rounded to 0.001 ms.
• Source tags become source_<key> labels; target tags become target_<key> labels.
• A target series appears only after its first successful probe.
• A timeout or send failure deletes the series; a later success recreates it.

Example scrape configuration:

scrape_configs:
  - job_name: pingprober
    scrape_interval: 10s
    static_configs:
      - targets: ["pingprober:9115"]

Example query:

pingprober_latency_ms{source_dc="shanghai-a", target_dc="beijing-a"}

Check whether a known target has no latency data while the exporter is reachable:

absent(pingprober_latency_ms{target="10.0.0.1"})
and on() (up{job="pingprober"} == 1)

Build from source

Requirements: Go 1.26, Linux, and permission to use raw ICMP sockets.

GOTOOLCHAIN=local go build -o bin/pingprober ./cmd/pingprober
cp config.example.yaml config.yaml
./bin/pingprober --config ./config.yaml --check-config
sudo setcap cap_net_raw=+ep ./bin/pingprober
./bin/pingprober --config ./config.yaml

Manual systemd deployment

Create /etc/systemd/system/pingprober.service:

[Unit]
Description=PingProber ICMP latency exporter
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/pingprober --config /etc/pingprober/config.yaml
Restart=always
RestartSec=5
User=root
Group=root
StandardOutput=journal
StandardError=journal
SyslogIdentifier=node-exporter

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now pingprober

License

PingProber is available under the MIT License.