core

Documentation

Index

• Constants
• Variables
• type Condition
  • func (c Condition) Validate() error
• type ConditionResult
• type DNS
• type Endpoint
  • func (endpoint Endpoint) DisplayName() string
  • func (endpoint *Endpoint) EvaluateHealth() *Result
  • func (endpoint Endpoint) IsEnabled() bool
  • func (endpoint Endpoint) Key() string
  • func (endpoint Endpoint) Type() EndpointType
  • func (endpoint *Endpoint) ValidateAndSetDefaults() error
• type EndpointStatus
  • func NewEndpointStatus(group, name string) *EndpointStatus
• type EndpointType
• type Event
  • func NewEventFromResult(result *Result) *Event
• type EventType
• type HourlyUptimeStatistics
• type Result
  • func (r *Result) AddError(error string)
• type Uptime
  • func NewUptime() *Uptime

Constants

const (
	// StatusPlaceholder is a placeholder for a HTTP status.
	//
	// Values that could replace the placeholder: 200, 404, 500, ...
	StatusPlaceholder = "[STATUS]"

	// IPPlaceholder is a placeholder for an IP.
	//
	// Values that could replace the placeholder: 127.0.0.1, 10.0.0.1, ...
	IPPlaceholder = "[IP]"

	// DNSRCodePlaceholder is a placeholder for DNS_RCODE
	//
	// Values that could replace the placeholder: NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMP, REFUSED
	DNSRCodePlaceholder = "[DNS_RCODE]"

	// ResponseTimePlaceholder is a placeholder for the request response time, in milliseconds.
	//
	// Values that could replace the placeholder: 1, 500, 1000, ...
	ResponseTimePlaceholder = "[RESPONSE_TIME]"

	// BodyPlaceholder is a placeholder for the Body of the response
	//
	// Values that could replace the placeholder: {}, {"data":{"name":"john"}}, ...
	BodyPlaceholder = "[BODY]"

	// ConnectedPlaceholder is a placeholder for whether a connection was successfully established.
	//
	// Values that could replace the placeholder: true, false
	ConnectedPlaceholder = "[CONNECTED]"

	// CertificateExpirationPlaceholder is a placeholder for the duration before certificate expiration, in milliseconds.
	//
	// Values that could replace the placeholder: 4461677039 (~52 days)
	CertificateExpirationPlaceholder = "[CERTIFICATE_EXPIRATION]"

	// DomainExpirationPlaceholder is a placeholder for the duration before the domain expires, in milliseconds.
	DomainExpirationPlaceholder = "[DOMAIN_EXPIRATION]"
)

Placeholders

const (
	// LengthFunctionPrefix is the prefix for the length function
	//
	// Usage: len([BODY].articles) == 10, len([BODY].name) > 5
	LengthFunctionPrefix = "len("

	// HasFunctionPrefix is the prefix for the has function
	//
	// Usage: has([BODY].errors) == true
	HasFunctionPrefix = "has("

	// PatternFunctionPrefix is the prefix for the pattern function
	//
	// Usage: [IP] == pat(192.168.*.*)
	PatternFunctionPrefix = "pat("

	// AnyFunctionPrefix is the prefix for the any function
	//
	// Usage: [IP] == any(1.1.1.1, 1.0.0.1)
	AnyFunctionPrefix = "any("

	// FunctionSuffix is the suffix for all functions
	FunctionSuffix = ")"
)

Functions

const (
	// InvalidConditionElementSuffix is the suffix that will be appended to an invalid condition
	InvalidConditionElementSuffix = "(INVALID)"
)

Other constants

Variables

var (
	// ErrDNSWithNoQueryName is the error with which gatus will panic if a dns is configured without query name
	ErrDNSWithNoQueryName = errors.New("you must specify a query name for DNS")

	// ErrDNSWithInvalidQueryType is the error with which gatus will panic if a dns is configured with invalid query type
	ErrDNSWithInvalidQueryType = errors.New("invalid query type")
)

var (
	// ErrEndpointWithNoCondition is the error with which Gatus will panic if an endpoint is configured with no conditions
	ErrEndpointWithNoCondition = errors.New("you must specify at least one condition per endpoint")

	// ErrEndpointWithNoURL is the error with which Gatus will panic if an endpoint is configured with no url
	ErrEndpointWithNoURL = errors.New("you must specify an url for each endpoint")

	// ErrEndpointWithNoName is the error with which Gatus will panic if an endpoint is configured with no name
	ErrEndpointWithNoName = errors.New("you must specify a name for each endpoint")

	// ErrEndpointWithInvalidNameOrGroup is the error with which Gatus will panic if an endpoint has an invalid character where it shouldn't
	ErrEndpointWithInvalidNameOrGroup = errors.New("endpoint name and group must not have \" or \\")

	// ErrUnknownEndpointType is the error with which Gatus will panic if an endpoint has an unknown type
	ErrUnknownEndpointType = errors.New("unknown endpoint type")

	// ErrInvalidConditionFormat is the error with which Gatus will panic if a condition has an invalid format
	ErrInvalidConditionFormat = errors.New("invalid condition format: does not match '<VALUE> <COMPARATOR> <VALUE>'")

	// ErrInvalidEndpointIntervalForDomainExpirationPlaceholder is the error with which Gatus will panic if an endpoint
	// has both an interval smaller than 5 minutes and a condition with DomainExpirationPlaceholder.
	// This is because the free whois service we are using should not be abused, especially considering the fact that
	// the data takes a while to be updated.
	ErrInvalidEndpointIntervalForDomainExpirationPlaceholder = errors.New("the minimum interval for an endpoint with a condition using the " + DomainExpirationPlaceholder + " placeholder is 300s (5m)")
)

Types

type Condition

type Condition string

Condition is a condition that needs to be met in order for an Endpoint to be considered healthy.

func (Condition) Validate

func (c Condition) Validate() error

Validate checks if the Condition is valid

type ConditionResult

type ConditionResult struct {
	// Condition that was evaluated
	Condition string `json:"condition"`

	// Success whether the condition was met (successful) or not (failed)
	Success bool `json:"success"`
}

ConditionResult result of a Condition

type DNS

type DNS struct {
	// QueryType is the type for the DNS records like A, AAAA, CNAME...
	QueryType string `yaml:"query-type"`

	// QueryName is the query for DNS
	QueryName string `yaml:"query-name"`
}

DNS is the configuration for a Endpoint of type DNS

type Endpoint

type Endpoint struct {
	// Enabled defines whether to enable the monitoring of the endpoint
	Enabled *bool `yaml:"enabled,omitempty"`

	// Name of the endpoint. Can be anything.
	Name string `yaml:"name"`

	// Group the endpoint is a part of. Used for grouping multiple endpoints together on the front end.
	Group string `yaml:"group,omitempty"`

	// URL to send the request to
	URL string `yaml:"url"`

	// DNS is the configuration of DNS monitoring
	DNS *DNS `yaml:"dns,omitempty"`

	// Method of the request made to the url of the endpoint
	Method string `yaml:"method,omitempty"`

	// Body of the request
	Body string `yaml:"body,omitempty"`

	// GraphQL is whether to wrap the body in a query param ({"query":"$body"})
	GraphQL bool `yaml:"graphql,omitempty"`

	// Headers of the request
	Headers map[string]string `yaml:"headers,omitempty"`

	// Interval is the duration to wait between every status check
	Interval time.Duration `yaml:"interval,omitempty"`

	// Conditions used to determine the health of the endpoint
	Conditions []Condition `yaml:"conditions"`

	// Alerts is the alerting configuration for the endpoint in case of failure
	Alerts []*alert.Alert `yaml:"alerts,omitempty"`

	// ClientConfig is the configuration of the client used to communicate with the endpoint's target
	ClientConfig *client.Config `yaml:"client,omitempty"`

	// UIConfig is the configuration for the UI
	UIConfig *ui.Config `yaml:"ui,omitempty"`

	// NumberOfFailuresInARow is the number of unsuccessful evaluations in a row
	NumberOfFailuresInARow int `yaml:"-"`

	// NumberOfSuccessesInARow is the number of successful evaluations in a row
	NumberOfSuccessesInARow int `yaml:"-"`
}

Endpoint is the configuration of a monitored

func (Endpoint) DisplayName

func (endpoint Endpoint) DisplayName() string

DisplayName returns an identifier made up of the Name and, if not empty, the Group.

func (*Endpoint) EvaluateHealth

func (endpoint *Endpoint) EvaluateHealth() *Result

EvaluateHealth sends a request to the endpoint's URL and evaluates the conditions of the endpoint.

func (Endpoint) IsEnabled

func (endpoint Endpoint) IsEnabled() bool

IsEnabled returns whether the endpoint is enabled or not

func (Endpoint) Key

func (endpoint Endpoint) Key() string

Key returns the unique key for the Endpoint

func (Endpoint) Type

func (endpoint Endpoint) Type() EndpointType

Type returns the endpoint type

func (*Endpoint) ValidateAndSetDefaults

func (endpoint *Endpoint) ValidateAndSetDefaults() error

ValidateAndSetDefaults validates the endpoint's configuration and sets the default value of args that have one

type EndpointStatus

type EndpointStatus struct {
	// Name of the endpoint
	Name string `json:"name,omitempty"`

	// Group the endpoint is a part of. Used for grouping multiple endpoints together on the front end.
	Group string `json:"group,omitempty"`

	// Key is the key representing the EndpointStatus
	Key string `json:"key"`

	// Results is the list of endpoint evaluation results
	Results []*Result `json:"results"`

	// Events is a list of events
	Events []*Event `json:"events,omitempty"`

	// Uptime information on the endpoint's uptime
	//
	// Used by the memory store.
	//
	// To retrieve the uptime between two time, use store.GetUptimeByKey.
	Uptime *Uptime `json:"-"`
}

EndpointStatus contains the evaluation Results of an Endpoint

func NewEndpointStatus

func NewEndpointStatus(group, name string) *EndpointStatus

NewEndpointStatus creates a new EndpointStatus

type EndpointType

type EndpointType string

const (
	// HostHeader is the name of the header used to specify the host
	HostHeader = "Host"

	// ContentTypeHeader is the name of the header used to specify the content type
	ContentTypeHeader = "Content-Type"

	// UserAgentHeader is the name of the header used to specify the request's user agent
	UserAgentHeader = "User-Agent"

	// GatusUserAgent is the default user agent that Gatus uses to send requests.
	GatusUserAgent = "Gatus/1.0"

	EndpointTypeDNS      EndpointType = "DNS"
	EndpointTypeTCP      EndpointType = "TCP"
	EndpointTypeSCTP     EndpointType = "SCTP"
	EndpointTypeUDP      EndpointType = "UDP"
	EndpointTypeICMP     EndpointType = "ICMP"
	EndpointTypeSTARTTLS EndpointType = "STARTTLS"
	EndpointTypeTLS      EndpointType = "TLS"
	EndpointTypeHTTP     EndpointType = "HTTP"
	EndpointTypeUNKNOWN  EndpointType = "UNKNOWN"
)

type Event

type Event struct {
	// Type is the kind of event
	Type EventType `json:"type"`

	// Timestamp is the moment at which the event happened
	Timestamp time.Time `json:"timestamp"`
}

Event is something that happens at a specific time

func NewEventFromResult

func NewEventFromResult(result *Result) *Event

NewEventFromResult creates an Event from a Result

type EventType

type EventType string

EventType is, uh, the types of events?

var (
	// EventStart is a type of event that represents when an endpoint starts being monitored
	EventStart EventType = "START"

	// EventHealthy is a type of event that represents an endpoint passing all of its conditions
	EventHealthy EventType = "HEALTHY"

	// EventUnhealthy is a type of event that represents an endpoint failing one or more of its conditions
	EventUnhealthy EventType = "UNHEALTHY"
)

type HourlyUptimeStatistics

type HourlyUptimeStatistics struct {
	TotalExecutions             uint64 // Total number of checks
	SuccessfulExecutions        uint64 // Number of successful executions
	TotalExecutionsResponseTime uint64 // Total response time for all executions in milliseconds
}

HourlyUptimeStatistics is a struct containing all metrics collected over the course of an hour

type Result

type Result struct {
	// HTTPStatus is the HTTP response status code
	HTTPStatus int `json:"status"`

	// DNSRCode is the response code of a DNS query in a human-readable format
	//
	// Possible values: NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMP, REFUSED
	DNSRCode string `json:"-"`

	// Hostname extracted from Endpoint.URL
	Hostname string `json:"hostname,omitempty"`

	// IP resolved from the Endpoint URL
	IP string `json:"-"`

	// Connected whether a connection to the host was established successfully
	Connected bool `json:"-"`

	// Duration time that the request took
	Duration time.Duration `json:"duration"`

	// Errors encountered during the evaluation of the Endpoint's health
	Errors []string `json:"errors,omitempty"`

	// ConditionResults results of the Endpoint's conditions
	ConditionResults []*ConditionResult `json:"conditionResults"`

	// Success whether the result signifies a success or not
	Success bool `json:"success"`

	// Timestamp when the request was sent
	Timestamp time.Time `json:"timestamp"`

	// CertificateExpiration is the duration before the certificate expires
	CertificateExpiration time.Duration `json:"-"`

	// DomainExpiration is the duration before the domain expires
	DomainExpiration time.Duration `json:"-"`

	// Body is the response body
	//
	// Note that this field is not persisted in the storage.
	// It is used for health evaluation as well as debugging purposes.
	Body []byte `json:"-"`
}

Result of the evaluation of a Endpoint

func (*Result) AddError

func (r *Result) AddError(error string)

AddError adds an error to the result's list of errors. It also ensures that there are no duplicates.

type Uptime

type Uptime struct {
	// HourlyStatistics is a map containing metrics collected (value) for every hourly unix timestamps (key)
	//
	// Used only if the storage type is memory
	HourlyStatistics map[int64]*HourlyUptimeStatistics `json:"-"`
}

Uptime is the struct that contains the relevant data for calculating the uptime as well as the uptime itself and some other statistics

func NewUptime

func NewUptime() *Uptime

NewUptime creates a new Uptime