Service Health Checker

service-health-checker is a Python library that validates the health of critical service dependencies and reports whether your system is safe to run.

It is designed for:

• production readiness checks
• container health checks
• Kubernetes readiness probes
• CI/CD deployment checks

Features

• Health checks for dependencies such as:
  • databases
  • cache systems
  • message queues
  • external APIs
  • storage services
• Simple status model: OK or FAILED
• Aggregated report with optional fail-fast exit code for automation
• Lightweight, no third-party dependencies

Installation

pip install service-health-checker

Quick Start (Library)

from service_health_checker import (
    ServiceMonitor,
    tcp_check,
    http_check,
    disk_space_check,
)

monitor = ServiceMonitor(timeout=3.0)

monitor.add_check("Database", tcp_check(host="127.0.0.1", port=5432))
monitor.add_check("Redis", tcp_check(host="127.0.0.1", port=6379))
monitor.add_check("Kafka", tcp_check(host="127.0.0.1", port=9092))
monitor.add_check("External API", http_check(url="https://api.example.com/health"))
monitor.add_check("Disk Space", disk_space_check(path="/", min_free_percent=10.0))

report = monitor.run()
print(report.to_table())

if not report.is_healthy:
    raise SystemExit("System is not safe to run")

Example Output

Service Health Report

Database        OK
Redis           OK
Kafka           OK
External API    FAILED
Disk Space      OK

CLI Usage

The package provides a CLI command:

service-health-check --http "External API=https://api.example.com/health" --disk "Disk Space=/,10"

Additional examples:

service-health-check \
  --tcp "Database=127.0.0.1:5432" \
  --tcp "Redis=127.0.0.1:6379" \
  --tcp "Kafka=127.0.0.1:9092" \
  --http "External API=https://api.example.com/health" \
  --disk "Disk Space=/,10" \
  --json

Exit codes:

• 0 when all checks are healthy
• 1 when one or more checks fail

Built-in Checks

• tcp_check(host, port)
• http_check(url, method="GET")
• disk_space_check(path="/", min_free_percent=10.0)

API Overview

• ServiceMonitor(timeout=3.0)
• add_check(name, check_fn)
• run() -> HealthReport

HealthReport provides:

• results: list of individual service results
• is_healthy: boolean overall status
• to_table(): human-readable report
• to_dict(): structured output