ping

README

ping

A simple ping library that aims to make the retrieval of ping-statistics easy and manageable. This project is a fork of go-ping, with the following major changes:

• Unprivileged (UDP) pinging has been removed.
• Almost all fields have been renamed.
• Statistics are calculated on the fly, and no history of round-trip times is stored.
• Main initialisation is not done in the NewPinger function, but when Run is called.
• The given Size is respected: when the timestamp cannot be stored in the packet, it is kept in the Pinger. The data is also not encoded as JSON.

Also see the documentation

Installation

Download & install using:

go get git.slxh.eu/prometheus/ping/...

Usage

An full implementation matching the Unix ping command is included in cmd/ping.

The following example sends three packets to Google:

pinger, err := ping.NewPinger("www.google.com")
if err != nil {
        panic(err)
}
pinger.PacketLimit = 3
err = pinger.Run()
if err != nil {
	panic(err)
}
stats := pinger.Statistics

If the destination address is already available, the Pinger can also be initialised directly:

pinger := &ping.Pinger{
    IPAddr:    ipAddr, // some *net.IPAddr
    Host:      ipAddr.String(),
    Size:      ping.DefaultSize,
}

Note

On Linux, any binary using this code requires the cap_net_raw capability, this can be set on a binary with the following command:

setcap cap_net_raw=+ep $GOPATH/bin/ping

See the documentation for golang.org/x/net/icmp for more details.

Documentation

Overview

Package ping is an ICMP ping library seeking to emulate the unix "ping" command.

Here is a very simple example that sends and receives 3 packets:

pinger, err := ping.NewPinger("www.google.com")
if err != nil {
	panic(err)
}

pinger.PacketLimit = 3
pinger.Run() // blocks until finished
stats := pinger.Statistics // get send/receive/rtt stats

For a full ping example, see "cmd/ping/ping.go".

Index

• Constants
• type Packet
• type Pinger
  • func NewPinger(host string) (*Pinger, error)
  • func (p *Pinger) Run() (err error)
  • func (p *Pinger) SetHost(host string) error
  • func (p *Pinger) SetSource(host string) error
  • func (p *Pinger) Stop()
• type Statistics
  • func NewStatistics(addr string, ipAddr *net.IPAddr) *Statistics
  • func (s *Statistics) Add(rtt time.Duration)
  • func (s *Statistics) Counters() (recv, sent int)
  • func (s *Statistics) Durations() (min, mean, max time.Duration)
  • func (s *Statistics) IncSent()
  • func (s *Statistics) PacketLoss() float64
  • func (s *Statistics) StandardDeviation() time.Duration
  • func (s *Statistics) Variance() time.Duration

Constants

const (
	DefaultSize      = 8
	DefaultInterval  = 1 * time.Second
	DefaultTimeLimit = 100000 * time.Second
)

Default values for the Pinger

Types

type Packet

type Packet struct {
	// RTT is the round-trip time it took to ping.
	RTT time.Duration

	// IPAddr is the address of the host being pinged.
	IPAddr *net.IPAddr

	// Host is the string address of the host being pinged.
	Host string

	// Source is the source address the ping was sent from.
	Source string

	// NBytes is the number of bytes in the message.
	Size int

	// Seq is the ICMP sequence number.
	Seq int
}

Packet represents a received and processed ICMP echo packet.

type Pinger

type Pinger struct {
	// Interval is the wait time between each packet send. Default is 1s.
	Interval time.Duration

	// TimeLimit specifies a timeout before ping exits, regardless of how many
	// packets have been received.
	TimeLimit time.Duration

	// PacketLimit tells pinger to stop after sending (and receiving) PacketLimit echo
	// packets. If this option is not specified, pinger will operate until
	// interrupted.
	PacketLimit int

	// Number of packets sent
	Sent int

	// Number of packets received
	Received int

	// OnReceive is called when Pinger receives and processes a packet
	OnReceive func(*Packet)

	// OnFinish is called when Pinger exits
	OnFinish func(*Statistics)

	// Size of packet being sent
	Size int

	// Resolved IP Address
	IPAddr *net.IPAddr

	// Host to ping
	Host string

	// Resolved source IP Address
	SourceAddr *net.IPAddr

	// Source host
	Source string

	// Statistics returns the statistics of the pinger. This can be run while the
	// pinger is running or after it is finished. OnFinish uses this to get its
	// finished statistics.
	// Access is thread-safe as long as Statistics is set before calling Run().
	Statistics *Statistics
	// contains filtered or unexported fields
}

Pinger represents ICMP packet sender/receiver. It is not entirely thread-safe. Troublesome attributes are marked as such.

func NewPinger

func NewPinger(host string) (*Pinger, error)

NewPinger returns a new Pinger struct pointer with initialized statistics. The source address may be an empty string.

func (*Pinger) Run

func (p *Pinger) Run() (err error)

Run runs the pinger. This is a blocking function that will exit when it's done. If PacketLimit or Interval are not specified, it will run continuously until it is interrupted.

func (*Pinger) SetHost

func (p *Pinger) SetHost(host string) error

SetHost sets the host and the corresponding IP address

func (*Pinger) SetSource

func (p *Pinger) SetSource(host string) error

SetSource sets the source address and corresponding IP address.

func (*Pinger) Stop

func (p *Pinger) Stop()

Stop stops a running Pinger.

type Statistics

type Statistics struct {
	sync.Mutex

	// Received is the number of packets received.
	Received int

	// Sent is the number of packets sent.
	Sent int

	// IPAddr is the address of the host being pinged.
	IPAddr *net.IPAddr

	// Host is the hostname of the host being pinged.
	Host string

	// Source is the source hostname or IP pings are sent from.
	Source string

	// Min is the minimum round-trip time.
	Min time.Duration

	// Max is the maximum round-trip time.
	Max time.Duration

	// Mean is the average round-trip time.
	Mean time.Duration

	// Sum is the of all round-trip times.
	Sum time.Duration
	// contains filtered or unexported fields
}

Statistics represent the stats of a currently running or finished pinger operation. All methods on *Statistics are thread safe, but field access is not.

func NewStatistics

func NewStatistics(addr string, ipAddr *net.IPAddr) *Statistics

NewStatistics returns an initialised Statistics struct pointer

func (*Statistics) Add

func (s *Statistics) Add(rtt time.Duration)

Add updates the statistics with this new value

func (*Statistics) Counters

func (s *Statistics) Counters() (recv, sent int)

Counters returns the counter values of the statistics.

func (*Statistics) Durations

func (s *Statistics) Durations() (min, mean, max time.Duration)

Durations returns the durations values of the statistics.

func (*Statistics) IncSent

func (s *Statistics) IncSent()

Increment the sent count

func (*Statistics) PacketLoss

func (s *Statistics) PacketLoss() float64

PacketLoss returns the packet loss ratio.

func (*Statistics) StandardDeviation

func (s *Statistics) StandardDeviation() time.Duration

StandardDeviation returns the standard deviation of the round-trip times sent via this pinger.

func (*Statistics) Variance

func (s *Statistics) Variance() time.Duration

Variance returns the variance of the round-trip times sent via the pinger.