ndt7

README

ndt7 Go client

Reference ndt7 Go client implementation. Useful resources:

• API exposed by this library;

• Manual for the ndt7-client CLI program;

• ndt7 protocol specification.

The master branch contains stable code. We don't promise we won't break the API, but we'll try not to.

Installing

You need Go >= 1.12. We use modules. Make sure Go knows that:

export GO111MODULE=on

Clone the repository wherever you want with

git clone https://github.com/m-lab/ndt7-client-go

From inside the repository, use go get ./cmd/ndt7-client to build the client. Binaries will be placed in $GOPATH/bin, if GOPATH is set, and in $HOME/go/bin otherwise.

If you're into a one-off install, this

go install -v github.com/m-lab/ndt7-client-go/cmd/ndt7-client@latest

is equivalent to cloning the repository, running go get ./cmd/ndt7-client, and then cancelling the repository directory.

Building with a custom client name

In case you are integrating an ndt7-client binary into a third-party application, it may be useful to build it with a custom client name. Since this value is passed to the server as metadata, doing so will allow you to retrieve measurements coming from your custom integration in Measurement Lab's data easily.

To set a custom client name at build time:

CLIENTNAME=my-custom-client-name

go build -ldflags "-X main.ClientName=$CLIENTNAME" ./cmd/ndt7-client

Prometheus Exporter

While ndt7-client is a "single shot" ndt7 client, there is also a non-interactive periodic test runner ndt7-prometheus-exporter.

Build and Run using Docker

git clone https://github.com/m-lab/ndt7-client-go
docker build -t ndt7-prometheus-exporter .

To run tests repeatedly

PORT=9191
docker run -d -p ${PORT}:8080 ndt7-prometheus-exporter

Sample Prometheus config

# scrape ndt7 test metrics
  - job_name: ndt7
    metrics_path: /metrics
    static_configs:
	  - targets:
	    # host:port of the exporter
	    - localhost:9191

# scrape ndt7-prometheus-exporter itself
  - job_name: ndt7-prometheus-exporter
    static_configs:
	  - targets:
	    # host:port of the exporter
		- localhost:9191

Documentation

Overview

Package ndt7 contains a ndt7 client.

The client will automatically discover a suitable server to use by default. However, you can also manually discover a server and configure the client accordingly.

The code configures reasonable I/O timeouts. We recommend to also provide contexts with whole-operation timeouts attached, as we do in the code example provided as part of this package.

Example

This shows how to run a ndt7 test.

ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()
client := ndt7.NewClient("ndt7-client-go-example", "0.1.0")
ch, err := client.StartDownload(ctx)
if err != nil {
	log.Fatal(err)
}
for ev := range ch {
	log.Printf("%+v", ev)
}
ch, err = client.StartUpload(ctx)
if err != nil {
	log.Fatal(err)
}
for ev := range ch {
	log.Printf("%+v", ev)
}

Index

• Constants
• Variables
• type Client
  • func NewClient(clientName, clientVersion string) *Client
  • func (c *Client) Results() map[spec.TestKind]*LatestMeasurements
  • func (c *Client) StartDownload(ctx context.Context) (<-chan spec.Measurement, error)
  • func (c *Client) StartUpload(ctx context.Context) (<-chan spec.Measurement, error)
• type LatestMeasurements
• type Locator

Examples

• Package

Constants

const DefaultWebSocketHandshakeTimeout = 7 * time.Second

DefaultWebSocketHandshakeTimeout is the default timeout configured by NewClient in the Client.Dialer.HandshakeTimeout field.

Variables

var (
	// ErrServiceUnsupported is returned if an unknown service URL is provided.
	ErrServiceUnsupported = errors.New("unsupported service url")

	// ErrNoTargets is returned if all Locate targets have been tried.
	ErrNoTargets = errors.New("no targets available")
)

Types

type Client

type Client struct {
	// ClientName is the name of the software running ndt7 tests. It's set by
	// NewClient; you may want to change this value.
	ClientName string

	// ClientVersion is the version of the software running ndt7 tests. It's
	// set by NewClient; you may want to change this value.
	ClientVersion string

	// Dialer is the optional websocket Dialer. It's set to its
	// default value by NewClient; you may override it.
	Dialer websocket.Dialer

	// FQDN is the server FQDN currently used by the Client. The FQDN is set
	// by Client at runtime. (read-only)
	FQDN string

	// Server is an optional server name. Client will use this target server if
	// not empty. Takes precedence over ServiceURL and Locate API.
	Server string

	// ServiceURL is an optional service url, fully specifying the scheme,
	// resource, and HTTP parameters. Takes precedence over the Locate API.
	ServiceURL *url.URL

	// Locate is used to discover nearby healthy servers using the Locate API.
	// NewClient defaults to the public Locate API URL. You may override it.
	Locate Locator

	// Scheme is the scheme to use with Server and Locate modes. It's set to
	// "wss" by NewClient, change it to "ws" for unencrypted ndt7.
	Scheme string
	// contains filtered or unexported fields
}

Client is a ndt7 client.

func NewClient

func NewClient(clientName, clientVersion string) *Client

NewClient creates a new client instance identified by the specified clientName and clientVersion. M-Lab services may reject requests coming from clients that do not identify themselves properly.

func (*Client) Results

func (c *Client) Results() map[spec.TestKind]*LatestMeasurements

Results returns the test results map.

func (*Client) StartDownload

func (c *Client) StartDownload(ctx context.Context) (<-chan spec.Measurement, error)

StartDownload discovers a ndt7 server (if needed) and starts a download. On success it returns a channel where measurements are emitted. This channel is closed when the download ends. On failure, the error is non nil and you should not attempt using the channel. A side effect of starting the download is that, if you did not specify a server FQDN, we will discover a server for you and store that value into the c.FQDN field.

func (*Client) StartUpload

func (c *Client) StartUpload(ctx context.Context) (<-chan spec.Measurement, error)

StartUpload is like StartDownload but for the upload.

type LatestMeasurements

type LatestMeasurements struct {
	Server         spec.Measurement
	Client         spec.Measurement
	ConnectionInfo *spec.ConnectionInfo
}

LatestMeasurements contains the latest Measurement sent by the server and the client, plus the latest ConnectionInfo sent by the server.

type Locator

type Locator interface {
	Nearest(ctx context.Context, service string) ([]v2.Target, error)
}

Locator is an interface used to locate a server.