gatus README

The project's README from github.com/TwiN/gatus. As one markdown file: README.md.

Gatus

test Go Report Card Go version Docker pulls Follow TwiN

Gatus is a developer-oriented health dashboard that gives you the ability to monitor your services using HTTP, ICMP, TCP, and even DNS queries as well as evaluate the result of said queries by using a list of conditions on values like the status code, the response time, the certificate expiration, the body and many others. The icing on top is that each of these health checks can be paired with alerting via Slack, Teams, PagerDuty, Discord, Twilio and many more.

I personally deploy it in my Kubernetes cluster and let it monitor the status of my core applications: https://status.twin.sh/

Looking for a managed solution? Check out Gatus.io.

Quick start 
docker run -p 8080:8080 --name gatus ghcr.io/twin/gatus:stable

You can also use Docker Hub if you prefer:

docker run -p 8080:8080 --name gatus twinproduction/gatus:stable

For more details, see Usage

❤ Like this project? Please consider sponsoring me.

Gatus dashboard

Have any feedback or questions? Create a discussion.

Table of Contents

Why Gatus?

Before getting into the specifics, I want to address the most common question:

Why would I use Gatus when I can just use Prometheus’ Alertmanager, Cloudwatch or even Splunk?

Neither of these can tell you that there’s a problem if there are no clients actively calling the endpoint. In other words, it's because monitoring metrics mostly rely on existing traffic, which effectively means that unless your clients are already experiencing a problem, you won't be notified.

Gatus, on the other hand, allows you to configure health checks for each of your features, which in turn allows it to monitor these features and potentially alert you before any clients are impacted.

A sign you may want to look into Gatus is by simply asking yourself whether you'd receive an alert if your load balancer was to go down right now. Will any of your existing alerts be triggered? Your metrics won’t report an increase in errors if no traffic makes it to your applications. This puts you in a situation where your clients are the ones that will notify you about the degradation of your services rather than you reassuring them that you're working on fixing the issue before they even know about it.

Features

The main features of Gatus are:

Gatus dashboard conditions

Usage

docker run -p 8080:8080 --name gatus ghcr.io/twin/gatus:stable

You can also use Docker Hub if you prefer:

docker run -p 8080:8080 --name gatus twinproduction/gatus:stable

If you want to create your own configuration, see Docker for information on how to mount a configuration file.

Here's a simple example:

endpoints:
  - name: website                 # Name of your endpoint, can be anything
    url: "https://twin.sh/health"
    interval: 5m                  # Duration to wait between every status check (default: 60s)
    conditions:
      - "[STATUS] == 200"         # Status must be 200
      - "[BODY].status == UP"     # The json path "$.status" must be equal to UP
      - "[RESPONSE_TIME] < 300"   # Response time must be under 300ms

  - name: make-sure-header-is-rendered
    url: "https://example.org/"
    interval: 60s
    conditions:
      - "[STATUS] == 200"                          # Status must be 200
      - "[BODY] == pat(*<h1>Example Domain</h1>*)" # Body must contain the specified header

This example would look similar to this:

Simple example

If you want to test it locally, see Docker.

Configuration

By default, the configuration file is expected to be at config/config.yaml.

You can specify a custom path by setting the GATUS_CONFIG_PATH environment variable.

If GATUS_CONFIG_PATH points to a directory, all *.yaml and *.yml files inside said directory and its subdirectories are merged like so:

💡 You can also use environment variables in the configuration file (e.g. $DOMAIN, ${DOMAIN})

⚠️ When your configuration parameter contains a $ symbol, you have to escape $ with $$.

See Use environment variables in config files or examples/docker-compose-postgres-storage/config/config.yaml for examples.

If you want to test it locally, see Docker.

Configuration

Parameter Description Default
metrics Whether to expose metrics at /metrics. false
storage Storage configuration. {}
alerting Alerting configuration. {}
announcements Announcements configuration. []
endpoints Endpoints configuration. Required []
external-endpoints External Endpoints configuration. []
security Security configuration. {}
concurrency Maximum number of endpoints/suites to monitor concurrently. Set to 0 for unlimited. See Concurrency. 3
disable-monitoring-lock Whether to disable the monitoring lock. Deprecated: Use concurrency: 0 instead. false
skip-invalid-config-update Whether to ignore invalid configuration update.
See Reloading configuration on the fly.		 false
web Web configuration. {}
ui UI configuration. {}
maintenance Maintenance configuration. {}

If you want more verbose logging, you may set the GATUS_LOG_LEVEL environment variable to DEBUG. Conversely, if you want less verbose logging, you can set the aforementioned environment variable to WARN, ERROR or FATAL. The default value for GATUS_LOG_LEVEL is INFO.

Endpoints

Endpoints are URLs, applications, or services that you want to monitor. Each endpoint has a list of conditions that are evaluated on an interval that you define. If any condition fails, the endpoint is considered as unhealthy. You can then configure alerts to be triggered when an endpoint is unhealthy once a certain threshold is reached.

Parameter Description Default
endpoints List of endpoints to monitor. Required []
endpoints[].enabled Whether to monitor the endpoint. true
endpoints[].name Name of the endpoint. Can be anything. Required ""
endpoints[].group Group name. Used to group multiple endpoints together on the dashboard.
See Endpoint groups.		 ""
endpoints[].url URL to send the request to. Required ""
endpoints[].method Request method. GET
endpoints[].conditions Conditions used to determine the health of the endpoint.
See Conditions.		 []
endpoints[].interval Duration to wait between every status check. 60s
endpoints[].graphql Whether to wrap the body in a query param ({"query":"$body"}). false
endpoints[].body Request body. ""
endpoints[].headers Request headers. {}
endpoints[].dns Configuration for an endpoint

gatus (TwiN/gatus)

Searching Database…

12.3K ·GitHub
Gatus
What is this?Gatus is an open-source, developer-oriented status page and health dashboard: it actively probes your services over HTTP, TCP, ICMP or DNS, shows the results on a web dashboard, and can alert you when checks fail.
How is this different from Prometheus Alertmanager or Cloudwatch alerts?Metric-based alerting relies on existing traffic, so nothing fires if no client is calling the failing service. Gatus runs its own scheduled health checks, so it can alert you before your users notice an outage.
How do I get it running?Run the Docker image (docker run -p 8080:8080 twinproduction/gatus) and mount your config file. Helm chart, Terraform, Kubernetes manifests and a plain binary install are also documented. Config is read from config/config.yaml by default.
What does configuring a health check look like?Just YAML: each endpoint gets a name, a URL, a method, an interval and a list of conditions on values like status code, response time, response body or certificate expiration. No agent is installed on the monitored services.
Anything still experimental or deprecated I should know about?Yes — Suites are marked ALPHA, remote instances are EXPERIMENTAL, and the old Teams alerting is deprecated in favor of Teams Workflow alerts. Config files are also strict: a primitive parameter defined twice across merged files is rejected.
Is this built for ops teams or solo developers?Developer-oriented by design: the author runs it in his own Kubernetes cluster to watch core applications, and deployments range from a single Docker container to Helm and Terraform — a fit for anyone self-hosting services.
Does it phone home or send my data anywhere?It is fully self-hosted: checks run from wherever you deploy it and results stay in your own storage (a docker-compose example for PostgreSQL is included). Sensitive config values can be injected via environment variables; a managed alternative exists at Gatus.io.
What can it check besides plain HTTP URLs?Beyond HTTP/HTTPS it can probe TCP, UDP and SCTP ports, ping hosts via ICMP, run DNS queries, hit WebSocket and gRPC endpoints, check SSH, STARTTLS and TLS services, send GraphQL requests, and even track domain expiration dates.
What happens when a check fails?Once a failure threshold is reached, Gatus alerts you through one of its many built-in providers — Slack, Teams, PagerDuty, Discord, Telegram, Twilio, email and dozens more — or a custom alerting provider you write yourself. A default alert can be configured for all endpoints at once.
Can I pull data out or embed status badges elsewhere?Yes. There is a programmatic API exposing raw data, uptime and response-time series, plus generated badges for uptime, health (Shields.io-compatible) and response time, with configurable color thresholds.
Could I use this as an automated smoke-test runner?That is an advertised use case: since conditions can assert on status codes, response bodies, response times and even the resolved IP, the README suggests leveraging Gatus to create automated user acceptance tests.
What are similar projects?uptime-kuma, Checkmate, nezha, upptime, keep, healthchecks, labtether, kubeshark
Which topics is it in?uptime-monitoring, monitoring-tool, status, monitor, health, selfhosted, alerting, container, helm, prometheus, notifications, slack
Creator
TwiN
Size
36 MB
Stars
12.3K
Updated
CommitOct 16Releasev5.37.0Sep 24
Age
7y
Commits · 90 Days