{"id":19528632,"url":"https://github.com/community-of-python/health-checks","last_synced_at":"2025-06-20T16:12:11.005Z","repository":{"id":253754566,"uuid":"844418144","full_name":"community-of-python/health-checks","owner":"community-of-python","description":"Library for health checks","archived":true,"fork":false,"pushed_at":"2025-02-25T10:52:47.000Z","size":92,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-20T16:11:28.661Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/community-of-python.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-19T08:09:56.000Z","updated_at":"2025-03-11T10:39:43.000Z","dependencies_parsed_at":"2024-12-09T11:27:05.987Z","dependency_job_id":"9ae1d12c-a87b-4214-a3fb-ad660b46a711","html_url":"https://github.com/community-of-python/health-checks","commit_stats":null,"previous_names":["community-of-python/health-checks"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/community-of-python/health-checks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/community-of-python%2Fhealth-checks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/community-of-python%2Fhealth-checks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/community-of-python%2Fhealth-checks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/community-of-python%2Fhealth-checks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/community-of-python","download_url":"https://codeload.github.com/community-of-python/health-checks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/community-of-python%2Fhealth-checks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260976921,"owners_count":23091528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T01:19:28.959Z","updated_at":"2025-06-20T16:12:05.994Z","avatar_url":"https://github.com/community-of-python.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HealthChecks\n\nWelcome to the healthiest library of all time! It provides a simple interface to check the health of your application.\n\nWe have base classes for HTTP and FILE based health checks.\n\n# Installation\n\nTODO\n\n### If you want to check health of your **FastAPI** application, run:\n\n```bash\npoetry run health-checks -E fastapi\n```\n\n### If you want to check health of your **Litestar** application, run:\n\n```bash\npoetry run health-checks -E litestar\n```\n\n### If you want to check health of your **consumer**, run:\n\n```bash\npoetry run health-checks -E file\n```\n\n## HTTP based quickstart\n\nLet's begin with http based health-checks for **Litestar** application:\n\n```python\nfrom health_checks.http_based import DefaultHTTPHealthCheck\nfrom health_checks.litestar_healthcheck import build_litestar_health_check_router\nimport litestar\n\n\nlitestar_application = litestar.Litestar(\n    route_handlers=[\n        build_litestar_health_check_router(\n            healthcheck_endpoint=\"/health/\",\n            health_check=DefaultHTTPHealthCheck(),\n        ),\n    ],\n)\n```\n\nThis is it! Now if your go to `/health/` you will notice a 200 HTTP status code if everything is alright. Otherwise you will face a 500 HTTP status code.\n\nSimilar to litestar, here is the **FastAPI** example\n\n```python\nimport fastapi\nfrom health_checks.fastapi_healthcheck import build_fastapi_health_check_router\nfrom health_checks.http_based import DefaultHTTPHealthCheck\n\n\nfastapi_app = fastapi.FastAPI()\nfastapi_app.include_router(\n    build_fastapi_health_check_router(\n        health_check_endpoint=\"/health/\",\n        health_check=DefaultHTTPHealthCheck(),\n    ),\n)\n```\n\nThis is also it! How wonderful, isn't it? You can navigate to `/health/` and meet your 200 HTTP status code.\n\n## FILE based quickstart\n\nHere things are starting to get complicated.\nLet's imagine a simple consumer\n\n```python\nimport dataclasses\n\nfrom health_checks.base import HealthCheck\n\n\n@dataclasses.dataclass\nclass SimpleConsumer:\n    health_check: HealthCheck\n\n    async def startup(self):\n        await self.health_check.startup()\n\n    async def shutdown(self):\n        await self.health_check.shutdown()\n\n    async def listen(self):\n        while True:\n            # Here we receive our messages from some queue\n            try:\n                # Non-blocking message processing\n                await self.process_message()\n\n                # Be attentive! We call update_health method, not update_health_status.\n                await health_check.update_health()\n            except Exception:\n                continue\n```\n\nThis is very **important** to place your health check inside infinite loop or something like that in your consumer.\nYou cannot use it inside your message processing function or method because if there will be no messages - your consumer will die eventually. And this is not the case we are looking for.\nSo, your update_health method call should be independent from message processing, also it should not be locked by it.\n\nSo, here how your code could look like\n\n```python\n# directory/some_file.py\nimport asyncio\n\nfrom health_checks import file_based\n\n\nhealth_check_object = file_based.DefaultFileHealthCheck()\nconsumer = SimpleConsumer(health_check_object)\n\nif __name__ == '__main__':\n    asyncio.run(consumer.run_consumer())\n```\n\nCool! Now during your consumer process health will be updated. But how to check it and where?\n\nIn this package we have a cli, that allows you to check health of certain **HealthCheck** object. Here, how you can use it\n\n```bash\npython -m health_checks directory.some_file:health_check_object\n```\n\nHere `some_file` is the name of file and `health_check_object` is the name of file_based.DefaultFileHealthCheck object.\nIf everything is alright, then there will be no exception, but if it is not - there will be\n\nAnd you use it inside your k8s manifest like this:\n\n```yaml\nlivenessProbe:\n  exec:\n    command:\n      - python\n      - \"-m\"\n      - health_checks\n      - directory.some_file:health_check_object\n```\n\nNow let's look at FILE health check accepted arguments.\n\n```python\n@dataclasses.dataclass\nclass BaseFileHealthCheck(base.HealthCheck):\n    failure_threshold: int = 60\n    health_check_period: int = 30\n    healthcheck_file_name: str | None = None\n    base_folder: str = \"./tmp/health-checks\"\n    ...\n```\n\n- `base_folder` - folder, where health check file will be created.\n- `failure_threshold` - time after which health check won't pass\n- `health_check_period` - delay time before updating health check file\n- `healthcheck_file_name` - you can pass an explicit file name to your health check.\n\n\u003e IMPORTANT: You actually have to pass `healthcheck_file_name` it if your are not running in k8s environment.\n\u003e In that case your health check file will be named randomly and you cannot check health with provided script.\n\u003e If you are running in k8s, then file name will be made of `HOSTNAME` env variable a.k.a. pod id.\n\n\u003e IMPORTANT: Consider putting your health check into separate file to prevent useless imports during health check script execution.\n\n## FAQ\n\n- **Why do i even need `health_check_period` in FILE based health check?**\n  This parameter helps to throttle calls to `update_health` method. By default `update_health` will be called every 30 seconds.\n- **Custom health checks**\n  There are two options. You can inherit from `BaseFileHealthCheck` or `BaseHTTPHealthCheck`. Another way is to implement class according to HealthCheck protocol. More information about protocols [here](https://peps.python.org/pep-0544/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommunity-of-python%2Fhealth-checks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommunity-of-python%2Fhealth-checks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommunity-of-python%2Fhealth-checks/lists"}