prober

Documentation

Overview

Package prober implements a simple blackbox prober. Each probe runs in its own goroutine, and run results are recorded as Prometheus metrics.

Index

• func DERP(p *Prober, derpMapURL string, opts ...DERPOpt) (*derpProber, error)
• func WithPageLink(text, url string) statusHandlerOpt
• func WithProbeLink(textTpl, urlTpl string) statusHandlerOpt
• func WithTitle(title string) statusHandlerOpt
• type DERPOpt
  • func WithBandwidthProbing(interval time.Duration, size int64) DERPOpt
  • func WithMeshProbing(interval time.Duration) DERPOpt
  • func WithRegion(regionCode string) DERPOpt
  • func WithSTUNProbing(interval time.Duration) DERPOpt
  • func WithTLSProbing(interval time.Duration) DERPOpt
• type ForEachAddrOpts
• type Labels
  • func (l Labels) With(k, v string) Labels
• type Probe
  • func (p *Probe) Close() error
  • func (p *Probe) Collect(ch chan<- prometheus.Metric)
  • func (p *Probe) Describe(ch chan<- *prometheus.Desc)
• type ProbeClass
  • func ForEachAddr(host string, makeProbes func(netip.Addr) []*Probe, opts ForEachAddrOpts) ProbeClass
  • func FuncProbe(fn func(context.Context) error) ProbeClass
  • func HTTP(url, wantText string) ProbeClass
  • func TCP(addr string) ProbeClass
  • func TLS(hostPort string) ProbeClass
  • func TLSWithIP(certDomain string, dialAddr netip.AddrPort) ProbeClass
• type ProbeInfo
  • func (pb ProbeInfo) RecentMedianLatency() time.Duration
  • func (pb ProbeInfo) RecentSuccessRatio() float64
• type Prober
  • func New() *Prober
  • func (p *Prober) ProbeInfo() map[string]ProbeInfo
  • func (p *Prober) Run(name string, interval time.Duration, labels Labels, pc ProbeClass) *Probe
  • func (p *Prober) RunHandler(w http.ResponseWriter, r *http.Request) error
  • func (p *Prober) StatusHandler(opts ...statusHandlerOpt) tsweb.ReturnHandlerFunc
  • func (p *Prober) Wait()
  • func (p *Prober) WithMetricNamespace(n string) *Prober
  • func (p *Prober) WithOnce(s bool) *Prober
  • func (p *Prober) WithSpread(s bool) *Prober
• type RunHandlerResponse

Functions

func DERP

func DERP(p *Prober, derpMapURL string, opts ...DERPOpt) (*derpProber, error)

DERP creates a new derpProber.

If derpMapURL is "local", the DERPMap is fetched via the local machine's tailscaled.

func WithPageLink

func WithPageLink(text, url string) statusHandlerOpt

WithPageLink adds a top-level link to the status page.

func WithProbeLink

func WithProbeLink(textTpl, urlTpl string) statusHandlerOpt

WithProbeLink adds a link to each probe on the status page. The textTpl and urlTpl are Go templates that will be rendered with the respective ProbeInfo struct as the data.

func WithTitle

func WithTitle(title string) statusHandlerOpt

WithTitle sets the title of the status page.

Types

type DERPOpt

type DERPOpt func(*derpProber)

func WithBandwidthProbing

func WithBandwidthProbing(interval time.Duration, size int64) DERPOpt

WithBandwidthProbing enables bandwidth probing. When enabled, a payload of `size` bytes will be regularly transferred through each DERP server, and each pair of DERP servers in every region.

func WithMeshProbing

func WithMeshProbing(interval time.Duration) DERPOpt

WithMeshProbing enables mesh probing. When enabled, a small message will be transferred through each DERP server and each pair of DERP servers.

func WithRegion

func WithRegion(regionCode string) DERPOpt

WithRegion restricts probing to the specified region identified by its code (e.g. "lax"). This is case sensitive.

func WithSTUNProbing

func WithSTUNProbing(interval time.Duration) DERPOpt

WithSTUNProbing enables STUN/UDP probing, with a STUN request being sent to each DERP server every `interval`.

func WithTLSProbing

func WithTLSProbing(interval time.Duration) DERPOpt

WithTLSProbing enables TLS probing that will check TLS certificate on port 443 of each DERP server every `interval`.

type ForEachAddrOpts

type ForEachAddrOpts struct {
	// Logf is the logger to use for logging. If nil, no logging is done.
	Logf logger.Logf
	// Networks is the list of networks to resolve; if non-empty, it should
	// contain at least one of "ip", "ip4", or "ip6".
	//
	// If empty, "ip" is assumed.
	Networks []string
	// LookupNetIP is the function to use to resolve the hostname to one or
	// more IP addresses.
	//
	// If nil, net.DefaultResolver.LookupNetIP is used.
	LookupNetIP func(context.Context, string, string) ([]netip.Addr, error)
}

ForEachAddrOpts contains options for ForEachAddr. The zero value for all fields is valid unless stated otherwise.

type Labels

type Labels map[string]string

Labels is a set of metric labels used by a prober.

func (Labels) With

func (l Labels) With(k, v string) Labels

type Probe

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

Probe is a probe that healthchecks something and updates Prometheus metrics with the results.

func (*Probe) Close

func (p *Probe) Close() error

Close shuts down the Probe and unregisters it from its Prober. It is safe to Run a new probe of the same name after Close returns.

func (*Probe) Collect

func (p *Probe) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*Probe) Describe

func (p *Probe) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

type ProbeClass

type ProbeClass struct {
	// Probe is a function that probes something and reports whether the Probe
	// succeeded. The provided context's deadline must be obeyed for correct
	// Probe scheduling.
	Probe func(context.Context) error

	// Class defines a user-facing name of the probe class that will be used
	// in the `class` metric label.
	Class string

	// Labels defines a set of metric labels that will be added to all metrics
	// exposed by this probe class.
	Labels Labels

	// Metrics allows a probe class to export custom Metrics. Can be nil.
	Metrics func(prometheus.Labels) []prometheus.Metric
}

ProbeClass defines a probe of a specific type: a probing function that will be regularly ran, and metric labels that will be added automatically to all probes using this class.

func ForEachAddr

func ForEachAddr(host string, makeProbes func(netip.Addr) []*Probe, opts ForEachAddrOpts) ProbeClass

ForEachAddr returns a Probe that resolves a given hostname into all available IP addresses, and then calls a function to create new Probes every time a new IP is discovered. The Probes returned will be closed if an IP address is no longer in the DNS record for the given hostname. This can be used to healthcheck every IP address that a hostname resolves to.

func FuncProbe

func FuncProbe(fn func(context.Context) error) ProbeClass

FuncProbe wraps a simple probe function in a ProbeClass.

func HTTP

func HTTP(url, wantText string) ProbeClass

HTTP returns a ProbeClass that healthchecks an HTTP URL.

The probe function sends a GET request for url, expects an HTTP 200 response, and verifies that want is present in the response body.

func TCP

func TCP(addr string) ProbeClass

TCP returns a Probe that healthchecks a TCP endpoint.

The ProbeFunc reports whether it can successfully connect to addr.

func TLS

func TLS(hostPort string) ProbeClass

TLS returns a Probe that healthchecks a TLS endpoint.

The ProbeFunc connects to a hostPort (host:port string), does a TLS handshake, verifies that the hostname matches the presented certificate, checks certificate validity time and OCSP revocation status.

func TLSWithIP

func TLSWithIP(certDomain string, dialAddr netip.AddrPort) ProbeClass

TLSWithIP is like TLS, but dials the provided dialAddr instead of using DNS resolution. The certDomain is the expected name in the cert (and the SNI name to send).

type ProbeInfo

type ProbeInfo struct {
	Name            string
	Class           string
	Interval        time.Duration
	Labels          map[string]string
	Start           time.Time
	End             time.Time
	Latency         time.Duration
	Result          bool
	Error           string
	RecentResults   []bool
	RecentLatencies []time.Duration
}

ProbeInfo is a snapshot of the configuration and state of a Probe.

func (ProbeInfo) RecentMedianLatency

func (pb ProbeInfo) RecentMedianLatency() time.Duration

RecentMedianLatency returns the median latency of the probe in the recent history.

func (ProbeInfo) RecentSuccessRatio

func (pb ProbeInfo) RecentSuccessRatio() float64

RecentSuccessRatio returns the success ratio of the probe in the recent history.

type Prober

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

a Prober manages a set of probes and keeps track of their results.

func New

func New() *Prober

New returns a new Prober.

func (*Prober) ProbeInfo

func (p *Prober) ProbeInfo() map[string]ProbeInfo

ProbeInfo returns the state of all probes.

func (*Prober) Run

func (p *Prober) Run(name string, interval time.Duration, labels Labels, pc ProbeClass) *Probe

Run executes probe class function every interval, and exports probe results under probeName.

Registering a probe under an already-registered name panics.

func (*Prober) RunHandler

func (p *Prober) RunHandler(w http.ResponseWriter, r *http.Request) error

RunHandler runs a probe by name and returns the result as an HTTP response.

func (*Prober) StatusHandler

func (p *Prober) StatusHandler(opts ...statusHandlerOpt) tsweb.ReturnHandlerFunc

StatusHandler is a handler for the probe overview HTTP endpoint. It shows a list of probes and their current status.

func (*Prober) Wait

func (p *Prober) Wait()

Wait blocks until all probes have finished execution. It should typically be used with the `once` mode to wait for probes to finish before collecting their results.

func (*Prober) WithMetricNamespace

func (p *Prober) WithMetricNamespace(n string) *Prober

WithMetricNamespace allows changing metric name prefix from the default `prober`.

func (*Prober) WithOnce

func (p *Prober) WithOnce(s bool) *Prober

WithOnce mode can be used if you want to run all configured probes once rather than on a schedule.

func (*Prober) WithSpread

func (p *Prober) WithSpread(s bool) *Prober

WithSpread is used to enable random delay before the first run of each added probe.

type RunHandlerResponse

type RunHandlerResponse struct {
	ProbeInfo             ProbeInfo
	PreviousSuccessRatio  float64
	PreviousMedianLatency time.Duration
}

RunHandlerResponse is the JSON response format for the RunHandler.