Eyrie is a distributed uptime monitoring system built for region-aware checks, lightweight deployment, and a status page that reflects both current health and recent history.
The backend is a Go monolith that can run as a server or a checker. The frontend is a React 19 + Vite SPA embedded into the server binary at build time.
- Region-aware monitor execution with checker registration and authenticated result submission
- HTTP, TCP, ICMP, gRPC health checks, Redis, PostgreSQL, MySQL, Microsoft SQL Server, and ClickHouse monitors
- ClickHouse support over both native TCP and HTTP transport through DSN configuration
- Raw submission ingestion plus hourly and daily uptime aggregation in PostgreSQL
- Programmatic incidents with persisted lifecycle records and event timeline groundwork
- Webhook, Slack, Discord, Teams, and ntfy alert delivery targets
- Sentry error monitoring, tracing, logs, and custom metrics around checks, ingestion, processing, and alerting
| Type | Config block | Notes |
|---|---|---|
| HTTP | http |
Supports headers, expected status codes, custom CA trust, and optional client certificates |
| TCP | tcp |
Optional TLS, request payload, and substring assertion |
| ICMP | icmp |
Uses the system ping binary |
| gRPC | grpc |
Calls the standard grpc.health.v1.Health/Check RPC; optional service name and TLS |
| Redis | redis |
Optional auth, database selection, and TLS |
| PostgreSQL | postgres |
Uses a DSN via pgx |
| MySQL | mysql |
Uses a DSN via go-sql-driver/mysql |
| Microsoft SQL Server | mssql |
Uses a sqlserver://... DSN |
| ClickHouse | clickhouse |
Use clickhouse://... for native TCP and ?protocol=http for HTTP |
See example_configurations/monitor.example.yaml for sample definitions.
go run . -mode=server ...
The server process:
- runs PostgreSQL migrations and maintains time-based partitions
- exposes the HTTP API and embedded SPA
- receives checker submissions
- fans submissions out to ingester and processor queues
- runs ingester, processor, and alerter workers
go run . -mode=checker ...
Each checker:
- registers to the server with an API key, region, and optional checker name
- downloads the current monitor configuration
- executes checks on schedule
- submits structured probe results back to the server
Eyrie stores uptime data in PostgreSQL 18+. Plain PostgreSQL is enough; no extensions such as TimescaleDB are required.
monitor_historicalstores raw probe results and is partitioned by UTC day oncreated_atmonitor_historical_hourly_aggregateandmonitor_historical_hourly_region_aggregatestore hourly rollupsmonitor_historical_daily_aggregateandmonitor_historical_region_daily_aggregatestore the daily rollups used by the status pagemonitor_incident_state,monitor_incidents, andmonitor_incident_eventsstore incident state, records, and timeline events
The service creates the current and future partitions automatically. Retention drops whole expired partitions instead of deleting rows one by one, and removes incidents by start time and events by event time (plus events belonging to deleted incidents) once they are older than dataset.retention_days. Submissions older than the current UTC day are acknowledged but not inserted; the ingester logs the time drift.
Configure the connection with:
database:
url: "postgres://eyrie:eyrie@localhost:5432/eyrie?sslmode=disable"
max_connections: 20
min_connections: 2DATABASE_URL overrides database.url. The service needs permission to create and drop tables because it manages partitions at runtime.
This release replaces DuckDB with PostgreSQL. Existing DuckDB data is not imported. Point database.url at a fresh PostgreSQL database and keep the old DuckDB file only as an archive.
| Method | Path | Purpose |
|---|---|---|
GET |
/config |
Returns status page metadata |
GET |
/uptime-data |
Aggregated monitor/group uptime data |
GET |
/uptime-data-by-region |
Region breakdown for a monitor |
GET |
/monitor-incidents |
Current monitor health plus active incident metadata |
POST |
/checker/register |
Checker registration and config fetch |
POST |
/checker/submit |
Checker submission ingestion entrypoint |
If a checker runs outside your private network and the server sits behind a reverse proxy, the minimum paths to expose are:
POST /checker/registerPOST /checker/submit
Everything else can remain private if you only need remote checker registration and result submission.
You can optionally pin a monitor to specific checkers with checker_names. These values must match each checker's effective name: registered_checkers[].name when it is set, otherwise the checker's region. In checker mode, the same fallback applies when name or CHECKER_NAME is unset, so the checker identifies itself by region.
registered_checkers:
- name: "us-east-1-public-checker"
region: "us-east-1"
api_key: "us-east-1-api-key-here"
monitors:
- id: "primary-postgres"
name: "Primary PostgreSQL"
type: "postgres"
checker_names:
- "us-east-1-public-checker"
postgres:
dsn: "postgres://postgres:postgres@10.0.0.5:5432/postgres?sslmode=disable"Monitors without checker_names are still sent to every checker.
HTTP monitors can override TLS material per monitor:
http.ca_cert_pathadds a CA bundle for private trust chains.http.client_cert_pathandhttp.client_key_pathenable mTLS.http.client_key_passwordcan be used with legacy PEM-encrypted private keys.
These files are loaded when each probe runs instead of only once at checker startup, so externally rotated certificates can be picked up without restarting the checker. The YAML loader does not expand environment variables, so the password value must be provided literally or substituted before the monitor config is loaded.
monitors:
- id: "internal-api"
name: "Internal API"
type: "http"
http:
url: "https://internal.example.com/health"
ca_cert_path: "/etc/eyrie/tls/ca.pem"
client_cert_path: "/etc/eyrie/tls/client.crt"
client_key_path: "/etc/eyrie/tls/client.key"
client_key_password: "change-me"
expected_status_codes:
- 200Eyrie currently creates programmatic incidents from processor-evaluated monitor state.
Today that means:
monitor_incident_statestores the current derived health per monitormonitor_incidentsstores the active/resolved incident recordsmonitor_incident_eventsstores timeline events for creation, updates, and resolution
The storage model is intentionally shaped so incidents can remain automatically generated first, then be manually adjusted later without losing the machine-derived values that created them.
Server, checker, and workers all initialize Sentry with tracing and logs enabled. The codebase also emits custom Sentry metrics for:
- checker cycles and monitor checks
- submission receipt, send, and ingestion
- processor incident transitions
- alert delivery outcomes
Example Sentry configuration is included in example_configurations/server.example.yaml and example_configurations/checker.example.yaml.
- Go 1.25+
- Node.js 22+
- PostgreSQL 18+ (the examples below use the
postgres:18-alpineimage)
docker run -d --rm --name eyrie-postgres \
-e POSTGRES_USER=eyrie \
-e POSTGRES_PASSWORD=eyrie \
-e POSTGRES_DB=eyrie \
-p 5432:5432 \
postgres:18-alpine
docker exec eyrie-postgres createdb -U eyrie eyrie_testgo run . -mode=server -config=./example_configurations/server.example.yaml -monitor=./example_configurations/monitor.example.yamlThe example config points at postgres://eyrie:eyrie@localhost:5432/eyrie?sslmode=disable. Set DATABASE_URL to override it.
UPSTREAM_URL="http://localhost:8600" CHECKER_NAME="us-east-1-public-checker" REGION="us-east-1" API_KEY="us-east-1-api-key-here" go run . -mode=checker -config=./example_configurations/checker.example.yamlcd frontend
npm install
npm run devTEST_DATABASE_URL="postgres://eyrie:eyrie@localhost:5432/eyrie_test?sslmode=disable" go test ./...
go build -o eyrie .Without TEST_DATABASE_URL, database integration tests are skipped and the pure unit tests still run. CI starts a postgres:18-alpine service and sets this variable automatically.
cd frontend
npm run lint
npm run build- Use PostgreSQL 18 or newer.
- The service runs embedded migrations on startup and records them in
schema_migrations. - Partition creation and retention require table create/drop privileges.
- External clients such as
psql, Grafana, and DBeaver can query the tables directly. - The service uses UTC for daily partitioning and
date_truncrollups.
- Go sources live at the repository root
frontend/contains the SPAexample_configurations/contains starter YAML filesmigrations/postgres/contains the embedded PostgreSQL schema migrations
Copyright 2025 Reinaldy Rafli <github@reinaldyrafli.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.