My health check system developed in Python
7.8K
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
protocol://host:port/endpoint,
protocol:host:port/endpoint or host:port./status, /health, /healthz, /livez,
/readyz, /ready, /ping, /-/healthy, /api/health, /actuator/health, ...) or
custom paths per target.trace_id, OpenTelemetry traces (OTLP/HTTP).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/healthchecks/health). A URL without a path (http://app:8080orhttp://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 withpaths: [/](see below).
--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
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.
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
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
| Variable | Default | Description |
|---|---|---|
HTTP_PORT | 8000 | API port |
LOG_LEVEL | INFO | DEBUG, INFO, WARNING, ERROR, CRITICAL |
CHECK_INTERVAL | 60 | Seconds between check cycles |
REQUEST_TIMEOUT | 5 | Per-request timeout (seconds) |
RESPONSE_TIME_THRESHOLD | 3.0 | Slower answers are marked degraded |
RETRY_ATTEMPTS / RETRY_DELAY | 3 / 2 | Retries for network errors, timeouts and 5xx |
HEALTH_ENDPOINTS | Comma-separated endpoints | |
TARGETS_FILE | YAML/JSON/text file with targets | |
DEFAULT_HEALTH_PATHS | /status,/health,... | Paths tried when a target has none |
DISCOVERY_ENABLED | false | Kubernetes service discovery |
DISCOVERY_NAMESPACES | (all) | Namespaces to scan (globs allowed) |
DISCOVERY_EXCLUDE_NAMESPACES | kube-system,kube-public,kube-node-lease | Namespaces to skip |
DISCOVERY_PORTS | 80,8080,8888 | Service ports to check (* = all) |
DB_PATH | /data/myhealthcheck.db | SQLite database |
OTEL_ENABLED | false | Export traces (OTLP/HTTP) |
OTEL_EXPORTER_OTLP_ENDPOINT | e.g. http://alloy:4318 | |
ALERT_WEBHOOK_URL | JSON 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.
| Path | Purpose |
|---|---|
/docs, /redoc, /openapi.json | API documentation |
/api/v1/targets | List, create (POST) and remove (DELETE /{id}) targets |
/api/v1/checks | Run a check cycle now (POST) |
/api/v1/probe | Ad-hoc check of any URL (POST, not stored) |
/api/v1/summary | Counters by status and source |
/health/live | Liveness |
/health/ready | Readiness (503 until the first check cycle finishes) |
/metrics | Prometheus 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!
GPL-3.0 - https://github.com/aeciopires/myhealthcheck/blob/main/LICENSE
Content type
Image
Digest
sha256:13335d4b6…
Size
66.3 MB
Last updated
3 days ago
docker pull aeciopires/myhealthcheck