core

Documentation

Index

• Constants
• Variables
• type Alert
• type AlertType
• type Condition
• type ConditionResult
• type DNS
• type HealthStatus
• type Result
• type Service
  • func (service *Service) EvaluateHealth() *Result
  • func (service *Service) GetAlertsTriggered() []Alert
  • func (service *Service) ValidateAndSetDefaults()
• type ServiceStatus
  • func NewServiceStatus(service *Service) *ServiceStatus
  • func (ss *ServiceStatus) AddResult(result *Result)

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 place holder for DNS_RCODE
	//
	// Values that could be NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMP and 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]"

	// LengthFunctionPrefix is the prefix for the length function
	LengthFunctionPrefix = "len("

	// PatternFunctionPrefix is the prefix for the pattern function
	PatternFunctionPrefix = "pat("

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

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

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 (
	// ErrServiceWithNoCondition is the error with which gatus will panic if a service is configured with no conditions
	ErrServiceWithNoCondition = errors.New("you must specify at least one condition per service")

	// ErrServiceWithNoURL is the error with which gatus will panic if a service is configured with no url
	ErrServiceWithNoURL = errors.New("you must specify an url for each service")

	// ErrServiceWithNoName is the error with which gatus will panic if a service is configured with no name
	ErrServiceWithNoName = errors.New("you must specify a name for each service")
)

Types

type Alert

type Alert struct {
	// Type of alert
	Type AlertType `yaml:"type"`

	// Enabled defines whether or not the alert is enabled
	Enabled bool `yaml:"enabled"`

	// FailureThreshold is the number of failures in a row needed before triggering the alert
	FailureThreshold int `yaml:"failure-threshold"`

	// Description of the alert. Will be included in the alert sent.
	Description string `yaml:"description"`

	// SendOnResolved defines whether to send a second notification when the issue has been resolved
	SendOnResolved bool `yaml:"send-on-resolved"`

	// SuccessThreshold defines how many successful executions must happen in a row before an ongoing incident is marked as resolved
	SuccessThreshold int `yaml:"success-threshold"`

	// ResolveKey is an optional field that is used by some providers (i.e. PagerDuty's dedup_key) to resolve
	// ongoing/triggered incidents
	ResolveKey string

	// Triggered is used to determine whether an alert has been triggered. When an alert is resolved, this value
	// should be set back to false. It is used to prevent the same alert from going out twice.
	Triggered bool
}

Alert is the service's alert configuration

type AlertType

type AlertType string

AlertType is the type of the alert. The value will generally be the name of the alert provider

const (
	// SlackAlert is the AlertType for the slack alerting provider
	SlackAlert AlertType = "slack"

	// MattermostAlert is the AlertType for the mattermost alerting provider
	MattermostAlert AlertType = "mattermost"

	// MessagebirdAlert is the AlertType for the messagebird alerting provider
	MessagebirdAlert AlertType = "messagebird"

	// PagerDutyAlert is the AlertType for the pagerduty alerting provider
	PagerDutyAlert AlertType = "pagerduty"

	// TwilioAlert is the AlertType for the twilio alerting provider
	TwilioAlert AlertType = "twilio"

	// CustomAlert is the AlertType for the custom alerting provider
	CustomAlert AlertType = "custom"
)

type Condition

type Condition string

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

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 Service of type DNS

type HealthStatus

type HealthStatus struct {
	// Status is the state of Gatus (UP/DOWN)
	Status string `json:"status"`

	// Message is an accompanying description of why the status is as reported.
	// If the Status is UP, no message will be provided
	Message string `json:"message,omitempty"`
}

HealthStatus is the status of Gatus

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
	DNSRCode string `json:"-"`

	// Body is the response body
	Body []byte `json:"-"`

	// Hostname extracted from the Service URL
	Hostname string `json:"hostname"`

	// IP resolved from the Service 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 service's health
	Errors []string `json:"errors"`

	// ConditionResults results of the service's conditions
	ConditionResults []*ConditionResult `json:"condition-results"`

	// 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:"-"`
}

Result of the evaluation of a Service

type Service

type Service struct {
	// Name of the service. Can be anything.
	Name string `yaml:"name"`

	// Group the service is a part of. Used for grouping multiple services 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 service
	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 service
	Conditions []*Condition `yaml:"conditions"`

	// Alerts is the alerting configuration for the service in case of failure
	Alerts []*Alert `yaml:"alerts"`

	// Insecure is whether to skip verifying the server's certificate chain and host name
	Insecure bool `yaml:"insecure,omitempty"`

	// NumberOfFailuresInARow is the number of unsuccessful evaluations in a row
	NumberOfFailuresInARow int

	// NumberOfFailuresInARow is the number of successful evaluations in a row
	NumberOfSuccessesInARow int
}

Service is the configuration of a monitored endpoint

func (*Service) EvaluateHealth

func (service *Service) EvaluateHealth() *Result

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

func (*Service) GetAlertsTriggered

func (service *Service) GetAlertsTriggered() []Alert

GetAlertsTriggered returns a slice of alerts that have been triggered

func (*Service) ValidateAndSetDefaults

func (service *Service) ValidateAndSetDefaults()

ValidateAndSetDefaults validates the service's configuration and sets the default value of fields that have one

type ServiceStatus

type ServiceStatus struct {
	// Name of the service
	Name string `json:"name,omitempty"`

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

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

ServiceStatus contains the evaluation Results of a Service

func NewServiceStatus

func NewServiceStatus(service *Service) *ServiceStatus

NewServiceStatus creates a new ServiceStatus

func (*ServiceStatus) AddResult

func (ss *ServiceStatus) AddResult(result *Result)

AddResult adds a Result to ServiceStatus.Results and makes sure that there are no more than 20 results in the Results slice