### Welcome to the UDPing network measurement tool.

The purpose of UDPing is to measure latency and packet loss across a link.  It does this by sending a continuous stream of packets from a source to a destination, measuring latency and loss at the destination, and periodically outputting summary performance metrics.

UDPing has many useful features, including:
* Efficient implementation - typical sampling rates are 100/second
* Randomized Poisson sampling intervals
* Multiple source ports (to exercise multiple ECMP paths)
* Ability to specify multiple next-hop MAC addresses
* Varied payload sizes
* Supports multiple output formats, including statsd and JSON to stdout 
* True one-way protocol - no information is sent from server to client

## Usage

    udping_client -r <remote hostname> -p <remote port> -d <delay> -l <local IP>
      -s <starting port>|<source port descriptor> [-n <number of ports>]
      -i <measurement interval seconds> -m <max packet size> -a <next-hop MAC,...>
      [-v] [-q]
        * Source port descriptor should be a set of ranges separated by commas.
          Each range can either be a port, or a range of ports separated by a
          dash.  For example:
            * 5000 -> port 5000
            * 5000-5009 -> ports 5000,5001,...,5009
            * 5000,5005,5010 -> ports 5000,5005,5010
            * 5000-5001,5005-5006 -> ports 5000,5001,5005,5006
        * If a single port is specified AND a number of ports is specified,
          then source traffic from the number of sequential ports specified
          starting with the starting port

    udping_server -l <listen hostname> -p <port number> -k <keepalive interval seconds>
      [-r <receive hostname>] [-s <statsd host:port>]
      [-t <tag based statsd host:port>] [-m <tag based statsd metric name>]
      [-v] [-q]

## How it works

The UDPing client publishes a stream of UDP packets from a client to a server with a header and a varying length payload, with an average interval specified by the -d switch.  The payload size is randomized from zero to MAX - the size of the header, where MAX is specified by the -m switch on the client.  The packets are sent in groups according to a measurement period, specified by the -i switch.  Packets for a measurement period from a single port share a common GUID.  At the end of the measurement period, a control packet is sent from each port with the total packet count for the period.

As the server receives packets, it timestamps them on arrival and records several counters, including
* Count
* Sum of latency
* Sum of squares of latency
* Max latency

Upon receipt of a control packet, the server dumps several metrics to stdout, a statsd receiver, or both, including
* Count
* Expected count
* Sum of latency
* Sum of squares of latency
* Max latency

If the server does not receive a control packet within a keepalive timeout specified by the -k switch, it will output metrics with a zero expected count.

Metrics emitted to stdout are at the source host:port level.  Metrics emitted to statsd can either be at the host level only, or at the host level and the host:port level, as specified in the -s switch on the server.

At least one next-hop MAC address must be specified with the -a switch on the client.  This should ordinarily be set to the MAC address of the default gateway for the client.  If more than one egress path is desired, multiple next-hops can be separated by commas.

## Protocol

The header is defined by the following struct:

    typedef struct {
        uint8_t protoVersion;      // Allow for evolution of protocol
        time_t clientStartTime;    // Holds the creation time for the client session - used by the server to differentiate between runs
        char guid[MAX_GUID + 1];   // Unique identifier for a stream of packets
        seqnum_t seqNum;           // Monotonically increasing sequence number per client port
        struct timespec sent;      // High-resolution sender timestamp (resolution dependent on system clock resolution)
        uint32_t size;             // Size of the packet, including the header and the payload
    } packet;

A normal packet also includes a payload of random size, up to MAX - sizeof(packet), where MAX is specified by the -m switch on the client.

This code is licensed under Apache License 2.0 as per the license file and contains code from the reference implementation in RFC 1071.