HUB
Sign inSign up

aeciopires/myhealthcheck

By aeciopires

•Updated 3 days ago

My health check system developed in Python

Image
0

7.8K

aeciopires/myhealthcheck repository overview

⁠myhealthcheck

Health check system that monitors the availability of other applications. Point it at a list of URLs, or let it discover services in Kubernetes, and it keeps checking them, stores the results and exposes everything through a REST API (Swagger), Prometheus metrics, JSON logs and OpenTelemetry traces.

Source code, documentation and Helm chart: https://github.com/aeciopires/myhealthcheck⁠

⁠Features

  • Checks a list of endpoints in the forms protocol://host:port/endpoint, protocol:host:port/endpoint or host:port.
  • Probes common health paths automatically (/status, /health, /healthz, /livez, /readyz, /ready, /ping, /-/healthy, /api/health, /actuator/health, ...) or custom paths per target.
  • Kubernetes service discovery: a list of namespaces, all namespaces, or all except an exclusion list (globs supported). Ports 80, 8080 and 8888 by default (customizable).
  • Checks every 60 seconds by default, with timeouts, retries (network errors and 5xx only), expected status codes and body, and a "degraded" state for slow answers.
  • REST API documented with Swagger/OpenAPI.
  • SQLite storage with automatic fallback: data volume, then temp directory, then memory.
  • Prometheus metrics, JSON logs with trace_id, OpenTelemetry traces (OTLP/HTTP).
  • Alerts on status change: JSON log line plus an optional webhook.

⁠Quick start

Check two endpoints and open the API:

docker run -d --name myhealthcheck -p 8000:8000 \
  -e HEALTH_ENDPOINTS="https://www.githubstatus.com/api/v2/status.json,http:host.docker.internal:8080/health" \
  aeciopires/myhealthcheck:latest

Then open:

Logs are JSON, one object per line:

docker logs -f myhealthcheck

How URLs are read: the path of the URL is the health endpoint (http://app:8080/health checks /health). A URL without a path (http://app:8080 or http://app:8080/) makes myhealthcheck try the default health paths in order (/status, /health, /healthz, ...) until one answers. To check the root page itself, use a targets file with paths: [/] (see below).

⁠Run a single check (CI / cron)

--once runs one check cycle, prints a JSON report on stdout and exits with code 1 if any target is down (0 when everything is fine, 2 for invalid configuration):

docker run --rm aeciopires/myhealthcheck:latest --once \
  -u https://www.githubstatus.com/api/v2/status.json \
  -u https:api.example.com:443/health

⁠Use a targets file

Create targets.yaml:

defaults:
  timeout: 5

targets:
  - name: my-api
    url: http://my-api:8080
    paths: [/live, /ready]
    match: all              # any (default) | all
    expected_status: [200]  # default: any 2xx/3xx
    labels:
      team: backend

  - name: website
    url: https://example.com/
    paths: [/]

  # A target without paths gets the default health paths (/status, /health, ...)
  - name: legacy
    url: http://legacy:9000

  # Plain URLs work too
  - http:10.0.0.5:8080/status

Mount it and keep the history in a volume:

docker run -d --name myhealthcheck -p 8000:8000 \
  -v "$PWD/targets.yaml:/app/config/targets.yaml:ro" \
  -e TARGETS_FILE=/app/config/targets.yaml \
  -v myhealthcheck-data:/data \
  aeciopires/myhealthcheck:latest

A plain text file with one URL per line is also accepted.

⁠Docker Compose

services:
  myhealthcheck:
    image: aeciopires/myhealthcheck:latest
    ports:
      - "8000:8000"
    environment:
      CHECK_INTERVAL: "60"
      TARGETS_FILE: /app/config/targets.yaml
    volumes:
      - ./targets.yaml:/app/config/targets.yaml:ro
      - myhealthcheck-data:/data
    restart: unless-stopped

volumes:
  myhealthcheck-data:

The GitHub repository has a complete docker-compose.yml with Grafana, Loki, Tempo, Prometheus, Jaeger and Grafana Alloy, plus a ready-made dashboard for metrics, logs and traces:

git clone https://github.com/aeciopires/myhealthcheck.git
cd myhealthcheck
make up

⁠Kubernetes

Use the Helm chart (Helm 4) from the repository. It enables service discovery, read-only RBAC, HTTP probes, ServiceMonitor, PrometheusRule and a Grafana dashboard:

git clone https://github.com/aeciopires/myhealthcheck.git
cd myhealthcheck
helm upgrade --install myhealthcheck charts/myhealthcheck \
  -n myhealthcheck --create-namespace \
  --set 'config.discovery.namespaces={shop,payments}'

Chart documentation: https://github.com/aeciopires/myhealthcheck/blob/main/charts/myhealthcheck/README.md⁠

⁠Main environment variables

VariableDefaultDescription
HTTP_PORT8000API port
LOG_LEVELINFODEBUG, INFO, WARNING, ERROR, CRITICAL
CHECK_INTERVAL60Seconds between check cycles
REQUEST_TIMEOUT5Per-request timeout (seconds)
RESPONSE_TIME_THRESHOLD3.0Slower answers are marked degraded
RETRY_ATTEMPTS / RETRY_DELAY3 / 2Retries for network errors, timeouts and 5xx
HEALTH_ENDPOINTSComma-separated endpoints
TARGETS_FILEYAML/JSON/text file with targets
DEFAULT_HEALTH_PATHS/status,/health,...Paths tried when a target has none
DISCOVERY_ENABLEDfalseKubernetes service discovery
DISCOVERY_NAMESPACES(all)Namespaces to scan (globs allowed)
DISCOVERY_EXCLUDE_NAMESPACESkube-system,kube-public,kube-node-leaseNamespaces to skip
DISCOVERY_PORTS80,8080,8888Service ports to check (* = all)
DB_PATH/data/myhealthcheck.dbSQLite database
OTEL_ENABLEDfalseExport traces (OTLP/HTTP)
OTEL_EXPORTER_OTLP_ENDPOINTe.g. http://alloy:4318
ALERT_WEBHOOK_URLJSON POST on every status change

Full reference: https://github.com/aeciopires/myhealthcheck/blob/main/docs/configuration.md⁠

Run docker run --rm aeciopires/myhealthcheck:latest --help to see every CLI flag.

⁠Endpoints of the container

PathPurpose
/docs, /redoc, /openapi.jsonAPI documentation
/api/v1/targetsList, create (POST) and remove (DELETE /{id}) targets
/api/v1/checksRun a check cycle now (POST)
/api/v1/probeAd-hoc check of any URL (POST, not stored)
/api/v1/summaryCounters by status and source
/health/liveLiveness
/health/readyReadiness (503 until the first check cycle finishes)
/metricsPrometheus metrics

The image has a built-in Docker HEALTHCHECK on /health/live.

If this project is useful to you, please give it a ⭐ on GitHub!

⁠Developer

⁠License

GPL-3.0 - https://github.com/aeciopires/myhealthcheck/blob/main/LICENSE⁠

Tag summary

Content type

Image

Digest

sha256:13335d4b6…

Size

66.3 MB

Last updated

3 days ago

docker pull aeciopires/myhealthcheck