goatapi

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 12, 2023 License: BSD-2-Clause-Views Imports: 17 Imported by: 0

README

goatapi - Go (RIPE) Atlas Tools - API Library

goatapi is a Go package to interact with RIPE Atlas APIs using Golang. It is similar to Cousteau and Sagan combined.

It supports:

  • finding probes, anchors and measurements
  • scheduling new measurements, stop existing ones
  • modify participants of an existing measurement (add/remove probes)
  • downloading results of measurements and turning them into Go objects
  • tuning in to result streaming and turning them into Go objects
  • loading a local file containing measurement results and turning them into Go objects

The tool needs Go 1.21 to compile.

Context

RIPE Atlas is an open, community based active Internet measurement network developed by the RIPE NCC since 2010. It provides a number of vantage points ("probes") run by volunteers, that allow various kinds of network measurements (pings, traceroutes, DNS queries, ...) to be run by any user.

Quick Start

Finding Probes

Count Probes Matching Some Criteria
	filter := goatapi.NewProbeFilter()
	filter.FilterCountry("NL")
	filter.FilterPublic(true)
	count, err := filter.GetProbeCount(false)
	if err != nil {
		// handle the error
	}
	fmt.Println(count)
Search for Probes
	filter := goatapi.NewProbeFilter()
	filter.FilterCountry("NL")
	filter.Sort("-id")
	probes := make(chan goatapi.AsyncProbeResult)
	go filter.GetProbes(false, probes) // false means non-verbose
	if err != nil {
		// handle the error
	}
	for probe := range probes {
		if probe.Error != nil {
			// handle the error
		} else {
			// process the result
		}
	}
Get a Particular Probe
	probe, err := filter.GetProbe(false, 10001) // false means non-verbose
	if err != nil {
		// handle the error
	}
	fmt.Println(probe.ShortString())

Finding Anchors

Count Anchors Matching Some Criteria
	filter := goatapi.NewAnchorFilter()
	filter.FilterCountry("NL")
	count, err := filter.GetAnchorCount(false)
	if err != nil {
		// handle the error
	}
	fmt.Println(count)
Search for Anchors
	filter := goatapi.NewAnchorFilter()
	filter.FilterCountry("NL")
	anchors := make(chan goatapi.AsyncAnchorResult)
	go filter.GetAnchors(false, anchors) // false means non-verbose
	if err != nil {
		// handle the error
	}
	for anchor := range anchors {
		if anchor.Error != nil {
			// handle the error
		} else {
			// process the result
		}
	}
Get a Particular Anchor
	anchor, err := filter.GetAnchor(false, 1080) // false means non-verbose
	if err != nil {
		// handle the error
	}
	fmt.Println(anchor.ShortString())

Finding Measurements

Count Measurements Matching Some Criteria
	filter := goatapi.NewMeasurementFilter()
	filter.FilterTarget(netip.ParsePrefix("193.0.0.0/19"))
	filter.FilterType("ping")
	filter.FilterOneoff(true)
	count, err := filter.GetMeasurementCount(false)
	if err != nil {
		// handle the error
	}
	fmt.Println(count)
Search for Measurements
	filter := goatapi.NewMeasurementFilter()
	filter.FilterTarget(netip.ParsePrefix("193.0.0.0/19"))
	filter.FilterType("ping")
	filter.FilterOneoff(true)
	filter.Sort("-id")
	msms := make(chan goatapi.AsyncMeasurementResult)
	go filter.GetMeasurements(false, msms) // false means non-verbose
	if err != nil {
		// handle the error
	}
	for msm := range msms {
		if msm.Error != nil {
			// handle the error
		} else {
			// process the result
		}
	}
Get a Particular Measurement
	msm, err := filter.GetMeasurement(false, 1001)
	if err != nil {
		// handle the error
	}
	fmt.Println(msm.ShortString())

Processing results

All result types are defined as object types (PingResult, TracerouteResult, DnsResult, ...). The Go types try to be more useful than what the API natively provides, i.e. there's a translation from what the API gives to objects that have more meaning and simpler to understand fields and methods.

Results can be fetched via a channel. The filter support measurement ID, start/end time, probe IDs, "latest" results and combinations of these.

Note: this is alpha level code. Some fields are probably mis-interpreted, old result versions are not processed correctly, a lot of corner cases are likely not handled properly and some objects should be passed as pointers instead. There's possibly a lot of work to be done here.

An example of retrieving and processing results from the data API:

	filter := goatapi.NewResultsFilter()
	filter.FilterID(10001)
	filter.FilterLatest()

	results := make(chan result.AsyncResult)
	go filter.GetResults(false, results) // false means verbose mode is off

	for result := range results {
		// do something with a result
	}

An example of retrieving and processing results from result streaming:

	filter := goatapi.NewResultsFilter()
	filter.FilterID(10001)
	filter.Stream(true)

	results := make(chan result.AsyncResult)
	go filter.GetResults(false, results) // false means verbose mode is off

	for result := range results {
		// do something with a result
	}

An example of retrieving and processing results from a file:

	filter := goatapi.NewResultsFilter()
	filter.FilterFile("-") // stdin, one can also use a proper file name
	// note: other filters can be added (namely start, stop and probe)

	results := make(chan result.AsyncResult)
	go filter.GetResults(false, results) // false means verbose mode is off

	for result := range results {
		// do something with a result
	}

Result types

The result package contains various types to hold corresponding measurement result types:

  • BaseResult is the basis of all and contains the basic fields such as MeasurementID, ProbeId, TimeStamp, Type and such
  • PingResult, TracerouteResult, DnsResult etc. contain the type-specific fields

Measurement Scheduling

You can schedule measuements with virtually all available API options. A quick example:

	spec := goatapi.NewMeasurementSpec()
	spec.ApiKey(myapikey)

	include := []string{"system-v4"}
	exclude := []string{"badtag", "anotherbad"}
	spec.AddProbesAreaWithTags("ww", 10, &include, &exclude)
	spec.AddProbesList([]uint{1, 99, 999})
	spec.AddProbesCountry("NL", 15)
	spec.AddProbesPrefix(netip.MustParsePrefix("192.0.0.0/8"), 5)

	spec.StartTime(tomorrownoon)
	spec.OneOff(true)

	spec.AddTrace(
		"my traceroute measurement",
		"ping.ripe.net",
		4,
		&goatapi.BaseOptions{ResolveOnProbe: true},
		&goatapi.TraceOptions{FirstHop: 4, ParisId: 9},
	)

	msmid, err := spec.Schedule()
	if err != nil {
		// use msmid
	}
Basics

A new measuement object can be created with NewMeasurementSpec(). In order to successfully submit this to the API, you need to add an API key using ApiKey(). It also needs to contain at least one probe definition and at least one measurement definition.

Probe Definitions

All variations of probe selection are supported:

  • AddProbesArea() and AddProbesAreaWithTags() to add probes from an area (WW, West, ...)
  • AddProbesCountry() and AddProbesCountryWithTags() to add probes from an country specified by its country code (ISO 3166-1 alpha-2)
  • AddProbesReuse() and AddProbesReuseWithTags() to reuse probes from a previous measurement
  • AddProbesAsn() and AddProbesAsnWithTags() to add probes from an ASN
  • AddProbesPrefix() and AddProbesPrefixWithTags() to add probes from a prefix (IPv4 or IPv6)
  • AddProbesList() and AddProbesListWithTags() to add probes with explicit probe IDs

Probe tags can be specified to include or exclude ones that have those specific tags.

Time Definitions

You can specify whether you want a one-off or an ongoing measurement using Oneoff().

Each measurement can have an explicit start time defined with StartTime(). Ongoing measurements can also have a predefined end time with EndTime(). These have to be sane regarding the current time (they need to be in the future) and to each other (end needs to happen after start). By default start time is as soon as possible with an undefined end time.

Measurement Definitions

Various measurements can be added with AddPing(), AddTrace(), AddDns(), AddTls(), AddNtp() and AddHttp(). Multiple measurements can be added to one specification; in this case they will use the same probes and timing.

All measurement types support setting common options using a BaseOptions{} structure. You can set the measurement interval, spread, the resolve-on-probe flag and so on here. If you are ok with the API defaults then you can leave this parameter to be nil.

All measurement types also accept type-specific options via the structures PingOptions{}, TraceOptions{}, DnsOptions{} and so on. If you are ok with the API defaults then you can leave this parameter to be nil as well.

Submitting a Measurement Specification to the API

The Schedule() function POSTs the whole specification to the API. It either returns with an error or a list of recently created measurement IDs. In case you're only interested in the API-compatible JSON structure without submitting it, then GetApiJson() should be called instead.

Adding and Removing Probes

One can ask for more probes to be added to a measurement, or existing ones to be removed. While the API itself can do both in one call, goatAPI only supports either additions or removals in one query. In order to add or remove probes, the same AddProbesX() functions can be used to specify the probe set, then ParticipationRequest(id, add) is used with either add=true to add or add=false to remove probes. Note that for the remove function only an explicit probe list (AddProbesList()) can be used in the API.

In order to successfully submit this to the API, you need to add an API key beforehand using ApiKey().

The return value of this function is a list of participation request IDs or an error.

Stopping a Measurement

You can stop a measuement via:

	spec := goatapi.NewMeasurementSpec()
	spec.ApiKey(myapikey)

	err := spec.Stop(msmID)
	if err != nil {
		// done
	}

Future Additions / TODO

  • check credit balance, transfer credits, ...

(C) 2022, 2023 Robert Kisteleki & RIPE NCC

Contribution is possible and encouraged via the Github repo

License

See the LICENSE file

Documentation

Index

Constants

View Source 
const (
	MeasurementStatusSpecified        = iota // 0
	MeasurementStatusScheduled               // 1
	MeasurementStatusOngoing                 // 2
	MeasurementStatusUnusedStatus            // 3
	MeasurementStatusStopped                 // 4
	MeasurementStatusForcedStop              // 5
	MeasurementStatusNoSuitableProbes        // 6
	MeasurementStatusFailed                  // 7
	MeasurementStatusDenied                  // 8
	MeasurementStatusCanceled                // 9
)

various measurement statuses

View Source 
const (
	ProbeStatusNeverConnected = iota // 0
	ProbeStatusConnected             // 1
	ProbeStatusDisconnected          // 2
	ProbeStatusAbandoned             // 3
)

various probe statuses

Variables

View Source 
var MeasurementListSortOrders = []string{
	"id", "-id",
	"start_time", "-start_time",
	"stop_time", "-stop_time",
	"is_oneoff", "-is_oneoff",
	"interval", "-interval",
	"type", "-type",
	"af", "-af",
	"status.name", "-status.name",
	"status.id", "-status.id",
}

MeasurementListSortOrders lists all the allowed sort orders

View Source 
var MeasurementOneoffDict = map[bool]string{
	// contains filtered or unexported fields
}

MeasurementStatusDict maps the measurement variations to human readable descriptions

View Source 
var MeasurementStatusDict = map[uint]string{
	MeasurementStatusSpecified:        "Specified",
	MeasurementStatusScheduled:        "Scheduled",
	MeasurementStatusOngoing:          "Ongoing",
	MeasurementStatusStopped:          "Stopped",
	MeasurementStatusForcedStop:       "ForcedStop",
	MeasurementStatusNoSuitableProbes: "NoSuitableProbes",
	MeasurementStatusFailed:           "Failed",
	MeasurementStatusDenied:           "Denied",
	MeasurementStatusCanceled:         "Canceled",
}

MeasurementStatusDict maps the measurement status codes to human readable descriptions

View Source 
var MeasurementTypes = []string{
	"ping", "traceroute", "dns", "http", "sslcert", "ntp",
}

MeasurementTypes lists all the allowed measurement types

View Source 
var ProbeListSortOrders = []string{
	"id", "-id",
}

ProbeListSortOrders lists all the allowed sort orders

View Source 
var ProbeStatusDict = map[uint]string{
	ProbeStatusNeverConnected: "NeverConnected",
	ProbeStatusConnected:      "Connected",
	ProbeStatusDisconnected:   "Disconnected",
	ProbeStatusAbandoned:      "Abandoned",
}

ProbeStatusDict maps the probe status codes to human readable descriptions

Functions

func ModifyUserAgent 

func ModifyUserAgent(addition string)

ModifyUserAgent allows the caller to refine the user agent to include some extra piece of text

func SetAPIBase 

func SetAPIBase(newAPIBaseURL string)

SetAPIBase allows the caller to modify the API to talk to This is really only useful to developers who have access to compatible APIs

func SetStreamBase added in v0.3.0 

func SetStreamBase(newStreamBaseURL string)

SetStreamBase allows the caller to modify the stream to talk to This is really only useful to developers who have access to compatible APIs

func UserAgent 

func UserAgent() string

UserAgent returns the user agent used by the package as a string

func ValidMeasurementListSortOrder 

func ValidMeasurementListSortOrder(sort string) bool

ValidMeasurementListSortOrder checks if a sort order is supported

func ValidMeasurementType 

func ValidMeasurementType(typ string) bool

ValidMeasurementType checks if a measurment type is recognised

func ValidProbeListSortOrder 

func ValidProbeListSortOrder(sort string) bool

ValidProbeListSortOrder checks if a sort order is supported

Types

type Anchor 

type Anchor struct {
	ID              uint        `json:"id"`
	Address4        *netip.Addr `json:"ip_v4"`
	ASN4            *uint       `json:"as_v4"`
	IPv4Gateway     *netip.Addr `json:"ip_v4_gateway"`
	IPv4Netmask     *netip.Addr `json:"ip_v4_netmask"`
	Address6        *netip.Addr `json:"ip_v6"`
	ASN6            *uint       `json:"as_v6"`
	IPv6Gateway     *netip.Addr `json:"ip_v6_gateway"`
	IPv6Netmask     *netip.Addr `json:"ip_v6_netmask"`
	FQDN            string      `json:"fqdn"`
	ProbeID         uint        `json:"probe"`
	CountryCode     string      `json:"country"`
	City            string      `json:"city"`
	Company         string      `json:"company"`
	IPv4Only        bool        `json:"is_ipv4_only"`
	Disabled        bool        `json:"is_disabled"`
	NicHandle       string      `json:"nic_handle"`
	Location        Geolocation `json:"geometry"`
	Type            string      `json:"type"`
	TLSARecord      string      `json:"tlsa_record"`
	LiveSince       *uniTime    `json:"date_live"`
	HardwareVersion uint        `json:"hardware_version"`
}

Anchor object, as it comes from the API

func GetAnchor 

func GetAnchor(
	verbose bool,
	id uint,
) (
	anchor *Anchor,
	err error,
)

GetAnchor retrieves data for a single anchor, by ID returns anchor, _ if an anchor was found returns nil, _ if an anchor was not found returns _, err on error

func (*Anchor) LongString 

func (anchor *Anchor) LongString() string

LongString produces a longer textual description of the anchor

func (*Anchor) ShortString 

func (anchor *Anchor) ShortString() string

ShortString produces a short textual description of the anchor

type AnchorFilter 

type AnchorFilter struct {
	// contains filtered or unexported fields
}

AnchorFilter struct holds specified filters and other options

func NewAnchorFilter 

func NewAnchorFilter() AnchorFilter

NewAnchorFilter prepares a new anchor filter object

func (*AnchorFilter) FilterASN4 

func (filter *AnchorFilter) FilterASN4(as uint)

FilterASN4 filters for an ASN in IPv4 space

func (*AnchorFilter) FilterASN6 

func (filter *AnchorFilter) FilterASN6(as uint)

FilterASN6 filters for an ASN in IPv6 space

func (*AnchorFilter) FilterCountry 

func (filter *AnchorFilter) FilterCountry(cc string)

FilterCountry filters by a country code (ISO3166-1 alpha-2)

func (*AnchorFilter) FilterID 

func (filter *AnchorFilter) FilterID(id uint)

FilterID filters by a particular anchor ID

func (*AnchorFilter) FilterSearch 

func (filter *AnchorFilter) FilterSearch(text string)

FilterSearch filters within the fields `city`, `fqdn` and `company`

func (*AnchorFilter) GetAnchorCount 

func (filter *AnchorFilter) GetAnchorCount() (
	count uint,
	err error,
)

GetAnchorCount returns the count of anchors by filtering

func (*AnchorFilter) GetAnchors 

func (filter *AnchorFilter) GetAnchors(
	anchors chan AsyncAnchorResult,
)

GetAnchors returns a bunch of anchors by filtering Results (or an error) appear on a channel

func (*AnchorFilter) Limit 

func (filter *AnchorFilter) Limit(max uint)

Limit limits the number of result retrieved

func (*AnchorFilter) Verbose added in v0.4.0 

func (filter *AnchorFilter) Verbose(verbose bool)

Verboe sets verbosity

type AsyncAnchorResult added in v0.2.1 

type AsyncAnchorResult struct {
	Anchor Anchor
	Error  error
}

type AsyncMeasurementResult added in v0.2.1 

type AsyncMeasurementResult struct {
	Measurement Measurement
	Error       error
}

type AsyncProbeResult added in v0.2.1 

type AsyncProbeResult struct {
	Probe Probe
	Error error
}

type AsyncStatusCheckResult added in v0.4.0 

type AsyncStatusCheckResult struct {
	Status *StatusCheckResult
	Error  error
}

a status check result: error or value

type BaseOptions added in v0.4.0 

type BaseOptions struct {
	ResolveOnProbe bool
	Interval       uint
	Tags           []string
	Spread         uint
	SkipDNSCheck   bool
}

various measurement options

type DnsOptions added in v0.4.0 

type DnsOptions struct {
	Protocol       string // default: UDP
	Class          string
	Type           string
	Argument       string
	UseMacros      bool // API default: false
	UseResolver    bool // API default: false
	Nsid           bool // API default: false
	UdpPayloadSize uint // API default: 512
	Retries        uint // API default: 0
	IncludeQbuf    bool // API default: false
	IncludeAbuf    bool // API default: false
	PrependProbeID bool // API default: false
	SetRd          bool // API default: false
	SetDo          bool // API default: false
	SetCd          bool // API default: false
	Timeout        uint // API default: 5000 (ms)
}

type ErrorDetail 

type ErrorDetail struct {
	Detail string         `json:"detail"`
	Status int            `json:"status"`
	Title  string         `json:"title"`
	Code   int            `json:"code"`
	Errors []ErrorMessage `json:"errors"`
}

ErrorDetails type

type ErrorMessage added in v0.2.1 

type ErrorMessage struct {
	Source ErrorSource `json:"source"`
	Detail string      `json:"detail"`
}

type ErrorSource added in v0.2.1 

type ErrorSource struct {
	Pointer string `json:"pointer"`
}

type Geolocation 

type Geolocation struct {
	Type        string    `json:"type"`
	Coordinates []float32 `json:"coordinates"`
}

Geolocation type

type HttpOptions added in v0.4.0 

type HttpOptions struct {
	Method             string
	Path               string
	Query              string
	Port               uint
	HeaderBytes        uint
	Version            string
	ExtendedTiming     bool
	MoreExtendedTiming bool
}

type Measurement 

type Measurement struct {
	ID               uint               `json:"id"`
	CreationTime     uniTime            `json:"creation_time"`
	StartTime        uniTime            `json:"start_time"`
	StopTime         *uniTime           `json:"stop_time"`
	Status           MeasurementStatus  `json:"status"`
	GroupID          *uint              `json:"group_id"`
	ResolvedIPs      *[]netip.Addr      `json:"resolved_ips"`
	Description      *string            `json:"description"`
	Type             string             `json:"type"`
	Target           string             `json:"target"`
	TargetASN        *uint              `json:"target_asn"`
	TargetIP         netip.Addr         `json:"target_ip"`
	TargetPrefix     *netip.Prefix      `json:"target_prefix"`
	InWifiGroup      bool               `json:"in_wifi_group"`
	AddressFamily    *uint              `json:"af"`
	AllScheduled     bool               `json:"is_all_scheduled"`
	Interval         *uint              `json:"interval"`
	Spread           *uint              `json:"spread"`
	OneOff           bool               `json:"is_oneoff"`
	Public           bool               `json:"is_public"`
	ResolveOnProbe   bool               `json:"resolve_on_probe"`
	ParticipantCount *uint              `json:"participant_count"`
	ProbesRequested  *int               `json:"probes_requested"`
	ProbesScheduled  *uint              `json:"probes_scheduled"`
	CreditsPerResult uint               `json:"credits_per_result"`
	ResultsPerDay    uint               `json:"estimated_results_per_day"`
	Probes           []ParticipantProbe `json:"probes"`
	Tags             []string           `json:"tags"`
}

Measurement object, as it comes from the API

func GetMeasurement 

func GetMeasurement(
	verbose bool,
	id uint,
	key *uuid.UUID,
) (
	*Measurement,
	error,
)

GetMeasurement retrieves data for a single measurement, by ID returns measurement, nil if a measurement was found returns nil, nil if no such measurement was found returns nil, err on error

func (*Measurement) LongString 

func (measurement *Measurement) LongString() string

LongString produces a longer textual description of the measurement

func (*Measurement) ShortString 

func (measurement *Measurement) ShortString() string

ShortString produces a short textual description of the measurement

type MeasurementFilter 

type MeasurementFilter struct {
	// contains filtered or unexported fields
}

MeasurementFilter struct holds specified filters and other options

func NewMeasurementFilter 

func NewMeasurementFilter() MeasurementFilter

NewMeasurementFilter prepares a new measurement filter object

func (*MeasurementFilter) ApiKey 

func (filter *MeasurementFilter) ApiKey(key *uuid.UUID)

ApiKey sets the API key to be used This key should have the "list_measurements" permission

func (*MeasurementFilter) FilterAddressFamily 

func (filter *MeasurementFilter) FilterAddressFamily(af uint)

FilterAddressFamily filters for measurements using a particular address family 4 for IPv4, 6 for IPv6

func (*MeasurementFilter) FilterDescriptionEndsWith 

func (filter *MeasurementFilter) FilterDescriptionEndsWith(what string)

FilterDescriptionEndsWith filters for measurements that end with this string in their description

func (*MeasurementFilter) FilterDescriptionHas 

func (filter *MeasurementFilter) FilterDescriptionHas(what string)

FilterDescriptionHas filters for measurements that have a specific string in their description

func (*MeasurementFilter) FilterDescriptionIs 

func (filter *MeasurementFilter) FilterDescriptionIs(what string)

FilterDescriptionIs filters for measurements that have a specific description

func (*MeasurementFilter) FilterDescriptionStartsWith 

func (filter *MeasurementFilter) FilterDescriptionStartsWith(what string)

FilterDescriptionStartsWith filters for measurements that start with this string in their description

func (*MeasurementFilter) FilterID 

func (filter *MeasurementFilter) FilterID(id uint)

FilterID filters by a particular measurement ID

func (*MeasurementFilter) FilterIDGt 

func (filter *MeasurementFilter) FilterIDGt(n uint)

FilterIDGt filters for msm IDs > some number

func (*MeasurementFilter) FilterIDGte 

func (filter *MeasurementFilter) FilterIDGte(n uint)

FilterIDGte filters for msm IDs >= some number

func (*MeasurementFilter) FilterIDLt 

func (filter *MeasurementFilter) FilterIDLt(n uint)

FilterIDLt filters for msm IDs < some number

func (*MeasurementFilter) FilterIDLte 

func (filter *MeasurementFilter) FilterIDLte(n uint)

FilterIDLt filters for msm IDs <= some number

func (*MeasurementFilter) FilterIDin 

func (filter *MeasurementFilter) FilterIDin(list []uint)

FilterIDin filters for measurement ID being one of several in the list specified

func (*MeasurementFilter) FilterInterval 

func (filter *MeasurementFilter) FilterInterval(n uint)

FilterInterval filters for measurement interval being a specific number (seconds)

func (*MeasurementFilter) FilterIntervalGt 

func (filter *MeasurementFilter) FilterIntervalGt(n uint)

FilterIntervalGt filters for measurement interval being > a specific number (seconds)

func (*MeasurementFilter) FilterIntervalGte 

func (filter *MeasurementFilter) FilterIntervalGte(n uint)

FilterIntervalGte filters for measurement interval being >= a specific number (seconds)

func (*MeasurementFilter) FilterIntervalLt 

func (filter *MeasurementFilter) FilterIntervalLt(n uint)

FilterIntervalLt filters for measurement interval being < a specific number (seconds)

func (*MeasurementFilter) FilterIntervalLte 

func (filter *MeasurementFilter) FilterIntervalLte(n uint)

FilterIntervalLte filters for measurement interval being <= a specific number (seconds)

func (*MeasurementFilter) FilterMy 

func (filter *MeasurementFilter) FilterMy()

FilterMy filters to my own measurements - and needs an API key todo so

func (*MeasurementFilter) FilterOneoff 

func (filter *MeasurementFilter) FilterOneoff(oneoff bool)

FilterOneoff filters for one-off or ongoing measurements If oneoff is true then only one-offs are returned If oneoff is false then only ongoings are returned

func (*MeasurementFilter) FilterProbe 

func (filter *MeasurementFilter) FilterProbe(id uint)

FilterProbe filters for measurements that have a particular probe participating in them

func (*MeasurementFilter) FilterProtocol 

func (filter *MeasurementFilter) FilterProtocol(protocol string)

FilterProtocol filters for measurements using a particular protocol Protocol can be ICMP, UDP or TCP for traceroutes, UDP or TCP for DNS

func (*MeasurementFilter) FilterStarttimeGt 

func (filter *MeasurementFilter) FilterStarttimeGt(t time.Time)

FilterStarttimeGt filters for measurement that start/started after a specific time

func (*MeasurementFilter) FilterStarttimeGte 

func (filter *MeasurementFilter) FilterStarttimeGte(t time.Time)

FilterStarttimeGte filters for measurements that start/started after or at a specific time

func (*MeasurementFilter) FilterStarttimeLt 

func (filter *MeasurementFilter) FilterStarttimeLt(t time.Time)

FilterStarttimeLt filters for measurements that start/started before a specific time

func (*MeasurementFilter) FilterStarttimeLte 

func (filter *MeasurementFilter) FilterStarttimeLte(t time.Time)

FilterStarttimeLte filters for measurements that start/started before or at a specific time

func (*MeasurementFilter) FilterStatus 

func (filter *MeasurementFilter) FilterStatus(n uint)

FilterStatus filters for measurements that have a specific status See: const MeasurementStatusSpecified*

func (*MeasurementFilter) FilterStatusIn 

func (filter *MeasurementFilter) FilterStatusIn(list []uint)

FilterStatusIn filters for measurements that are in a set of statuses See: const MeasurementStatusSpecified*

func (*MeasurementFilter) FilterStoptimeGt 

func (filter *MeasurementFilter) FilterStoptimeGt(t time.Time)

FilterStoptimeGt filters for measurements that stop/stopped after a specific time

func (*MeasurementFilter) FilterStoptimeGte 

func (filter *MeasurementFilter) FilterStoptimeGte(t time.Time)

FilterStoptimeGte filters for measurements that stop/stopped after or at a specific time

func (*MeasurementFilter) FilterStoptimeLt 

func (filter *MeasurementFilter) FilterStoptimeLt(t time.Time)

FilterStoptimeLt filters for measurements that stop/stopped before a specific time

func (*MeasurementFilter) FilterStoptimeLte 

func (filter *MeasurementFilter) FilterStoptimeLte(t time.Time)

FilterStoptimeLte filters for measurements that stop/stopped before or at a specific time

func (*MeasurementFilter) FilterTags 

func (filter *MeasurementFilter) FilterTags(list []string)

FilterTags filters for measurements with the specified tags Speficying multiple tags results in an AND behaviour

func (*MeasurementFilter) FilterTarget 

func (filter *MeasurementFilter) FilterTarget(target netip.Prefix)

FilterTarget filters for measurements that target a specific IP (IPv4 /32 or IPv6 /128) or are withing a particular IPV4 or IPv6 prefix ("more specific" search)

func (*MeasurementFilter) FilterTargetEndsWith 

func (filter *MeasurementFilter) FilterTargetEndsWith(what string)

FilterTargetEndsWith filters for measurements that end with this string in their target

func (*MeasurementFilter) FilterTargetHas 

func (filter *MeasurementFilter) FilterTargetHas(what string)

FilterTargetHas filters for measurements that have a substring in their target

func (*MeasurementFilter) FilterTargetIs 

func (filter *MeasurementFilter) FilterTargetIs(what string)

FilterTargetIs filters for measurements that have a specific target as a string (DNS name or IP address)

func (*MeasurementFilter) FilterTargetStartsWith 

func (filter *MeasurementFilter) FilterTargetStartsWith(what string)

FilterTargetStartsWith filters for measurements that start with this string in their target

func (*MeasurementFilter) FilterType 

func (filter *MeasurementFilter) FilterType(typ string)

FilterType filters for measurements that have a specific type See also: MeasurementTypes

func (*MeasurementFilter) GetMeasurementCount 

func (filter *MeasurementFilter) GetMeasurementCount() (
	count uint,
	err error,
)

GetMeasurementCount returns the count of measurements by filtering

func (*MeasurementFilter) GetMeasurements 

func (filter *MeasurementFilter) GetMeasurements(
	measurements chan AsyncMeasurementResult,
)

GetMeasurements returns a bunch of measurements by filtering Results (or an error) appear on a channel

func (*MeasurementFilter) Limit 

func (filter *MeasurementFilter) Limit(limit uint)

Limit limits the number of result retrieved

func (*MeasurementFilter) Sort 

func (filter *MeasurementFilter) Sort(by string)

Sort asks the result list to be sorted by some ordering See also: MeasurementListSortOrders

func (*MeasurementFilter) Verbose added in v0.4.0 

func (filter *MeasurementFilter) Verbose(verbose bool)

Verbose sets verbosity

type MeasurementList added in v0.4.0 

type MeasurementList struct {
	Measurements []uint `json:"measurements"`
}

type MeasurementSpec added in v0.4.0 

type MeasurementSpec struct {
	// contains filtered or unexported fields
}

Measurement specification object, to be passed to the API

func NewMeasurementSpec added in v0.4.0 

func NewMeasurementSpec() (spec *MeasurementSpec)

func (*MeasurementSpec) AddDns added in v0.4.0 

func (spec *MeasurementSpec) AddDns(
	description string,
	target string,
	af uint,
	baseoptions *BaseOptions,
	dnsoptions *DnsOptions,
) error

func (*MeasurementSpec) AddHttp added in v0.4.0 

func (spec *MeasurementSpec) AddHttp(
	description string,
	target string,
	af uint,
	baseoptions *BaseOptions,
	httpoptions *HttpOptions,
) error

func (*MeasurementSpec) AddNtp added in v0.4.0 

func (spec *MeasurementSpec) AddNtp(
	description string,
	target string,
	af uint,
	baseoptions *BaseOptions,
	ntpoptions *NtpOptions,
) error

func (*MeasurementSpec) AddPing added in v0.4.0 

func (spec *MeasurementSpec) AddPing(
	description string,
	target string,
	af uint,
	baseoptions *BaseOptions,
	pingoptions *PingOptions,
) error

func (*MeasurementSpec) AddProbesArea added in v0.4.0 

func (spec *MeasurementSpec) AddProbesArea(area string, n int) error

func (*MeasurementSpec) AddProbesAreaWithTags added in v0.4.0 

func (spec *MeasurementSpec) AddProbesAreaWithTags(area string, n int, tagsincl *[]string, tagsexcl *[]string) error

func (*MeasurementSpec) AddProbesAsn added in v0.4.0 

func (spec *MeasurementSpec) AddProbesAsn(asn uint, n int) error

func (*MeasurementSpec) AddProbesAsnWithTags added in v0.4.0 

func (spec *MeasurementSpec) AddProbesAsnWithTags(asn uint, n int, tagsincl *[]string, tagsexcl *[]string) error

func (*MeasurementSpec) AddProbesCountry added in v0.4.0 

func (spec *MeasurementSpec) AddProbesCountry(cc string, n int) error

func (*MeasurementSpec) AddProbesCountryWithTags added in v0.4.0 

func (spec *MeasurementSpec) AddProbesCountryWithTags(cc string, n int, tagsincl *[]string, tagsexcl *[]string) error

func (*MeasurementSpec) AddProbesList added in v0.4.0 

func (spec *MeasurementSpec) AddProbesList(list []uint) error

func (*MeasurementSpec) AddProbesListWithTags added in v0.4.0 

func (spec *MeasurementSpec) AddProbesListWithTags(list []uint, tagsincl *[]string, tagsexcl *[]string) error

func (*MeasurementSpec) AddProbesPrefix added in v0.4.0 

func (spec *MeasurementSpec) AddProbesPrefix(prefix netip.Prefix, n int) error

func (*MeasurementSpec) AddProbesPrefixWithTags added in v0.4.0 

func (spec *MeasurementSpec) AddProbesPrefixWithTags(prefix netip.Prefix, n int, tagsincl *[]string, tagsexcl *[]string) error

func (*MeasurementSpec) AddProbesReuse added in v0.4.0 

func (spec *MeasurementSpec) AddProbesReuse(msm uint, n int) error

func (*MeasurementSpec) AddProbesReuseWithTags added in v0.4.0 

func (spec *MeasurementSpec) AddProbesReuseWithTags(msm uint, n int, tagsincl *[]string, tagsexcl *[]string) error

func (*MeasurementSpec) AddTls added in v0.4.0 

func (spec *MeasurementSpec) AddTls(
	description string,
	target string,
	af uint,
	baseoptions *BaseOptions,
	tlsoptions *TlsOptions,
) error

func (*MeasurementSpec) AddTrace added in v0.4.0 

func (spec *MeasurementSpec) AddTrace(
	description string,
	target string,
	af uint,
	baseoptions *BaseOptions,
	traceoptions *TraceOptions,
) error

func (*MeasurementSpec) ApiKey added in v0.4.0 

func (filter *MeasurementSpec) ApiKey(key *uuid.UUID)

ApiKey sets the API key to be used This key should have the required permission (create or stop)

func (*MeasurementSpec) BillTo added in v0.4.0 

func (spec *MeasurementSpec) BillTo(billto string)

func (*MeasurementSpec) EndTime added in v0.5.0 

func (spec *MeasurementSpec) EndTime(time time.Time)

func (*MeasurementSpec) GetApiJson added in v0.4.0 

func (spec *MeasurementSpec) GetApiJson() ([]byte, error)

func (*MeasurementSpec) OneOff added in v0.4.0 

func (spec *MeasurementSpec) OneOff(oneoff bool)

func (*MeasurementSpec) ParticipationRequest added in v0.5.0 

func (spec *MeasurementSpec) ParticipationRequest(msmID uint, add bool) ([]uint, error)

ParticipationRequest is used to add or remove probes to/from existing measurement the actual probe specification on what to add or remove comes in the form of measurementProbeDefinition objects in the specification

func (*MeasurementSpec) Schedule added in v0.5.0 

func (spec *MeasurementSpec) Schedule() (msmlist []uint, err error)

func (*MeasurementSpec) StartTime added in v0.5.0 

func (spec *MeasurementSpec) StartTime(time time.Time)

func (*MeasurementSpec) Stop added in v0.4.0 

func (spec *MeasurementSpec) Stop(msmID uint) error

func (*MeasurementSpec) Verbose added in v0.4.0 

func (spec *MeasurementSpec) Verbose(verbose bool)

type MeasurementStatus 

type MeasurementStatus struct {
	ID    uint     `json:"id"`
	Name  string   `json:"name"`
	Since *uniTime `json:"when"`
}

MeasurementStatus as defined by the API

type MultiErrorResponse added in v0.2.1 

type MultiErrorResponse struct {
	ErrorDetail
	Error  ErrorDetail    `json:"error"`
	Errors []ErrorMessage `json:"errors"`
}

ErrorResponse type

type NtpOptions added in v0.4.0 

type NtpOptions struct {
	Packets uint // API default: 3
	Timeout uint // API default: 4000 (ms)
}

type ParticipantProbe 

type ParticipantProbe struct {
	ID uint `json:"id"`
}

ParticipantProbe - only the ID though

type PingOptions added in v0.4.0 

type PingOptions struct {
	Packets        uint // API default: 3
	PacketSize     uint // API default: 48 bytes
	PacketInterval uint // Time between packets (ms)
	IncludeProbeID bool // Include the probe ID (encoded as ASCII digits) as part of the payload
}

type Probe 

type Probe struct {
	ID             uint          `json:"id"`
	Address4       *netip.Addr   `json:"address_v4"`
	Address6       *netip.Addr   `json:"address_v6"`
	ASN4           *uint         `json:"asn_v4"`
	ASN6           *uint         `json:"asn_v6"`
	CountryCode    string        `json:"country_code"`
	Description    string        `json:"description"`
	FirstConnected *uniTime      `json:"first_connected"`
	LastConnected  *uniTime      `json:"last_connected"`
	Location       Geolocation   `json:"geometry"`
	Anchor         bool          `json:"is_anchor"`
	Prefix4        *netip.Prefix `json:"prefix_v4"`
	Prefix6        *netip.Prefix `json:"prefix_v6"`
	Public         bool          `json:"is_public"`
	Status         ProbeStatus   `json:"status"`
	StatusSince    uniTime       `json:"status_since"`
	TotalUptime    uint          `json:"total_uptime"`
	Type           string        `json:"type"`
	Tags           []Tag         `json:"tags"`
}

Probe object, as it comes from the API

func GetProbe 

func GetProbe(
	verbose bool,
	id uint,
) (
	*Probe,
	error,
)

GetProbe retrieves data for a single probe, by ID returns probe, nil if a probe was found returns nil, nil if no such probe was found returns nil, err on error

func (*Probe) LongString 

func (probe *Probe) LongString() string

LongString produces a longer textual description of the probe

func (*Probe) ShortString 

func (probe *Probe) ShortString() string

ShortString produces a short textual description of the probe

type ProbeFilter 

type ProbeFilter struct {
	// contains filtered or unexported fields
}

ProbeFilter struct holds specified filters and other options

func NewProbeFilter 

func NewProbeFilter() *ProbeFilter

NewProbeFilter prepares a new probe filter object

func (*ProbeFilter) FilterASN 

func (filter *ProbeFilter) FilterASN(n uint)

FilterASN filters for an ASN in IPv4 or IPv6 space

func (*ProbeFilter) FilterASN4 

func (filter *ProbeFilter) FilterASN4(n uint)

FilterASN4 filters for an ASN in IPv4 space

func (*ProbeFilter) FilterASN4in 

func (filter *ProbeFilter) FilterASN4in(list []uint)

FilterASN4in filters for an ASN on this list in IPv4 space

func (*ProbeFilter) FilterASN6 

func (filter *ProbeFilter) FilterASN6(n uint)

FilterASN6 filters for an ASN in IPv6 space

func (*ProbeFilter) FilterASN6in 

func (filter *ProbeFilter) FilterASN6in(list []uint)

FilterASN6in filters for an ASN on this list in IPv6 space

func (*ProbeFilter) FilterAnchor 

func (filter *ProbeFilter) FilterAnchor(yesno bool)

FilterAnchor filters for probes that are anchors (true) or regular probes (false)

func (*ProbeFilter) FilterCountry 

func (filter *ProbeFilter) FilterCountry(cc string)

FilterCountry filters by a country code (ISO3166-1 alpha-2)

func (*ProbeFilter) FilterID 

func (filter *ProbeFilter) FilterID(id uint)

FilterID filters by a particular probe ID

func (*ProbeFilter) FilterIDGt 

func (filter *ProbeFilter) FilterIDGt(n uint)

FilterIDGt filters for probe IDs > some number

func (*ProbeFilter) FilterIDGte 

func (filter *ProbeFilter) FilterIDGte(n uint)

FilterIDGte filters for probe IDs >= some number

func (*ProbeFilter) FilterIDLt 

func (filter *ProbeFilter) FilterIDLt(n uint)

FilterIDLt filters for probe IDs < some number

func (*ProbeFilter) FilterIDLte 

func (filter *ProbeFilter) FilterIDLte(n uint)

FilterIDLte filters for probe IDs <= some number

func (*ProbeFilter) FilterIDin 

func (filter *ProbeFilter) FilterIDin(list []uint)

FilterIDin filters for probe ID being one of several in the list specified

func (*ProbeFilter) FilterLatitudeGt 

func (filter *ProbeFilter) FilterLatitudeGt(f float64)

FilterLatitudeGt filters for probes with latitude being greater than ('north of') this value (in degrees)

func (*ProbeFilter) FilterLatitudeGte 

func (filter *ProbeFilter) FilterLatitudeGte(f float64)

FilterLatitudeGte filters for probes with latitude being greater than or equal to ('north of') this value (in degrees)

func (*ProbeFilter) FilterLatitudeLt 

func (filter *ProbeFilter) FilterLatitudeLt(f float64)

FilterLatitudeLt filters for probes with latitude being greater than ('south of') this value (in degrees)

func (*ProbeFilter) FilterLatitudeLte 

func (filter *ProbeFilter) FilterLatitudeLte(f float64)

FilterLatitudeLte filters for probes with latitude being greater than or equal to ('south of') this value (in degrees)

func (*ProbeFilter) FilterLongitudeGt 

func (filter *ProbeFilter) FilterLongitudeGt(f float64)

FilterLongitudeGt filters for probes with longitude being greater than ('east of') this value (in degrees)

func (*ProbeFilter) FilterLongitudeGte 

func (filter *ProbeFilter) FilterLongitudeGte(f float64)

FilterLongitudeGte filters for probes with longitude being greater than or eaual to ('east of') this value (in degrees)

func (*ProbeFilter) FilterLongitudeLt 

func (filter *ProbeFilter) FilterLongitudeLt(f float64)

FilterLongitudeLt filters for probes with longitude being greater than ('west of') this value (in degrees)

func (*ProbeFilter) FilterLongitudeLte 

func (filter *ProbeFilter) FilterLongitudeLte(f float64)

FilterLongitudeLte filters for probes with longitude being greater than or equal to ('west of') this value (in degrees)

func (*ProbeFilter) FilterPrefixV4 

func (filter *ProbeFilter) FilterPrefixV4(prefix netip.Prefix)

FilterPrefixV4 filters for probes that are in a specific IPv4 prefix

func (*ProbeFilter) FilterPrefixV6 

func (filter *ProbeFilter) FilterPrefixV6(prefix netip.Prefix)

FilterPrefixV6 filters for probes that are in a specific IPv6 prefix

func (*ProbeFilter) FilterPublic 

func (filter *ProbeFilter) FilterPublic(yesno bool)

FilterPublic filters for probes that are public or non-public

func (*ProbeFilter) FilterRadius 

func (filter *ProbeFilter) FilterRadius(lat, lon, radius float64)

FilterRadius filters for probes that are within the radius (in km) of a coordinate It assumes the use of FilterLatitude and FilterLongitude as well

func (*ProbeFilter) FilterStatus 

func (filter *ProbeFilter) FilterStatus(n uint)

FilterStatus filters for probes that have a specific status See: const MeasurementStatusSpecified*

func (*ProbeFilter) FilterTags 

func (filter *ProbeFilter) FilterTags(tags []string)

FilterTags filters for probes with the specified tags Speficying multiple tags results in an AND behaviour

func (*ProbeFilter) GetProbeCount 

func (filter *ProbeFilter) GetProbeCount() (
	count uint,
	err error,
)

GetProbeCount returns the count of probes by filtering

func (*ProbeFilter) GetProbes 

func (filter *ProbeFilter) GetProbes(
	probes chan AsyncProbeResult,
)

GetProbes returns a bunch of probes by filtering Results (or an error) appear on a channel

func (*ProbeFilter) Limit 

func (filter *ProbeFilter) Limit(limit uint)

Limit limits the number of result retrieved

func (*ProbeFilter) Sort 

func (filter *ProbeFilter) Sort(by string)

Sort asks the result list to be sorted by some ordering See also: ProbeListSortOrders

func (*ProbeFilter) Verbose added in v0.4.0 

func (filter *ProbeFilter) Verbose(verbose bool)

Verbose sets verbosity

type ProbeStatus 

type ProbeStatus struct {
	ID    uint     `json:"id"`
	Name  string   `json:"name"`
	Since *uniTime `json:"since"`
}

ProbeStatus as defined by the API

type ResultsFilter added in v0.2.0 

type ResultsFilter struct {
	// contains filtered or unexported fields
}

ResultsFilter struct holds specified filters and other options

func NewResultsFilter added in v0.2.0 

func NewResultsFilter() ResultsFilter

NewResultsFilter prepares a new result filter object

func (*ResultsFilter) FilterAnchors added in v0.2.0 

func (filter *ResultsFilter) FilterAnchors()

FilterAnchors filters for results reported by anchors

func (*ResultsFilter) FilterFile added in v0.2.0 

func (filter *ResultsFilter) FilterFile(filename string)

FilterFile "filters" results from a particular file

func (*ResultsFilter) FilterID added in v0.2.0 

func (filter *ResultsFilter) FilterID(id uint)

FilterID filters by a particular measurement ID

func (*ResultsFilter) FilterLatest added in v0.2.0 

func (filter *ResultsFilter) FilterLatest()

FilterLatest "filters" for downloading the latest results only

func (*ResultsFilter) FilterProbeIDs added in v0.2.0 

func (filter *ResultsFilter) FilterProbeIDs(list []uint)

FilterProbeIDs filters for results where the probe ID is one of several in the list specified

func (*ResultsFilter) FilterPublicProbes added in v0.2.0 

func (filter *ResultsFilter) FilterPublicProbes()

FilterPublicProbes filters for results reported by public probes

func (*ResultsFilter) FilterStart added in v0.2.0 

func (filter *ResultsFilter) FilterStart(t time.Time)

FilterStart filters for results after this timestamp

func (*ResultsFilter) FilterStop added in v0.2.0 

func (filter *ResultsFilter) FilterStop(t time.Time)

FilterStop filters for results before this timestamp

func (*ResultsFilter) GetResults added in v0.2.0 

func (filter *ResultsFilter) GetResults(
	verbose bool,
	results chan result.AsyncResult,
)

GetResult returns results via various means by filtering Results (or an error) appear on a channel

func (*ResultsFilter) Limit added in v0.2.0 

func (filter *ResultsFilter) Limit(max uint)

Limit limits the number of result retrieved

func (*ResultsFilter) Save added in v0.3.0 

func (filter *ResultsFilter) Save(file *os.File)

Save the results to this particular file

func (*ResultsFilter) SaveAll added in v0.3.0 

func (filter *ResultsFilter) SaveAll(all bool)

SaveAll determines if all results are saved, or only the matched ones

func (*ResultsFilter) Stream added in v0.3.0 

func (filter *ResultsFilter) Stream(useStream bool)

Stream switches between using the streaming or the data API

type StatusCheckFilter added in v0.4.0 

type StatusCheckFilter struct {
	// contains filtered or unexported fields
}

StatusCheckFilter struct holds specified filters and other options

func NewStatusCheckFilter added in v0.4.0 

func NewStatusCheckFilter() StatusCheckFilter

NewStatusCheckFilter prepares a new status check filter object

func (*StatusCheckFilter) GetAllRTTs added in v0.4.0 

func (filter *StatusCheckFilter) GetAllRTTs(showall bool)

GetAllRTTs asks for all RTTs to be returned

func (*StatusCheckFilter) MsmID added in v0.4.0 

func (filter *StatusCheckFilter) MsmID(id uint)

MsmID sets the measurement ID for which we ask the status check

func (*StatusCheckFilter) StatusCheck added in v0.4.0 

func (filter *StatusCheckFilter) StatusCheck(
	verbose bool,
	statuses chan AsyncStatusCheckResult,
)

StatusCheck returns a status check result

type StatusCheckProbe added in v0.4.0 

type StatusCheckProbe struct {
	Alert          bool       `json:"alert"`
	Last           float64    `json:"last"`
	LastPacketLoss float64    `json:"last_packet_loss"`
	Source         string     `json:"source"`
	AllRTTs        *[]float64 `json:"all"`
}

status check result for one probe

type StatusCheckResult added in v0.4.0 

type StatusCheckResult struct {
	GloblaAlert bool                      `json:"global_alert"`
	TotalAlerts uint                      `json:"total_alerts"`
	Probes      map[uint]StatusCheckProbe `json:"probes"`
}

status check result object, as it comes from the API

func (*StatusCheckResult) LongString added in v0.4.0 

func (sc *StatusCheckResult) LongString() string

LongString produces a longer textual description of the status

func (*StatusCheckResult) ShortString added in v0.4.0 

func (sc *StatusCheckResult) ShortString() string

ShortString produces a short textual description of the status

type Tag 

type Tag struct {
	Name string `json:"name"`
	Slug string `json:"slug"`
}

Tag type

type TlsOptions added in v0.4.0 

type TlsOptions struct {
	Port uint // API default: 443
	Sni  string
}

type TraceOptions added in v0.4.0 

type TraceOptions struct {
	Protocol        string // default: UDP
	ResponseTimeout uint   // API default: 4000 (ms)
	Packets         uint   // API default: 3
	PacketSize      uint   // API default: 48 bytes
	ParisId         uint   // API default: 16, default: 0
	FirstHop        uint   // API default: 1
	LastHop         uint   // API default: 32
	DestinationEH   uint   // API default: 0
	HopByHopEH      uint   // API default: 0
	DontFragment    bool   // API default: false
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.