go-ping-exporter

A lightweight Go-based ICMP ping exporter that provides Prometheus-compatible metrics for network monitoring. This tool continuously pings IPv4 and IPv6 targets and exposes metrics about response times and availability status.

Features

• Dual-stack support: Monitor both IPv4 and IPv6 targets
• Prometheus metrics: Exposes metrics in Prometheus format
• Statistical tracking: Maintains last, average, minimum, and maximum response times
• Configurable ping parameters: Customizable ping interval, timeout, packet size
• History tracking: Keeps configurable history of recent ping results
• HTTP server: Built-in web server for metrics endpoint
• Health check: Includes /healthz endpoint for service monitoring

Quick Start

Prerequisites

• Go 1.25 or later
• Network permissions for ICMP (typically requires root/administrator privileges)

Installation

git clone https://gitlab.pathandfilter.com/scratch/go-ping-exporter.git
cd go-ping-exporter
go build -o ping-exporter .

Configuration

Edit ping_exporter.json to configure your targets and settings:

{
    "General": {
        "ListenAddr": "127.0.0.1",
        "ListenPort": 8085,
        "History": 5,
        "PingInterval": 6,
        "Debug": false,
        "MaxTimeout": 1,
        "PingSize": 10,
        "DoNotFragment": true
    },
    "Targets": {
        "Targets4": [
            "10.0.1.1",
            "1.1.1.1",
            "google.com"
        ],
        "Targets6": [
            "google.com",
            "fdfb:b280:2849:a28c:200b:a264:768a:9db2"
        ]
    }
}

Running

# Run with default settings
sudo ./ping-exporter

# Run with custom options
sudo ./ping-exporter -listen 0.0.0.0 -port 9090 -Debug

Configuration Options

General Settings

Parameter	Type	Default	Description
ListenAddr	string	"127.0.0.1"	HTTP server bind address
ListenPort	int	8085	HTTP server port
History	int	10	Number of recent ping results to keep
PingInterval	duration	30s	Time between ping rounds
Debug	bool	false	Enable debug logging
MaxTimeout	duration	2s	Maximum timeout for ping responses
PingSize	int	50	ICMP packet size (minimum 10 bytes)
DoNotFragment	bool	false	Set DF flag on packets

Target Configuration

• Targets4: Array of IPv4 targets (IP addresses or hostnames)
• Targets6: Array of IPv6 targets (IP addresses or hostnames)

Metrics

The exporter provides the following Prometheus metrics at /metrics:

• icmp_status{target="...", protocol="..."}: Current availability status (1=up, 0=down)
• icmp_resp_last{target="...", protocol="..."}: Last response time in milliseconds
• icmp_resp_avg{target="...", protocol="..."}: Average response time in milliseconds
• icmp_resp_min{target="...", protocol="..."}: Minimum response time in milliseconds
• icmp_resp_max{target="...", protocol="..."}: Maximum response time in milliseconds

Endpoints

• /metrics: Prometheus metrics endpoint
• /healthz: Health check endpoint
• /: Returns 404 (all other endpoints)

Command Line Options

./ping-exporter -h

• -listen: HTTP listen address (default: "127.0.0.1")
• -port: HTTP port (default: 8080)
• -Debug: Enable debug mode (default: false)

Usage with Prometheus

Add the following to your prometheus.yml:

scrape_configs:
  - job_name: 'ping-exporter'
    static_configs:
      - targets: ['localhost:8085']
    scrape_interval: 30s

Usage with Grafana Alloy

Grafana Alloy can scrape metrics from the ping exporter using the prometheus.scrape component. Add the following to your Alloy configuration:

prometheus.scrape "ping_exporter" {
  targets = [{"__address__" = "localhost:8085"}]
  job_name = "ping-exporter"
  scrape_interval = "30s"
}

// Optional: Write metrics to Prometheus remote write
prometheus.remote_write "default" {
  endpoints {
    url = "http://prometheus:9090/api/v1/write"
  }
}

// Forward scraped metrics to remote write
prometheus.scrape.ping_exporter.forward_to = [prometheus.remote_write.default.receiver]

Complete Alloy Example

Here's a complete example for monitoring multiple ping exporters:

// Configure logging
logging {
  level  = "info"
  format = "logfmt"
}

// Scrape ping exporters
prometheus.scrape "ping_exporters" {
  targets = [
    {"__address__" = "ping-exporter-1:8085"},
    {"__address__" = "ping-exporter-2:8085"},
  ]
  job_name = "ping-exporter"
  scrape_interval = "30s"
  scrape_timeout = "10s"
  metrics_path = "/metrics"
}

// Send metrics to Grafana Mimir/Prometheus
prometheus.remote_write "grafana_cloud" {
  endpoints {
    url = "https://prometheus-prod-01-prod-us-central-0.grafana.net/api/prom/push"
    basic_auth {
      username = "your-username"
      password = "your-api-key"
    }
  }
}

// Route metrics
prometheus.scrape.ping_exporters.forward_to = [prometheus.remote_write.grafana_cloud.receiver]

Docker Compose with Alloy

Example docker-compose.yml file to run ping exporter with Grafana Alloy:

version: '3.8'

services:
  ping-exporter:
    build: .
    ports:
      - "8085:8085"
    privileged: true  # Required for ICMP
    volumes:
      - ./ping_exporter.json:/app/ping_exporter.json

  alloy:
    image: grafana/alloy:latest
    ports:
      - "12345:12345"
    volumes:
      - ./config.alloy:/etc/alloy/config.alloy
    command: run /etc/alloy/config.alloy
    depends_on:
      - ping-exporter

Development

Building

go build -o ping-exporter .

Testing

go test -v ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Troubleshooting

Permission Issues

ICMP operations typically require elevated privileges:

# Linux/macOS
sudo ./ping-exporter

# Or set capabilities (Linux)
sudo setcap cap_net_raw+ep ./ping-exporter

Common Issues

• "Address already in use": Change the port in configuration or command line
• "Permission denied": Run with appropriate privileges for ICMP
• High latency: Check network connectivity and firewall settings

Architecture

The application consists of several components:

• main.go: Entry point and HTTP server setup
• ping.go: ICMP ping implementation for IPv4/IPv6
• monitor.go: Continuous monitoring and statistics calculation
• config.go: Configuration management and validation
• web.go: HTTP handlers for metrics and health endpoints
• templates/metrics.tmpl: Prometheus metrics template