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.4K ·GitHub
Gatus
Что это такое?Gatus — это опенсорсная страница статуса и панель мониторинга здоровья, ориентированная на разработчиков: она активно проверяет ваши сервисы по HTTP, TCP, ICMP или DNS, показывает результаты на веб-панели и умеет отправлять оповещения, когда проверки проваливаются.
Чем это отличается от Prometheus Alertmanager или алертов Cloudwatch?Оповещения на основе метрик зависят от уже идущего трафика, поэтому ничего не сработает, если ни один клиент не обращается к упавшему сервису. Gatus сам запускает проверки по расписанию и может предупредить вас раньше, чем пользователи заметят сбой.
Как это запустить?Запустите Docker-образ (docker run -p 8080:8080 twinproduction/gatus) и подключите свой файл конфигурации. В документации также описаны установка через Helm chart, Terraform, манифесты Kubernetes и обычный бинарный файл. По умолчанию конфигурация читается из config/config.yaml.
Как выглядит настройка проверки здоровья?Всё в YAML: для каждого эндпоинта указываются имя, URL, метод, интервал и список условий по значениям вроде кода статуса, времени ответа, тела ответа или срока истечения сертификата. На отслеживаемых сервисах ничего не нужно устанавливать.
Есть ли что-то экспериментальное или устаревшее, что стоит знать?Да — Suites помечены как ALPHA, удалённые инстансы — EXPERIMENTAL, а старые оповещения Teams устарели: вместо них используются Teams Workflow alerts. Конфигурационные файлы также строгие: примитивный параметр, определённый дважды в объединяемых файлах, приведёт к ошибке.
Это для ops-команд или для одиночных разработчиков?Проект изначально ориентирован на разработчиков: автор запускает его в собственном Kubernetes-кластере, чтобы следить за ключевыми приложениями, а варианты развёртывания варьируются от одного Docker-контейнера до Helm и Terraform — подойдёт любому, кто самостоятельно хостит свои сервисы.
Она отправляет данные куда-то наружу?Полностью self-hosted решение: проверки выполняются там, где вы его развернули, а результаты остаются в вашем собственном хранилище (в комплекте есть пример docker-compose для PostgreSQL). Чувствительные значения конфигурации можно передавать через переменные окружения; есть и управляемый вариант на Gatus.io.
Что ещё можно проверять, кроме обычных HTTP-адресов?Помимо HTTP/HTTPS она умеет проверять TCP, UDP и SCTP порты, пинговать хосты по ICMP, выполнять DNS-запросы, обращаться к WebSocket и gRPC эндпоинтам, проверять сервисы SSH, STARTTLS и TLS, отправлять GraphQL-запросы и даже следить за сроком истечения домена.
Что происходит, когда проверка проваливается?Как только превышен порог сбоев, Gatus отправляет вам оповещение через один из множества встроенных провайдеров — Slack, Teams, PagerDuty, Discord, Telegram, Twilio, email и десятки других — либо через собственный провайдер уведомлений, который вы напишете сами. Можно настроить алерт по умолчанию сразу для всех эндпоинтов.
Можно ли вытащить данные или встроить статус-бейджи на других сайтах?Да. Есть программный API с доступом к сырым данным, аптайму и временным рядам времени ответа, а также готовые бейджи для аптайма, здоровья (совместимые с Shields.io) и времени ответа с настраиваемыми цветовыми порогами.
А можно использовать это как автоматический раннер смоук-тестов?Да, это прямо заявленный сценарий использования: поскольку условия могут проверять коды статусов, тела ответов, время ответа и даже резолвящийся IP, в README предлагается использовать Gatus для создания автоматизированных приёмочных тестов.
What are similar projects?uptime-kuma, Checkmate, nezha, upptime, keep, healthchecks, labtether, kubeshark
Which topics is it in?uptime-monitoring, monitoring-tool, status, monitor, selfhosted, alerting, health, container, helm, prometheus, slack, notifications
Creator
TwiN
Size
36 MB
Stars
12.4K
Updated
CommitOct 17Releasev5.37.0Sep 24
Age
7y
Commits · 90 Days