twin/gatus

Automated developer-oriented status page with alerting and incident support

10,541 stars Go 11 components 21 connections

Developer-focused health monitoring dashboard with alerting and incident support

Configuration drives endpoint monitoring which triggers alerts and persists results to storage

Under the hood, the system uses 3 feedback loops, 2 data pools, 4 control points to manage its runtime behavior.

Structural Verdict

A 11-component dashboard with 21 connections. 235 files analyzed. Highly interconnected — components depend on each other heavily.

How Data Flows Through the System

Configuration drives endpoint monitoring which triggers alerts and persists results to storage

Load Configuration — Parse YAML config defining endpoints and alert providers (config: endpoints)
Initialize Monitoring — Start watchdog to periodically check configured endpoints (config: endpoints)
Execute Health Checks — HTTP/ICMP/TCP/DNS requests to validate service health (config: endpoints)
Evaluate Conditions — Check response against configured success/failure conditions (config: endpoints)
Trigger Alerts — Send notifications via configured providers when thresholds exceeded (config: endpoints)
Persist Results — Store check results and alert history in database
Serve Dashboard — Present real-time status and historical data via web interface

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Results Database (database)
Health check results, alert history, and endpoint status

Configuration Cache (in-memory)
Parsed endpoint definitions and alert provider configurations

Feedback Loops

Health Check Loop (polling, balancing) — Trigger: Timer intervals per endpoint. Action: Execute health check and evaluate conditions. Exit: Application shutdown.
Alert Threshold Logic (circuit-breaker, balancing) — Trigger: Consecutive failures reach threshold. Action: Send alert notification. Exit: Success threshold met.
Configuration Reload (polling, balancing) — Trigger: Config file change detected. Action: Reload and apply new configuration. Exit: File stable.

Delays & Async Processing

Health Check Intervals (scheduled-job, ~configurable per endpoint) — Time between endpoint status updates
Alert Cooldown (rate-limit, ~minimum-reminder-interval) — Prevents alert spam during prolonged outages
Startup Delay (scheduled-job, ~GATUS_DELAY_START_SECONDS) — Delays application start for orchestration coordination

Control Points

GATUS_CONFIG_PATH (env-var) — Controls: Configuration file location
GATUS_LOG_LEVEL (env-var) — Controls: Logging verbosity
Alert Thresholds (threshold) — Controls: When alerts fire and resolve. Default: failure: 3, success: 2
Provider Overrides (runtime-toggle) — Controls: Per-group alert configuration

Technology Stack

Go (framework)
Core application runtime

Fiber v2 (framework)
HTTP web framework

SQLite (database)
Default database storage

PostgreSQL (database)
Alternative database backend

Prometheus (library)
Metrics collection and exposure

WebSockets (library)
Real-time dashboard updates

YAML (library)
Configuration file format

Docker (infra)
Container deployment

Key Components

main (function) — Bootstrap application, start monitoring and web server, handle graceful shutdown main.go
Alert (type-def) — Defines alert configuration with thresholds, types, and validation rules alerting/alert/alert.go
Config (config) — Central alerting configuration that registers all provider types alerting/config.go
AlertProvider (class) — AWS SES email alert provider with authentication and message formatting alerting/provider/awsses/awsses.go
AlertProvider (class) — Discord webhook alert provider with custom message content and titles alerting/provider/discord/discord.go
AlertProvider (class) — Generic HTTP webhook provider with configurable headers and placeholders alerting/provider/custom/custom.go
watchdog (module) — Monitors endpoints continuously and triggers alerts on failures watchdog/
controller (handler) — HTTP request handlers for status dashboard and REST API controller/
storage (module) — Persists monitoring results with support for SQLite, PostgreSQL storage/
endpoint (config) — Defines service endpoints to monitor with conditions and alert configurations config/endpoint/
client (utility) — HTTP client wrapper with timeout and authentication configuration client/

Configuration

config.yaml (yaml)

endpoints (array, unknown) — default: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Explore the interactive analysis

See the full architecture map, data flow, and code patterns visualization.

Analyze on CodeSea

Related Dashboard Repositories

Frequently Asked Questions

What is gatus used for?

Developer-focused health monitoring dashboard with alerting and incident support twin/gatus is a 11-component dashboard written in Go. Highly interconnected — components depend on each other heavily. The codebase contains 235 files.

How is gatus architected?

gatus is organized into 5 architecture layers: Configuration & Bootstrap, Monitoring Engine, Alerting System, Storage & Persistence, and 1 more. Highly interconnected — components depend on each other heavily. This layered structure enables tight integration between components.

How does data flow through gatus?

Data moves through 7 stages: Load Configuration → Initialize Monitoring → Execute Health Checks → Evaluate Conditions → Trigger Alerts → .... Configuration drives endpoint monitoring which triggers alerts and persists results to storage This pipeline design reflects a complex multi-stage processing system.

What technologies does gatus use?

The core stack includes Go (Core application runtime), Fiber v2 (HTTP web framework), SQLite (Default database storage), PostgreSQL (Alternative database backend), Prometheus (Metrics collection and exposure), WebSockets (Real-time dashboard updates), and 2 more. A focused set of dependencies that keeps the build manageable.

What system dynamics does gatus have?

gatus exhibits 2 data pools (Results Database, Configuration Cache), 3 feedback loops, 4 control points, 3 delays. The feedback loops handle polling and circuit-breaker. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does gatus use?

5 design patterns detected: Provider Pattern, Configuration Validation, Override System, Graceful Shutdown, Test Mocking.

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.