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

func WithPageLink(text, urlstring) statusHandlerOpt

func WithProbeLink(textTpl, urlTplstring) statusHandlerOpt

func WithTitle(titlestring) statusHandlerOpt

type DERPOpt func(*derpProber)

funcWithBandwidthProbing¶added inv1.62.0

func WithBandwidthProbing(intervaltime.Duration, sizeint64, tunAddressstring)DERPOpt

WithBandwidthProbing enables bandwidth probing. When enabled, a payload of`size` bytes will be regularly transferred through each DERP server, and eachpair of DERP servers in every region. If tunAddress is specified, probes willuse a TCP connection over a TUN device at this address in order to exerciseTCP-in-TCP in similar fashion to TCP over Tailscale via DERP.

funcWithMeshKey¶added inv1.86.0

func WithMeshKey(meshKeykey.DERPMesh)DERPOpt

funcWithMeshProbing¶added inv1.62.0

func WithMeshProbing(intervaltime.Duration)DERPOpt

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

funcWithQueuingDelayProbing¶added inv1.80.0

func WithQueuingDelayProbing(qdPacketsPerSecondint, qdPacketTimeouttime.Duration)DERPOpt

WithQueuingDelayProbing enables/disables queuing delay probing. qdSendRateis the number of packets sent per second. qdTimeout is the amount of timeafter which a sent packet is considered to have timed out.

funcWithRegionCodeOrID¶added inv1.80.0

func WithRegionCodeOrID(regionCodestring)DERPOpt

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

funcWithSTUNProbing¶added inv1.62.0

func WithSTUNProbing(intervaltime.Duration)DERPOpt

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

funcWithTLSProbing¶added inv1.62.0

func WithTLSProbing(intervaltime.Duration)DERPOpt

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

type ForEachAddrOpts struct {// Logf is the logger to use for logging. If nil, no logging is done.Logflogger.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)}

type Labels map[string]string

func (Labels)With¶added inv1.64.0

func (lbLabels) With(k, vstring)Labels

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

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¶added inv1.40.0

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

Collect implements prometheus.Collector.

func (*Probe)Describe¶added inv1.40.0

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

Describe implements prometheus.Collector.

func (*Probe)IsContinuous¶added inv1.80.0

func (p *Probe) IsContinuous()bool

IsContinuous indicates that this is a continuous probe.

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.Classstring// Labels defines a set of metric labels that will be added to all metrics// exposed by this probe class.LabelsLabels// Timeout is the maximum time the probe function is allowed to run before// its context is cancelled. Defaults to 80% of the scheduling interval.Timeouttime.Duration// Concurrency is the maximum number of concurrent probe executions// allowed for this probe class. Defaults to 1.Concurrencyint// Metrics allows a probe class to export custom Metrics. Can be nil.Metrics func(prometheus.Labels) []prometheus.Metric}

funcForEachAddr¶added inv1.64.0

func ForEachAddr(hoststring, makeProbes func(netip.Addr) []*Probe, optsForEachAddrOpts)ProbeClass

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

package mainimport ("context""crypto/tls""flag""fmt""log""net""net/netip""os""os/signal""time""tailscale.com/prober""tailscale.com/types/logger")const (every30s = 30 * time.Second)var (hostname = flag.String("hostname", "tailscale.com", "hostname to probe")oneshot  = flag.Bool("oneshot", true, "run probes once and exit")verbose  = flag.Bool("verbose", false, "enable verbose logging"))// This example demonstrates how to use ForEachAddr to create a TLS probe for// each IP address in the DNS record of a given hostname.func main() {flag.Parse()p := prober.New().WithSpread(true)if *oneshot {p = p.WithOnce(true)}// This function is called every time we discover a new IP address to check.makeTLSProbe := func(addr netip.Addr) []*prober.Probe {pf := prober.TLSWithIP(netip.AddrPortFrom(addr, 443), &tls.Config{ServerName: *hostname})if *verbose {logger := logger.WithPrefix(log.Printf, fmt.Sprintf("[tls %s]: ", addr))pf = probeLogWrapper(logger, pf)}probe := p.Run(fmt.Sprintf("website/%s/tls", addr), every30s, nil, pf)return []*prober.Probe{probe}}// Determine whether to use IPv4 or IPv6 based on whether we can create// an IPv6 listening socket on localhost.sock, err := net.Listen("tcp", "[::1]:0")supportsIPv6 := err == nilif sock != nil {sock.Close()}networks := []string{"ip4"}if supportsIPv6 {networks = append(networks, "ip6")}var vlogf logger.Logf = logger.Discardif *verbose {vlogf = log.Printf}// This is the outer probe that resolves the hostname and creates a new// TLS probe for each IP.p.Run("website/dns", every30s, nil, prober.ForEachAddr(*hostname, makeTLSProbe, prober.ForEachAddrOpts{Logf:     vlogf,Networks: networks,}))defer log.Printf("done")// Wait until all probes have run if we're running in oneshot mode.if *oneshot {p.Wait()return}// Otherwise, wait until we get a signal.sigCh := make(chan os.Signal, 1)signal.Notify(sigCh, os.Interrupt)<-sigCh}func probeLogWrapper(logf logger.Logf, pc prober.ProbeClass) prober.ProbeClass {return prober.ProbeClass{Probe: func(ctx context.Context) error {logf("starting probe")err := pc.Probe(ctx)logf("probe finished with %v", err)return err},}}

funcFuncProbe¶added inv1.64.0

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

FuncProbe wraps a simple probe function in a ProbeClass.

funcHTTP¶

func HTTP(url, wantTextstring)ProbeClass

HTTP returns a ProbeClass that healthchecks an HTTP URL.

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

funcTCP¶

func TCP(addrstring)ProbeClass

TCP returns a Probe that healthchecks a TCP endpoint.

The ProbeFunc reports whether it can successfully connect to addr.

funcTLS¶

func TLS(hostPortstring, config *tls.Config)ProbeClass

TLS returns a Probe that healthchecks a TLS endpoint.

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

The TLS config is optional and may be nil.

funcTLSWithIP¶added inv1.62.0

func TLSWithIP(dialAddrnetip.AddrPort, config *tls.Config)ProbeClass

TLSWithIP is like TLS, but dials the provided dialAddr instead of using DNSresolution. Use config.ServerName to send SNI and validate the name in thecert.

type ProbeInfo struct {NamestringClassstringIntervaltime.DurationLabels          map[string]stringStarttime.TimeEndtime.TimeLatencytime.DurationStatusProbeStatusErrorstringRecentResults   []boolRecentLatencies []time.Duration}

func (ProbeInfo)Continuous¶added inv1.80.0

func (pbProbeInfo) Continuous()bool

func (ProbeInfo)RecentMedianLatency¶added inv1.72.0

func (pbProbeInfo) RecentMedianLatency()time.Duration

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

func (ProbeInfo)RecentSuccessRatio¶added inv1.72.0

func (pbProbeInfo) RecentSuccessRatio()float64

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

type ProbeStatusstring

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

funcNew¶

func New() *Prober

New returns a new Prober.

func (*Prober)ProbeInfo¶added inv1.38.0

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

ProbeInfo returns the state of all probes.

func (*Prober)Run¶

func (p *Prober) Run(namestring, intervaltime.Duration, labelsLabels, pcProbeClass) *Probe

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

If interval is negative, the probe will run continuously. If it encounters a failure whilerunning continuously, it will pause for -1*interval and then retry.

Registering a probe under an already-registered name panics.

func (*Prober)RunAllHandler¶added inv1.88.0

func (p *Prober) RunAllHandler(whttp.ResponseWriter, r *http.Request)error

func (*Prober)RunHandler¶added inv1.72.0

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

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

func (*Prober)StatusHandler¶added inv1.72.0

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¶added inv1.38.0

func (p *Prober) Wait()

Wait blocks until all probes have finished execution. It should typicallybe used with the `once` mode to wait for probes to finish before collectingtheir results.

func (*Prober)WithMetricNamespace¶added inv1.40.0

func (p *Prober) WithMetricNamespace(nstring) *Prober

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

func (*Prober)WithOnce¶added inv1.38.0

func (p *Prober) WithOnce(sbool) *Prober

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

func (*Prober)WithSpread¶added inv1.34.0

func (p *Prober) WithSpread(sbool) *Prober

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

type RunHandlerAllResponse struct {Results map[string]RunHandlerResponse}

type RunHandlerResponse struct {ProbeInfoProbeInfoPreviousSuccessRatiofloat64PreviousMedianLatencytime.Duration}