checkers

A simple but comprehensive self-hosted uptime monitoring tool, written in and configured using Python.

Checks are Python objects. Configuration is a Python file that lists which checks to run. There is no web UI, just a plaintext CHECKS list.

Install

pip install -e .

Configure

Write a config file that defines a CHECKS list:

# config.py
from checkers.web import Web
from checkers.http import Http
from checkers.https import Https

CHECKS = [
    Web("example.com"),
    Http("http://internal.example.com/health", interval=30, timeout=5),
    Https("https://example.org", cert_expiry_warning_days=30),
]

See examples/config.py for a full example.

Run

checkers run config.py

Schedules every check at its own interval (default 60 seconds) and runs them concurrently. Results are logged and written to a local SQLite database (checkers.db by default, override with --db).

checkers check config.py

Runs every check once and exits non-zero if any check failed.

Stop a running process with Ctrl-C or SIGTERM; in-progress checks are allowed to finish before exit.

Checkers

All checkers accept interval (seconds between runs, default 60) and timeout (seconds, default 10).

• checkers.http.Http — request a URL, verify the status code and, optionally, that the response contains some expected text.
• checkers.https.Https — an Http check that also verifies the TLS certificate is valid and warns before it expires (cert_expiry_warning_days, default 14).
• checkers.web.Web — the convention for monitoring a website: an Https check of the domain, plus an Http check that plain http:// traffic redirects to https://. Set require_https_redirect=False to skip that requirement.

Custom checkers

A checker is any class implementing checkers.Checker: a run() method that returns a checkers.CheckResult. Use one directly in your config alongside the built-ins:

from checkers import Checker, CheckResult

class DiskSpace(Checker):
    def __init__(self, path, min_free_gb=5, **kwargs):
        self.path = path
        self.min_free_gb = min_free_gb
        super().__init__(**kwargs)

    def run(self):
        free_gb = shutil.disk_usage(self.path).free / 1e9
        if free_gb < self.min_free_gb:
            return CheckResult(False, f"only {free_gb:.1f}GB free")
        return CheckResult(True, f"{free_gb:.1f}GB free")

CHECKS = [DiskSpace("/", min_free_gb=10, interval=300)]

Outages

Every check result is recorded in the database. A check's first failure opens an outage; further failures while it's still down are logged but don't open a new one, and the next success closes it.

Alerting on outages (email, webhooks, etc.) is not implemented yet.

About

Contributions, small or large, are welcome! If you have any questions or feedback, we would love to hear from you.

Checkers is developed at Smart Yellow and licensed under the MIT license.