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)
- type DERPOpt
- type ForEachAddrOpts
- type Labels
- type Probe
- 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
- type 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) Wait()
- func (p *Prober) WithMetricNamespace(n string) *Prober
- func (p *Prober) WithOnce(s bool) *Prober
- func (p *Prober) WithSpread(s bool) *Prober
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type DERPOpt ¶ added in v1.62.0
type DERPOpt func(*derpProber)
func WithBandwidthProbing ¶ added in v1.62.0
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 ¶ added in v1.62.0
WithMeshProbing enables mesh probing. When enabled, a small message will be transferred through each DERP server and each pair of DERP servers.
func WithSTUNProbing ¶ added in v1.62.0
WithSTUNProbing enables STUN/UDP probing, with a STUN request being sent to each DERP server every `interval`.
func WithTLSProbing ¶ added in v1.62.0
WithTLSProbing enables TLS probing that will check TLS certificate on port 443 of each DERP server every `interval`.
type ForEachAddrOpts ¶ added in v1.64.0
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 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 ¶
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 in v1.40.0
func (p *Probe) Collect(ch chan<- prometheus.Metric)
Collect implements prometheus.Collector.
func (*Probe) Describe ¶ added in v1.40.0
func (p *Probe) Describe(ch chan<- *prometheus.Desc)
Describe implements prometheus.Collector.
type ProbeClass ¶ added in v1.64.0
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 ¶ added in v1.64.0
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.
Example ¶
This example demonstrates how to use ForEachAddr to create a TLS probe for each IP address in the DNS record of a given hostname.
package main import ( "context" "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(*hostname, netip.AddrPortFrom(addr, 443)) 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 == nil if sock != nil { sock.Close() } networks := []string{"ip4"} if supportsIPv6 { networks = append(networks, "ip6") } var vlogf logger.Logf = logger.Discard if *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 }, } }
Output:
func FuncProbe ¶ added in v1.64.0
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.
type Prober ¶
type Prober struct {
// contains filtered or unexported fields
}
a Prober manages a set of probes and keeps track of their results.
func (*Prober) Run ¶
Run executes probe class function every interval, and exports probe results under probeName.
Registering a probe under an already-registered name panics.
func (*Prober) Wait ¶ added in v1.38.0
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 ¶ added in v1.40.0
WithMetricNamespace allows changing metric name prefix from the default `prober`.
func (*Prober) WithOnce ¶ added in v1.38.0
WithOnce mode can be used if you want to run all configured probes once rather than on a schedule.
func (*Prober) WithSpread ¶ added in v1.34.0
WithSpread is used to enable random delay before the first run of each added probe.