py-healthcheck: Flask and Tornado Healthcheck Endpoints

1.10.1 · active · verified Thu Apr 16

py-healthcheck is a Python library that simplifies adding healthcheck and environment dump endpoints to Flask or Tornado web applications. It allows developers to define custom check functions to monitor application dependencies and internal state, exposing their status via a configurable HTTP route. The latest stable version is 1.10.1, though its release cadence appears irregular based on PyPI and GitHub history, with the most recent update in June 2022.

Common errors

```
ModuleNotFoundError: No module named 'healthcheck'
```
cause The `py-healthcheck` library has not been installed or is not accessible in the current Python environment.

fix Run `pip install py-healthcheck` to install the library.
```
HTTP 404 Not Found when accessing /healthcheck or /environment
```
cause The health check or environment dump endpoints have not been correctly registered with your Flask or Tornado application.

fix For Flask, ensure `HealthCheck(app, '/healthcheck')` and `EnvironmentDump(app, '/environment')` are correctly instantiated with your `app` object and desired paths. For Tornado, ensure `TornadoHandler` is correctly added to `app.add_handlers` or `tornado.web.Application` routes.
```
TypeError: 'bool' object is not iterable
```
cause A custom health checker function returned only a boolean or another non-iterable type, instead of the required `(bool, str)` tuple.

fix Modify your checker function to return a tuple, e.g., `return True, "All good"`.

Warnings

gotcha Health check results are cached by default (27 seconds for success, 9 seconds for failure). This can obscure immediate service degradation. To perform real-time checks, initialize `HealthCheck` with `success_ttl=None` and `failed_ttl=None`.
Fix: Initialize `HealthCheck(success_ttl=None, failed_ttl=None)` or tune `success_ttl` and `failed_ttl` parameters as needed.
gotcha All custom health checker functions must strictly return a tuple of `(bool, str)`. The boolean indicates success/failure, and the string provides a message. Exceptions within a checker function are caught and reported as failures.
Fix: Ensure all functions passed to `health.add_check()` adhere to the `(bool, str)` return signature. For example: `return True, "Service is up"` or `return False, "Service is down: error details"`.
gotcha Starting with version 1.6.0, the library added support for timeouts on execution checkers. If your custom checks perform long-running operations, consider implementing explicit timeouts within your checker functions or exploring configuration options for the `HealthCheck` instance to prevent health checks from blocking.
Fix: Review documentation for `HealthCheck` or `add_check` for specific timeout parameters. Alternatively, implement timeouts using Python's `concurrent.futures` or `asyncio.wait_for` within your custom checker functions. The release notes suggest this is an added capability.

Install

pip install py-healthcheck Install latest version

Imports

HealthCheck
```
from healthcheck import HealthCheck
```
EnvironmentDump
```
from healthcheck import EnvironmentDump
```
TornadoHandler
```
from healthcheck import TornadoHandler
```

Quickstart

This Flask quickstart demonstrates setting up `/healthcheck` and `/environment` endpoints. Custom functions (`redis_available`, `database_check`) are added to the health check. The `EnvironmentDump` also includes custom application data. Run with `python your_app.py` or `flask run` and access `/healthcheck` and `/environment` in your browser. Set `MOCK_REDIS_FAILURE=true` or `MOCK_DB_FAILURE=true` environment variables to see failure states.

from flask import Flask
from healthcheck import HealthCheck, EnvironmentDump
import os

app = Flask(__name__)

health = HealthCheck(app, '/healthcheck')
envdump = EnvironmentDump(app, '/environment')

def redis_available():
    # Simulate a Redis check
    # In a real app, you'd connect to Redis here
    if os.environ.get('MOCK_REDIS_FAILURE') == 'true':
        return False, "Redis connection failed (mocked)"
    return True, "redis ok"

def database_check():
    # Simulate a database check
    # In a real app, you'd check DB connection/query
    if os.environ.get('MOCK_DB_FAILURE') == 'true':
        return False, "Database connection failed (mocked)"
    return True, "database ok"

health.add_check(redis_available)
health.add_check(database_check)

def application_data():
    return {
        "maintainer": "Your Name",
        "git_repo": "https://github.com/your/repo",
        "version": "1.0.0"
    }

envdump.add_section("application", application_data)

# To run the Flask app (for demonstration, use 'flask run' in production)
if __name__ == '__main__':
    # Example usage: http://127.0.0.1:5000/healthcheck
    # Example usage: http://127.0.0.1:5000/environment
    app.run(debug=True)

view raw JSON →