Moving probes to probers. Adding comments to prober.go

observer/mon_conf.go

@@ -5,7 +5,7 @@ import (
 	"strings"
 
 	"github.com/letsencrypt/boulder/cmd"
-	p "github.com/letsencrypt/boulder/observer/probes"
+	p "github.com/letsencrypt/boulder/observer/probers"
 	"gopkg.in/yaml.v2"
 )
 

observer/monitor.go

@@ -5,7 +5,7 @@ import (
 	"time"
 
 	blog "github.com/letsencrypt/boulder/log"
-	p "github.com/letsencrypt/boulder/observer/probes"
+	p "github.com/letsencrypt/boulder/observer/probers"
 	"github.com/prometheus/client_golang/prometheus"
 )
 
@@ -30,7 +30,7 @@ func (m monitor) start() *time.Ticker {
 		for {
 			select {
 			case <-ticker.C:
-				result, dur := m.prober.Do(m.period)
+				result, dur := m.prober.Probe(m.period)
 				statObservations.WithLabelValues(
 					m.prober.Name(), m.prober.Kind(), strconv.FormatBool(result)).
 					Observe(dur.Seconds())

observer/observer.go

@@ -7,8 +7,8 @@ import (
 	"github.com/letsencrypt/boulder/metrics"
 
 	// _ are probes imported to trigger init func
-	_ "github.com/letsencrypt/boulder/observer/probes/dns"
-	_ "github.com/letsencrypt/boulder/observer/probes/http"
+	_ "github.com/letsencrypt/boulder/observer/probers/dns"
+	_ "github.com/letsencrypt/boulder/observer/probers/http"
 	"github.com/prometheus/client_golang/prometheus"
 )
 

observer/probes/dns/dns.go → observer/probers/dns/dns.go

@@ -17,18 +17,20 @@ type DNSProbe struct {
 	QType   uint16
 }
 
-// Name returns a name that uniquely identifies the monitor
+// Name returns a name that uniquely identifies the monitor that
+// configured this `Prober`. Used for metrics and logging
 func (p DNSProbe) Name() string {
 	return fmt.Sprintf("%s-%s-%s-%s", p.Proto, p.Server, p.QName, dns.TypeToString[p.QType])
 }
 
-// Kind returns a name that uniquely identifies the prober
+// Kind returns a name that uniquely identifies the `Kind` of `Prober`.
+// Used for metrics and logging
 func (p DNSProbe) Kind() string {
 	return "DNS"
 }
 
-// Do is the query handler for HTTP probes
-func (p DNSProbe) Do(timeout time.Duration) (bool, time.Duration) {
+// Probe attempts the configured DNS query
+func (p DNSProbe) Probe(timeout time.Duration) (bool, time.Duration) {
 	m := new(dns.Msg)
 	m.SetQuestion(dns.Fqdn(p.QName), p.QType)
 	m.RecursionDesired = p.Recurse

observer/probes/dns/dns_conf.go → observer/probers/dns/dns_conf.go

@@ -7,7 +7,7 @@ import (
 	"strconv"
 	"strings"
 
-	p "github.com/letsencrypt/boulder/observer/probes"
+	p "github.com/letsencrypt/boulder/observer/probers"
 	"github.com/miekg/dns"
 	"gopkg.in/yaml.v2"
 )

observer/probes/http/http.go → observer/probers/http/http.go

@@ -18,13 +18,14 @@ func (p HTTPProbe) Name() string {
 	return fmt.Sprintf("%s-%d", p.URL, p.RCodes)
 }
 
-// Kind returns a name that uniquely identifies the prober
+// Kind returns a name that uniquely identifies the `Kind` of `Prober`.
+// Used for metrics and logging
 func (p HTTPProbe) Kind() string {
 	return "HTTP"
 }
 
-// expectedRCode returns true when `got` matches on in
-// `HTTPProbe.RCodes`, else returns false
+// expectedRCode returns true when `got` matches one in `p.RCodes`, else
+// returns false
 func (p HTTPProbe) expectedRCode(got int) bool {
 	for _, c := range p.RCodes {
 		if got == c {
@@ -34,8 +35,8 @@ func (p HTTPProbe) expectedRCode(got int) bool {
 	return false
 }
 
-// Do is the request handler for HTTP probes
-func (p HTTPProbe) Do(timeout time.Duration) (bool, time.Duration) {
+// Probe attempts the configured HTTP request
+func (p HTTPProbe) Probe(timeout time.Duration) (bool, time.Duration) {
 	client := http.Client{Timeout: timeout}
 	start := time.Now()
 	// TODO(@beautifulentropy): add support for more than HTTP GET

observer/probes/http/http_conf.go → observer/probers/http/http_conf.go

@@ -5,7 +5,7 @@ import (
 	"net/url"
 	"strings"
 
-	p "github.com/letsencrypt/boulder/observer/probes"
+	p "github.com/letsencrypt/boulder/observer/probers"
 	"gopkg.in/yaml.v2"
 )
 
@@ -41,16 +41,16 @@ func (c HTTPConf) Validate() error {
 	url, err := url.Parse(c.URL)
 	if err != nil {
 		return fmt.Errorf(
-			"invalid url, got: %q, expected a valid url", c.URL)
+			"invalid 'url', got: %q, expected a valid url", c.URL)
 	}
 	if url.Scheme == "" {
 		return fmt.Errorf(
-			"invalid url, got: %q, missing scheme", c.URL)
+			"invalid 'url', got: %q, missing scheme", c.URL)
 	}
 	// validate `rcodes`
 	if c.RCodes == nil {
 		return fmt.Errorf(
-			"invalid rcodes, got: %q, please specify at least one", c.RCodes)
+			"invalid 'rcodes', got: %q, please specify at least one", c.RCodes)
 	}
 	return nil
 }

observer/probes/prober.go → observer/probers/prober.go

@@ -14,24 +14,42 @@ var (
 	Registry = make(map[string]Configurer)
 )
 
-// Prober is the expected interface for Prober types
+// Prober is the interface for `Prober` types
 type Prober interface {
+
+	// Name returns a name that uniquely identifies the monitor that
+	// configured this `Prober`. Used for metrics and logging
 	Name() string
+
+	// Kind returns a name that uniquely identifies the `Kind` of
+	// `Prober`. Used for metrics and logging
 	Kind() string
-	Do(time.Duration) (bool, time.Duration)
+
+	// Probe attempts the configured request or query
+	Probe(time.Duration) (bool, time.Duration)
 }
 
-// Configurer is the expected interface for Configurer types
+// Configurer is the interface for `Configurer` types
 type Configurer interface {
+
+	// UnmarshalSettings unmarshals YAML as bytes to the fields of the
+	// bound struct
 	UnmarshalSettings([]byte) (Configurer, error)
+
+	// Validate ensures that the unmarshalled settings are valid and
+	// returns errors appropriate for operator consumption when this is
+	// not the case
 	Validate() error
+
+	// AsProbe should be called last and return a `Prober` object to be
+	// used by an `observer.monitor`
 	AsProbe() Prober
 }
 
 // Settings is exported as a temporary receiver for the `settings` field
-// of the yaml config. It's always marshaled back to bytes and then
-// unmarshalled into the `Configurer` specified by the `kind` field of
-// the `MonConf`
+// of the yaml config. `Settings` is always marshaled back to bytes and
+// then unmarshalled into the `Configurer` specified by the `kind` field
+// of the `MonConf`
 type Settings map[string]interface{}
 
 // GetProbeConf returns the probe configurer specified by name from