pinger

README

go-pinger

Go library for perform ICMP ping checks to 1 or more destination addresses.

This "pinger" service is designed to support pinging 1000's of hotss concurrently and is used in the monitoring probes for the worldPing service run by Grafana Labs.

Getting started

• API documentation is available via godoc.
• A demo cli tool is available at ping-all

Documentation

Overview

Package pinger provides a service for sending ICMP echo requests to numerous hosts in parallel. The results from each "Ping" issued can used to calculate min,max,avg and stdev latency and % loss.

A process should only create 1 pinger service which can be shared across multiple goroutines.

see github.com/raintank/go-pinger/ping-all for an example of how to use the service.

Index

• Constants
• type EchoRequest
  • func NewEchoRequest(msg icmp.Message, dest net.IP, wg *sync.WaitGroup) *EchoRequest
• type EchoResponse
  • func (e *EchoResponse) String() string
• type PingStats
• type Pinger
  • func NewPinger(protocol string, bufferSize int) (*Pinger, error)
  • func (p *Pinger) Ping(address net.IP, count int, timeout time.Duration) (*PingStats, error)
  • func (p *Pinger) Send(req *EchoRequest) error
  • func (p *Pinger) Start()
  • func (p *Pinger) Stop()

Constants

const ProtocolICMP = 1 // Internet Control Message

const ProtocolIPv6ICMP = 58 // ICMP for IPv6

from "golang.org/x/net/internal/iana"

Types

type EchoRequest

type EchoRequest struct {
	icmp.Message

	Destination net.IP
	Sent        time.Time
	Received    time.Time
	ID          string
	WaitGroup   *sync.WaitGroup
}

An EchoRequest is a single ICMP echo request packet that will be sent. When the echoResponse is recieved, the "Received" field will be set and the Done() will be called on the WaitGroup.

func NewEchoRequest

func NewEchoRequest(msg icmp.Message, dest net.IP, wg *sync.WaitGroup) *EchoRequest

create a new EchoRequest instance.

type EchoResponse

type EchoResponse struct {
	Peer     string
	Id       int
	Seq      int
	Received time.Time
}

func (*EchoResponse) String

func (e *EchoResponse) String() string

type PingStats

type PingStats struct {
	Latency  []time.Duration
	Sent     int
	Received int
}

PingStats are the results from sending ICMP echo requests to a host. The stats include the number of packets sent and received and the latency for every packet received.

type Pinger

type Pinger struct {
	Counter int

	Debug bool

	sync.RWMutex
	// contains filtered or unexported fields
}

Pinger represents a service that can be used for sending IMCP pings to hosts.

func NewPinger

func NewPinger(protocol string, bufferSize int) (*Pinger, error)

Creates a new Pinger service. Accepts the IP protocol to use "ipv4", "ipv6" or "all" and the number of packets to buffer in the request and response packet channels. The pinger instance will immediately start listening on the raw sockets (ipv4:icmp, ipv6:ipv6-icmp or both).

func (*Pinger) Ping

func (p *Pinger) Ping(address net.IP, count int, timeout time.Duration) (*PingStats, error)

Send <count> icmp echo rquests to <address> and don't wait longer then <timeout> for a response. An error will be returned if the EchoRequests cant be sent. This call will block until all icmp EchoResponses are received or timeout is reached. It is safe to call this method concurrently.

func (*Pinger) Send

func (p *Pinger) Send(req *EchoRequest) error

func (*Pinger) Start

func (p *Pinger) Start()

Start launches goroutines for processing packets received on the raw sockets

func (*Pinger) Stop

func (p *Pinger) Stop()

Stop shuts down the pinger service and closes the raw sockets. This method will block until all spawned goroutines have ended.