checkers

package
v1.1.6 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2018 License: MIT Imports: 18 Imported by: 0

README

checkers

The health library comes with a number of built-in checkers for well known types of dependencies.

If a pre-built checker is not available, you can create your own checkers by implementing the ICheckable interface (which consists of a single method - Status() (interface{}, error)).

If you do create a custom-checker - consider opening a PR and adding it to the list of built-in checkers.

Built-in checkers

HTTP

The HTTP checker is a generic HTTP call executor. To make use of it, instantiate and fill out a HTTPConfig struct and pass it into checkers.NewHTTP(...).

The only required attribute is HTTPConfig.URL (*url.URL). Refer to the source code for all available attributes on the struct.

Redis

The Redis checker allows you to test that your server is either available (by ping), is able to set a value, is able to get a value or all of the above.

To make use of it, instantiate and fill out a RedisConfig struct and pass it to checkers.NewRedis(...).

The RedisConfig must contain a valid RedisAuthConfig and at least one check method (ping, set or get).

Refer to the godocs for additional info.

SQL DB

The SQL DB checker has implementations for the following interfaces:

  • SQLPinger, which encloses PingContext in sql.DB and sql.Conn

  • SQLQueryer, which encloses QueryContext in sql.DB, sql.Conn, sql.Stmt, and sql.Tx

  • SQLExecer, which encloses ExecContext in sql.DB, sql.Conn, sql.Stmt, and sql.Tx

    	#### SQLConfig
	The `SQLConfig` struct is required when using the SQL DB health check.  It **must** contain an inplementation of one of either `SQLPinger`, `SQLQueryer`, or `SQLExecer`.

	If `SQLQueryer` or `SQLExecer` are implemented, then `Query` must be valid (len > 0).

	Additionally, if `SQLQueryer` or `SQLExecer` are implemented, you have the option to also set either the `QueryerResultHandler` or `ExecerResultHandler` functions.  These functions allow you to evaluate the result of a query or exec operation.  If you choose not to implement these yourself, the default handlers are used.

	The default `ExecerResultHandler` is successful if the passed exec operation affected one and only one row.

	The default `QueryerResultHandler` is successful if the passed query operation returned one and only one row.

	#### SQLPinger

    Use the SQLPinger interface if your health check is only concerned with your application's database connectivity. All you need to do is set the Pinger value in your SQLConfig.

    	```golang
	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return err
	}

	sqlCheck, err := checkers.NewSQL(&checkers.SQLConfig{
		Pinger: db
	})
	if err != nil {
		return err
	}

	hc := health.New()
	healthCheck.AddCheck(&health.Config{
		Name:     "sql-check",
		Checker:  sqlCheck,
		Interval: time.Duration(3) * time.Second,
		Fatal:    true,
	})
	```

	#### SQLQueryer
	Use the `SQLQueryer` interface if your health check requires you to read rows from your database.  You can optionally supply a query result handler function.  If you don't supply one, the default function will be used.  The function signature for the handler is:

	```golang
	type SQLQueryerResultHandler func(rows *sql.Rows) (bool, error)
	```
	The default query handler returns true if there was exactly one row in the resultset:

	```golang
	func DefaultQueryHandler(rows *sql.Rows) (bool, error) {
		defer rows.Close()

		numRows := 0
		for rows.Next() {
			numRows++
		}

		return numRows == 1, nil
	}
	```
	**IMPORTANT**: Note that your query handler is responsible for closing the passed `*sql.Rows` value.

	Sample `SQLQueryer` implementation:

	```golang
	// this is our custom query row handler
	func myQueryHandler(rows *sql.Rows) (bool, error) {
		defer rows.Close()

		var healthValue string
		for rows.Next() {
			// this query will ever return at most one row
			if err := rows.Scan(&healthValue); err != nil {
				return false, err
			}
		}

		return healthValue == "ok", nil
	}

	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return err
	}

	// we pass the id we are looking for inside the params value
	sqlCheck, err := checkers.NewSQL(&checkers.SQLConfig{
		Queryerer:            db,
		Query:                "SELECT healthValue FROM some_table WHERE id = ?",
		Params:               []interface{}{1},
		QueryerResultHandler: myQueryHandler
	})
	if err != nil {
		return err
	}

	hc := health.New()
	healthCheck.AddCheck(&health.Config{
		Name:     "sql-check",
		Checker:  sqlCheck,
		Interval: time.Duration(3) * time.Second,
		Fatal:    true,
	})
	```

	#### SQLExecer
	Use the `SQLExecer` interface if your health check requires you to update or insert to your database.  You can optionally supply an exec result handler function.  If you don't supply one, the default function will be used.  The function signature for the handler is:

	```golang
	type SQLExecerResultHandler func(result sql.Result) (bool, error)
	```
	The default exec handler returns true if there was exactly one affected row:

	```golang
	func DefaultExecHandler(result sql.Result) (bool, error) {
		affectedRows, err := result.RowsAffected()
		if err != nil {
			return false, err
		}

		return affectedRows == int64(1), nil
	}
	```

	Sample `SQLExecer ` implementation:

	```golang
	// this is our custom exec result handler
	func myExecHandler(result sql.Result) (bool, error) {
		insertId, err := result.LastInsertId()
		if err != nil {
			return false, err
		}

		// for this example, a check isn't valid
		// until after the 100th iteration
		return insertId > int64(100), nil
	}

	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return err
	}

	sqlCheck, err := checkers.NewSQL(&checkers.SQLConfig{
		Execer:              db,
		Query:               "INSERT INTO checks (checkTS) VALUES (NOW())",
		ExecerResultHandler: myExecHandler
	})
	if err != nil {
		return err
	}

	hc := health.New()
	healthCheck.AddCheck(&health.Config{
		Name:     "sql-check",
		Checker:  sqlCheck,
		Interval: time.Duration(3) * time.Second,
		Fatal:    true,
	})
	```
Mongo

Planned, but PR's welcome!

Reachable

The reachable checker is a generic TCP/UDP checker. Use it to verify that a configured address can be contacted via a request over TCP or UDP. This is useful if you do not care about a response from the target and simply want to know if the URL is reachable.

The only required attribute is ReachableConfig.URL (*url.URL). Refer to the source code for all available attributes on the struct.

Documentation

Index

Constants

View Source 
const (
	// ReachableDDHealthErrors is the datadog name used when there is a failure in the reachable checker
	ReachableDDHealthErrors = "health.errors"
	// ReachableDefaultPort is the default port used if no port is defined in a reachable checker
	ReachableDefaultPort = "80"
	// ReachableDefaultNetwork is the default network used in the reachable checker
	ReachableDefaultNetwork = "tcp"
)
View Source 
const (
	DefaultDialTimeout = 10 * time.Second
)
View Source 
const (
	// MemcachedDefaultSetValue will be used if the "Set" check method is enabled
	// and "MemcachedSetOptions.Value" is _not_ set.
	MemcachedDefaultSetValue = "go-health/memcached-check"
)
View Source 
const (
	// RedisDefaultSetValue will be used if the "Set" check method is enabled
	// and "RedisSetOptions.Value" is _not_ set.
	RedisDefaultSetValue = "go-health/redis-check"
)

Variables

View Source 
var (
	// ReachableDefaultTimeout is the default timeout used when reachable is checking the URL
	ReachableDefaultTimeout = time.Duration(3) * time.Second
)

Functions

func DefaultExecHandler added in v1.0.2 

func DefaultExecHandler(result sql.Result) (bool, error)

DefaultExecHandler is the default SQLExecer result handler that assumes one row was affected in the passed query

func DefaultQueryHandler added in v1.0.2 

func DefaultQueryHandler(rows *sql.Rows) (bool, error)

DefaultQueryHandler is the default SQLQueryer result handler that assumes one row was returned from the passed query

Types

type DiskUsage added in v1.1.6 

type DiskUsage struct {
	Config *DiskUsageConfig
}

DiskUsage implements the "ICheckable" interface.

func NewDiskUsage added in v1.1.6 

func NewDiskUsage(cfg *DiskUsageConfig) (*DiskUsage, error)

func (*DiskUsage) Status added in v1.1.6 

func (d *DiskUsage) Status() (interface{}, error)

Status is used for performing a diskusage check against a dependency; it satisfies the "ICheckable" interface.

type DiskUsageConfig added in v1.1.6 

type DiskUsageConfig struct {
	Path              string
	WarningThreshold  float64
	CriticalThreshold float64
}

DiskUsageConfig is used for configuring the go-diskusage check.

"Path" is _required_; path to check directory/drive (ex. /home/user) "WarningThreshold" is _required_; set percent (more than 0 and less 100) of free space at specified path, 

which triggers warning.

"CriticalThreshold" is _required_; set percent (more than 0 and less 100) of free space at specified path, 

which triggers critical.

type HTTP 

type HTTP struct {
	Config *HTTPConfig
}

HTTP implements the "ICheckable" interface.

func NewHTTP 

func NewHTTP(cfg *HTTPConfig) (*HTTP, error)

NewHTTP creates a new HTTP checker that can be used for ".AddCheck(s)".

func (*HTTP) Status 

func (h *HTTP) Status() (interface{}, error)

Status is used for performing an HTTP check against a dependency; it satisfies the "ICheckable" interface.

type HTTPConfig 

type HTTPConfig struct {
	URL        *url.URL      // Required
	Method     string        // Optional (default GET)
	Payload    interface{}   // Optional
	StatusCode int           // Optional (default 200)
	Expect     string        // Optional
	Client     *http.Client  // Optional
	Timeout    time.Duration // Optional (default 3s)
}

HTTPConfig is used for configuring an HTTP check. The only required field is `URL`.

"Method" is optional and defaults to `GET` if undefined.

"Payload" is optional and can accept `string`, `[]byte` or will attempt to marshal the input to JSON for use w/ `bytes.NewReader()`.

"StatusCode" is optional and defaults to `200`.

"Expect" is optional; if defined, operates as a basic "body should contain <string>".

"Client" is optional; if undefined, a new client will be created using "Timeout".

"Timeout" is optional and defaults to "3s".

type Memcached added in v1.1.5 

type Memcached struct {
	Config *MemcachedConfig
	// contains filtered or unexported fields
}

func NewMemcached added in v1.1.5 

func NewMemcached(cfg *MemcachedConfig) (*Memcached, error)

func (*Memcached) Status added in v1.1.5 

func (mc *Memcached) Status() (interface{}, error)

type MemcachedClient added in v1.1.5 

type MemcachedClient interface {
	Get(key string) (item *memcache.Item, err error)
	Set(item *memcache.Item) error
}

type MemcachedClientWrapper added in v1.1.5 

type MemcachedClientWrapper struct {
	MemcachedClient
}

Used to simplify testing routines

func (MemcachedClientWrapper) GetClient added in v1.1.5 

func (mcw MemcachedClientWrapper) GetClient() MemcachedClient

type MemcachedConfig added in v1.1.5 

type MemcachedConfig struct {
	Url     string
	Timeout int32
	Ping    bool
	Set     *MemcachedSetOptions
	Get     *MemcachedGetOptions
}

MongoConfig is used for configuring the go-mongo check.

"Url" is _required_; memcached connection url, format is "10.0.0.1:11011". Port (:11011) is mandatory "Timeout" defines timeout for socket write/read (useful for servers hosted on different machine) "Ping" is optional; Ping establishes tcp connection to memcached server.

type MemcachedGetOptions added in v1.1.5 

type MemcachedGetOptions struct {
	Key               string
	Expect            []byte
	NoErrorMissingKey bool
}

MemcachedGetOptions contains attributes that can alter the behavior of the memcached "GET" check.

"Key" is _required_; the name of the key that we are attempting to "GET".

"Expect" is optional; optionally verify that the value for the key matches the Expect value.

"NoErrorMissingKey" is optional; by default, the "GET" check will error if the key we are fetching does not exist; flip this bool if that is normal/expected/ok.

type MemcachedSetOptions added in v1.1.5 

type MemcachedSetOptions struct {
	Key        string
	Value      string
	Expiration int32
}

MemcachedSetOptions contains attributes that can alter the behavior of the memcached "SET" check.

"Key" is _required_; the name of the key we are attempting to "SET".

"Value" is optional; what the value should hold; if not set, it will be set to "MemcachedDefaultSetValue".

"Expiration" is optional; if set, a TTL will be attached to the key.

type Mongo added in v1.1.4 

type Mongo struct {
	Config  *MongoConfig
	Session *mgo.Session
}

func NewMongo added in v1.1.4 

func NewMongo(cfg *MongoConfig) (*Mongo, error)

func (*Mongo) Status added in v1.1.4 

func (m *Mongo) Status() (interface{}, error)

type MongoAuthConfig added in v1.1.4 

type MongoAuthConfig struct {
	Url         string
	Credentials mgo.Credential
}

MongoAuthConfig, used to setup connection params for go-mongo check Url format is localhost:27017 or mongo://localhost:27017 Credential has format described at https://godoc.org/github.com/globalsign/mgo#Credential

type MongoConfig added in v1.1.4 

type MongoConfig struct {
	Auth        *MongoAuthConfig
	Collection  string
	DB          string
	Ping        bool
	DialTimeout time.Duration
}

MongoConfig is used for configuring the go-mongo check.

"Auth" is _required_; redis connection/auth config.

"Collection" is optional; method checks if collection exist

"Ping" is optional; Ping runs a trivial ping command just to get in touch with the server.

"DialTimeout" is optional; default @ 10s; determines the max time we'll wait to reach a server.

Note: At least _one_ check method must be set/enabled; you can also enable _all_ of the check methods (ie. perform a ping, or check particular collection for existense).

type ReachableChecker added in v1.1.2 

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

ReachableChecker checks that URL responds to a TCP request

func NewReachableChecker added in v1.1.2 

func NewReachableChecker(cfg *ReachableConfig) (*ReachableChecker, error)

NewReachableChecker creates a new reachable health checker

func (*ReachableChecker) Status added in v1.1.2 

func (r *ReachableChecker) Status() (interface{}, error)

Status checks if the endpoint is reachable

type ReachableConfig added in v1.1.2 

type ReachableConfig struct {
	URL           *url.URL                    // Required
	Dialer        ReachableDialer             // Optional (default net.DialTimeout)
	Timeout       time.Duration               // Optional (default 3s)
	Network       string                      // Optional (default tcp)
	DatadogClient ReachableDatadogIncrementer // Optional
	DatadogTags   []string                    // Optional
}

ReachableConfig is used for configuring an HTTP check. The only required field is `URL`.

"Dialer" is optional and defaults to using net.DialTimeout.

"Timeout" is optional and defaults to "3s".

"Network" is optional and defaults to "tcp"; it should be one of "tcp", "tcp4", "tcp6", "unix", "unixpacket", "udp", "udp4", "udp6", "unixgram" or an IP transport. The IP transports are "ip", "ip4", or "ip6" followed by a colon and a literal protocol number or a protocol name, as in "ip:1" or "ip:icmp".

"DatadogClient" is optional; if defined metrics will be sent via statsd.

"DatadogTags" is optional; defines the tags that are passed to datadog when there is a failure

type ReachableDatadogIncrementer added in v1.1.2 

type ReachableDatadogIncrementer interface {
	Incr(name string, tags []string, rate float64) error
}

ReachableDatadogIncrementer is any datadog client that has the Incr method for tracking metrics

type ReachableDialer added in v1.1.2 

type ReachableDialer func(network, address string, timeout time.Duration) (net.Conn, error)

ReachableDialer is the signature for a function that checks if an address is reachable

type Redis 

type Redis struct {
	Config *RedisConfig
	// contains filtered or unexported fields
}

Redis implements the ICheckable interface

func NewRedis 

func NewRedis(cfg *RedisConfig) (*Redis, error)

NewRedis creates a new "go-redis/redis" checker that can be used w/ "AddChecks()".

func (*Redis) Status 

func (r *Redis) Status() (interface{}, error)

Status is used for performing a redis check against a dependency; it satisfies the "ICheckable" interface.

type RedisAuthConfig 

type RedisAuthConfig struct {
	Addr     string // `host:port` format
	Password string // leave blank if no password
	DB       int    // leave unset if no specific db

	TLS *tls.Config // TLS config in case we are using in-transit encryption
}

RedisAuthConfig defines how to connect to redis.

type RedisConfig 

type RedisConfig struct {
	Auth *RedisAuthConfig
	Ping bool
	Set  *RedisSetOptions
	Get  *RedisGetOptions
}

RedisConfig is used for configuring the go-redis check.

"Auth" is _required_; redis connection/auth config.

"Ping" is optional; the most basic check method, performs a `.Ping()` on the client.

"Get" is optional; perform a "GET" on a key; refer to the "RedisGetOptions" docs for details.

"Set" is optional; perform a "SET" on a key; refer to the "RedisSetOptions" docs for details.

Note: At least _one_ check method must be set/enabled; you can also enable _all_ of the check methods (ie. perform a ping, set this key and now try to retrieve that key).

type RedisGetOptions 

type RedisGetOptions struct {
	Key               string
	Expect            string
	NoErrorMissingKey bool
}

RedisGetOptions contains attributes that can alter the behavior of the redis "GET" check.

"Key" is _required_; the name of the key that we are attempting to "GET".

"Expect" is optional; optionally verify that the value for the key matches the Expect value.

"NoErrorMissingKey" is optional; by default, the "GET" check will error if the key we are fetching does not exist; flip this bool if that is normal/expected/ok.

type RedisSetOptions 

type RedisSetOptions struct {
	Key        string
	Value      string
	Expiration time.Duration
}

RedisSetOptions contains attributes that can alter the behavior of the redis "SET" check.

"Key" is _required_; the name of the key we are attempting to "SET".

"Value" is optional; what the value should hold; if not set, it will be set to "RedisDefaultSetValue".

"Expiration" is optional; if set, a TTL will be attached to the key.

type SQL added in v1.0.2 

type SQL struct {
	Config *SQLConfig
}

SQL implements the "ICheckable" interface

func NewSQL added in v1.0.2 

func NewSQL(cfg *SQLConfig) (*SQL, error)

NewSQL creates a new database checker that can be used for ".AddCheck(s)".

func (*SQL) Status added in v1.0.2 

func (s *SQL) Status() (interface{}, error)

Status is used for performing a database ping against a dependency; it satisfies the "ICheckable" interface.

type SQLConfig added in v1.0.2 

type SQLConfig struct {
	// Pinger is the value implementing SQLPinger
	Pinger SQLPinger

	// Queryer is the value implementing SQLQueryer
	Queryer SQLQueryer

	// Execer is the value implementing SQLExecer
	Execer SQLExecer

	// Query is the parameterized SQL query required
	// with both Queryer and Execer
	Query string

	// Params are the SQL query parameters, if any
	Params []interface{}

	// QueryerResultHandler handles the result of
	// the QueryContext function
	QueryerResultHandler SQLQueryerResultHandler

	// ExecerResultHandler handles the result of
	// the ExecContext function
	ExecerResultHandler SQLExecerResultHandler
}

SQLConfig is used for configuring a database check. One of the Pinger, Queryer, or Execer fields is required.

If Execer is set, it will take precedence over Queryer and Pinger, Execer implements the SQLExecer interface in this package. The sql.DB and sql.TX structs both implement this interface.

Note that if the Execer is set, then the ExecerResultHandler and Query values MUST also be set

If Queryer is set, it will take precedence over Pinger. SQLQueryer implements the SQLQueryer interface in this package. The sql.DB and sql.TX structs both implement this interface.

Note that if the Queryer is set, then the QueryerResultHandler and Query values MUST also be set

Pinger implements the SQLPinger interface in this package. The sql.DB struct implements this interface.

type SQLExecer added in v1.0.2 

type SQLExecer interface {
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
}

SQLExecer is an interface that allows executing of queries in the database

type SQLExecerResultHandler added in v1.0.2 

type SQLExecerResultHandler func(result sql.Result) (bool, error)

SQLExecerResultHandler is the BYO function to handle a database exec result

type SQLPinger added in v1.0.2 

type SQLPinger interface {
	PingContext(ctx context.Context) error
}

SQLPinger is an interface that allows direct pinging of the database

type SQLQueryer added in v1.0.2 

type SQLQueryer interface {
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
}

SQLQueryer is an interface that allows querying of the database

type SQLQueryerResultHandler added in v1.0.2 

type SQLQueryerResultHandler func(rows *sql.Rows) (bool, error)

SQLQueryerResultHandler is the BYO function to handle the result of an SQL SELECT query

Source Files

View all Source files

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.