README
¶
ndt7 Go client
Reference ndt7 Go client implementation. Useful resources:
The main 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.25.5.
Clone the repository wherever you want with
git clone https://github.com/m-lab/ndt7-client-go
From inside the repository, use go build -v ./cmd/ndt7-client to
build the client. Binaries will be placed in ..
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 build -v ./cmd/ndt7-client,
installing the binary in $HOME/go/bin and deleting the repository.
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
Usage
Run:
ndt7-client
to run a speedtest.
Use:
ndt7-client -format json
to obtain output in JSON format.
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.
package main
import (
"context"
"log"
"time"
"github.com/m-lab/ndt7-client-go"
)
func main() {
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)
}
}
Output:
Index ¶
Examples ¶
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") )
Functions ¶
func MakeUserAgent ¶ added in v0.10.0
MakeUserAgent creates the user agent string.
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 ¶
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 ¶ added in v0.3.0
func (c *Client) Results() map[spec.TestKind]*LatestMeasurements
Results returns the test results map.
func (*Client) StartDownload ¶
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 ¶
StartUpload is like StartDownload but for the upload.
type LatestMeasurements ¶ added in v0.3.0
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ndt7-client
command
ndt7-client is the ndt7 command line client.
|
ndt7-client is the ndt7 command line client. |
|
ndt7-prometheus-exporter
command
ndt7-prometheus-exporter is an ndt7 non-interactive prometheus exporting client
|
ndt7-prometheus-exporter is an ndt7 non-interactive prometheus exporting client |
|
internal
|
|
|
download
Package download contains ndt7 download code.
|
Package download contains ndt7 download code. |
|
emitter
Package emitter contains the ndt7-client emitter.
|
Package emitter contains the ndt7-client emitter. |
|
mocks
Package mocks implements mocks.
|
Package mocks implements mocks. |
|
params
Package params contains private constants and structs.
|
Package params contains private constants and structs. |
|
upload
Package upload contains ndt7 upload code
|
Package upload contains ndt7 upload code |
|
websocketx
Package websocketx contains websocket extensions.
|
Package websocketx contains websocket extensions. |
|
Package spec contains constants and structs.
|
Package spec contains constants and structs. |