# HealthChecks
Welcome to the healthiest library of all times! It provides a simple interface to check the health of your application.
We have base classes for HTTP and FILE based health checks.
# Installation
TODO
### If you want to check health of your **FastAPI** application, run:
```bash
poetry run health-checks -E fastapi
```
### If you want to check health of your **Litestar** application, run:
```bash
poetry run health-checks -E litestar
```
### If you want to check health of your **consumer**, run:
```bash
poetry run health-checks -E file
```
## HTTP based quickstart
Let's begin with http based healthchecks for **Litestar** application:
```python
from health_checks.http_based import DefaultHTTPHealthCheck
from health_checks.litestar_healthcheck import build_litestar_health_check_router
import litestar
litestar_application = litestar.Litestar(
route_handlers=[
build_litestar_health_check_router(
healthcheck_endpoint="/health/",
health_check=DefaultHTTPHealthCheck(),
),
],
)
```
This 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.
Similar to litestar, here is the **FastAPI** example
```python
import fastapi
from health_checks.fastapi_healthcheck import build_fastapi_health_check_router
from health_checks.http_based import DefaultHTTPHealthCheck
fastapi_app = fastapi.FastAPI()
fastapi_app.include_router(
build_fastapi_health_check_router(
health_check_endpoint="/health/",
health_check=DefaultHTTPHealthCheck(),
),
)
```
This is also it! How wonderful, isn't it? You can navigate to `/health/` and meet your 200 HTTP status code.
## FILE based quickstart
Here things are starting to get complicated.
Let's imagine a simple consumer
```python
import dataclasses
from health_checks.base import HealthCheck
@dataclasses.dataclass
class SimpleConsumer:
health_check: HealthCheck
async def startup(self):
await self.health_check.startup()
async def shutdown(self):
await self.health_check.shutdown()
async def listen(self):
while True:
# Here we receive our messages from some queue
try:
# Non-blocking message processing
await self.process_message()
# Be attentive! We call update_health method, not update_health_status.
await health_check.update_health()
except Exception:
continue
```
This is very **important** to place your health check inside infinite loop or something like that in your consumer.
You 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.
So, your update_health method call should be independent from message processing, also it should not be locked by it.
So, here how your code could look like
```python
# directory/some_file.py
import asyncio
from health_checks import file_based
health_check_object = file_based.DefaultFileHealthCheck()
consumer = SimpleConsumer(health_check_object)
if __name__ == '__main__':
asyncio.run(consumer.run_consumer())
```
Cool! Now during your consumer process health will be updated. But how to check it and where?
In this package we have a cli, that allows you to check health of certain **HealthCheck** object. Here, how you can use it
```bash
python -m health_checks directory.some_file:health_check_object
```
Here `some_file` is the name of file and `health_check_object` is the name of file_based.DefaultFileHealthCheck object.
If everything is alright, then there will be no exception, but if it is not - there will be
And you use it inside your k8s manifest like this:
```yaml
livenessProbe:
exec:
command:
- python
- "-m"
- health_checks
- directory.some_file:health_check_object
```
Now let's look at FILE health check accepted arguments.
```python
@dataclasses.dataclass
class BaseFileHealthCheck(base.HealthCheck):
failure_threshold: int = 60
health_check_period: int = 30
healthcheck_file_name: str | None = None
base_folder: str = "./tmp/health-checks"
...
```
- `base_folder` - folder, where health check file will be created.
- `failure_threshold` - time after which health check won't pass
- `health_check_period` - delay time before updating health check file
- `healthcheck_file_name` - you can pass an explicit file name to your health check.
> IMPORTANT: You actually have to pass `healthcheck_file_name` it if your are not running in k8s environment.
> In that case your health check file will be named randomly and you cannot check health with provided script.
> If you are running in k8s, then file name will be made of `HOSTNAME` env variable a.k.a. pod id.
> IMPORTANT: Consider putting your health check into separate file to prevent useless imports during health check script execution.
## FAQ
- **Why do i even need `health_check_period` in FILE based health check?**
This parameter helps to throttle calls to `update_health` method. By default `update_health` will be called every 30 seconds.
- **Custom health checks**
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/).
Raw data
{
"_id": null,
"home_page": null,
"name": "health-checks",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "fastapi-health, litestar-health, health-check, uptime-monitoring, service-status, endpoint-health, application-monitoring, diagnostics, health-middleware, system-status",
"author": "community-of-python",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c1/68/8ce64d176c2da6e0baf249e67132ee013dc32fee0392bfdc0a364bfffaf5/health_checks-1.1.0.tar.gz",
"platform": null,
"description": "# HealthChecks\n\nWelcome to the healthiest library of all times! 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 healthchecks 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> IMPORTANT: You actually have to pass `healthcheck_file_name` it if your are not running in k8s environment.\n> In that case your health check file will be named randomly and you cannot check health with provided script.\n> If you are running in k8s, then file name will be made of `HOSTNAME` env variable a.k.a. pod id.\n\n> 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",
"bugtrack_url": null,
"license": null,
"summary": "Library for health checks",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [
"fastapi-health",
" litestar-health",
" health-check",
" uptime-monitoring",
" service-status",
" endpoint-health",
" application-monitoring",
" diagnostics",
" health-middleware",
" system-status"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "45d2829fed4c5e2e9c337ddad3df462b7f0878349f1d41062d7f2af4460e65df",
"md5": "030bad799ecddae39c5de106fe8402a0",
"sha256": "c5e9a91b3da3a75290cf57da2465ebd40b06d08654febc69d1d3f5341fecff2f"
},
"downloads": -1,
"filename": "health_checks-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "030bad799ecddae39c5de106fe8402a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 7194,
"upload_time": "2024-10-23T10:38:11",
"upload_time_iso_8601": "2024-10-23T10:38:11.365644Z",
"url": "https://files.pythonhosted.org/packages/45/d2/829fed4c5e2e9c337ddad3df462b7f0878349f1d41062d7f2af4460e65df/health_checks-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1688ce64d176c2da6e0baf249e67132ee013dc32fee0392bfdc0a364bfffaf5",
"md5": "ec026cc1affe46c298c18da3918aa7f2",
"sha256": "c0f9457a7cdb2b43f7d67c85a935a3a5d2766b1b6b9b58807421b3caa11368eb"
},
"downloads": -1,
"filename": "health_checks-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ec026cc1affe46c298c18da3918aa7f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 5723,
"upload_time": "2024-10-23T10:38:12",
"upload_time_iso_8601": "2024-10-23T10:38:12.585066Z",
"url": "https://files.pythonhosted.org/packages/c1/68/8ce64d176c2da6e0baf249e67132ee013dc32fee0392bfdc0a364bfffaf5/health_checks-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 10:38:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "health-checks"
}
JSON