core

Documentation

Index

• Constants
• Variables
• type Condition
• type ConditionResult
• type DNS
• type Event
  • func NewEventFromResult(result *Result) *Event
• type EventType
• type HealthStatus
• type HourlyUptimeStatistics
• type Result
  • func (r *Result) AddError(error string)
• type Service
  • func (service *Service) EvaluateHealth() *Result
  • func (service Service) IsEnabled() bool
  • func (service Service) Key() string
  • func (service *Service) ValidateAndSetDefaults() error
• type ServiceStatus
  • func NewServiceStatus(serviceKey, serviceGroup, serviceName string) *ServiceStatus
• 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 place holder 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]"

	// 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 = ")"

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

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"
)

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 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 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 a service starts being monitored
	EventStart EventType = "START"

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

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

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

	// Hostname extracted from 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:"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:"-"`
	// contains filtered or unexported fields
}

Result of the evaluation of a Service

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 Service

type Service struct {
	// Enabled defines whether to enable the service
	Enabled *bool `yaml:"enabled,omitempty"`

	// 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.Alert `yaml:"alerts"`

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

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

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

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

Service is the configuration of a monitored endpoint XXX: Rename this to Endpoint in v4.0.0?

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) IsEnabled

func (service Service) IsEnabled() bool

IsEnabled returns whether the service is enabled or not

func (Service) Key

func (service Service) Key() string

Key returns the unique key for the Service

func (*Service) ValidateAndSetDefaults

func (service *Service) ValidateAndSetDefaults() error

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"`

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

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

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

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

ServiceStatus contains the evaluation Results of a Service

func NewServiceStatus

func NewServiceStatus(serviceKey, serviceGroup, serviceName string) *ServiceStatus

NewServiceStatus creates a new ServiceStatus

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