{"id":13764355,"url":"https://github.com/revsys/django-health-check","last_synced_at":"2025-04-09T02:16:07.985Z","repository":{"id":37359411,"uuid":"2238739","full_name":"revsys/django-health-check","owner":"revsys","description":"a pluggable app that runs a full check on the deployment, using a number of plugins to check e.g. database, queue server, celery processes, etc.","archived":false,"fork":false,"pushed_at":"2024-07-23T15:28:07.000Z","size":1492,"stargazers_count":1235,"open_issues_count":61,"forks_count":191,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-29T16:53:45.187Z","etag":null,"topics":["django","monitoring"],"latest_commit_sha":null,"homepage":"https://readthedocs.org/projects/django-health-check/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/revsys.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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},"funding":{"github":"codingjoe","custom":"https://www.paypal.me/codingjoe"}},"created_at":"2011-08-20T11:53:16.000Z","updated_at":"2024-10-28T12:35:38.000Z","dependencies_parsed_at":"2023-02-16T04:16:02.844Z","dependency_job_id":"fb511d76-8cd1-407d-8f57-d3af9980418f","html_url":"https://github.com/revsys/django-health-check","commit_stats":{"total_commits":311,"total_committers":77,"mean_commits":4.038961038961039,"dds":0.8006430868167203,"last_synced_commit":"4da1fd9d7ceffe72d16d01143e1104e119ebac55"},"previous_names":["kristianoellegaard/django-health-check"],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-health-check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-health-check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-health-check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-health-check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/revsys","download_url":"https://codeload.github.com/revsys/django-health-check/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247962605,"owners_count":21024871,"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":["django","monitoring"],"created_at":"2024-08-03T16:00:19.405Z","updated_at":"2025-04-09T02:16:07.970Z","avatar_url":"https://github.com/revsys.png","language":"Python","funding_links":["https://github.com/sponsors/codingjoe","https://www.paypal.me/codingjoe"],"categories":["Python","Administration and Monitoring"],"sub_categories":[],"readme":"# django-health-check\n\n[![version](https://img.shields.io/pypi/v/django-health-check.svg)](https://pypi.python.org/pypi/django-health-check/)\n[![pyversion](https://img.shields.io/pypi/pyversions/django-health-check.svg)](https://pypi.python.org/pypi/django-health-check/)\n[![djversion](https://img.shields.io/pypi/djversions/django-health-check.svg)](https://pypi.python.org/pypi/django-health-check/)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://pypi.python.org/pypi/django-health-check/)\n\n\nThis project checks for various conditions and provides reports when anomalous\nbehavior is detected.\n\nThe following health checks are bundled with this project:\n\n- cache\n- database\n- storage\n- disk and memory utilization (via `psutil`)\n- AWS S3 storage\n- Celery task queue\n- Celery ping\n- RabbitMQ\n- Migrations\n- Database Heartbeat (Lightweight version of `health_check.db`)\n\nWriting your own custom health checks is also very quick and easy.\n\nWe also like contributions, so don't be afraid to make a pull request.\n\n## Use Cases\n\nThe primary intended use case is to monitor conditions via HTTP(S), with\nresponses available in HTML and JSON formats. When you get back a response that\nincludes one or more problems, you can then decide the appropriate course of\naction, which could include generating notifications and/or automating the\nreplacement of a failing node with a new one. If you are monitoring health in a\nhigh-availability environment with a load balancer that returns responses from\nmultiple nodes, please note that certain checks (e.g., disk and memory usage)\nwill return responses specific to the node selected by the load balancer.\n\n## Supported Versions\n\nWe officially only support the latest version of Python as well as the\nlatest version of Django and the latest Django LTS version.\n\n## Installation\n\nFirst, install the `django-health-check` package:\n\n```shell\n$ pip install django-health-check\n```\n\nAdd the health checker to a URL you want to use:\n\n```python\n    urlpatterns = [\n        # ...\n        path(r'ht/', include('health_check.urls')),\n    ]\n```\n\nAdd the `health_check` applications to your `INSTALLED_APPS`:\n\n```python\n    INSTALLED_APPS = [\n        # ...\n        'health_check',                             # required\n        'health_check.db',                          # stock Django health checkers\n        'health_check.cache',\n        'health_check.storage',\n        'health_check.contrib.migrations',\n        'health_check.contrib.celery',              # requires celery\n        'health_check.contrib.celery_ping',         # requires celery\n        'health_check.contrib.psutil',              # disk and memory utilization; requires psutil\n        'health_check.contrib.s3boto3_storage',     # requires boto3 and S3BotoStorage backend\n        'health_check.contrib.rabbitmq',            # requires RabbitMQ broker\n        'health_check.contrib.redis',               # requires Redis broker\n        'health_check.contrib.db_heartbeat',\n    ]\n```\n\n**Note:** If using `boto 2.x.x` use `health_check.contrib.s3boto_storage`\n\n(Optional) If using the `psutil` app, you can configure disk and memory\nthreshold settings; otherwise below defaults are assumed. If you want to disable\none of these checks, set its value to `None`.\n\n```python\n    HEALTH_CHECK = {\n        'DISK_USAGE_MAX': 90,  # percent\n        'MEMORY_MIN': 100,    # in MB\n    }\n```\n\nTo use Health Check Subsets, Specify a subset name and associate it with the relevant health check services to utilize Health Check Subsets. (New in version 3.18.0)\n```python\n    HEALTH_CHECK = {\n        # .....\n        \"SUBSETS\": {\n            \"startup-probe\": [\"MigrationsHealthCheck\", \"DatabaseBackend\"],\n            \"liveness-probe\": [\"DatabaseBackend\"],\n            \"\u003cSUBSET_NAME\u003e\": [\"\u003cHealth_Check_Service_Name\u003e\"]\n        },\n        # .....\n    }\n```\n\nTo only execute specific subset of health check\n```shell\ncurl -X GET -H \"Accept: application/json\" http://www.example.com/ht/startup-probe/\n```\n\nIf using the DB check, run migrations:\n\n```shell\n$ django-admin migrate\n```\n\nTo use the RabbitMQ healthcheck, please make sure that there is a variable named\n`BROKER_URL` on django.conf.settings with the required format to connect to your\nrabbit server. For example:\n\n```python\n    BROKER_URL = \"amqp://myuser:mypassword@localhost:5672/myvhost\"\n```\n\nTo use the Redis healthcheck, please make sure that there is a variable named ``REDIS_URL``\non django.conf.settings with the required format to connect to your redis server. For example:\n\n```python\n    REDIS_URL = \"redis://localhost:6370\"\n```\n\nThe cache healthcheck tries to write and read a specific key within the cache backend.\nIt can be customized by setting `HEALTHCHECK_CACHE_KEY` to another value:\n\n```python\n    HEALTHCHECK_CACHE_KEY = \"custom_healthcheck_key\"\n```\n\nAdditional connection options may be specified by defining a variable ``HEALTHCHECK_REDIS_URL_OPTIONS`` on the settings module.\n\n## Setting up monitoring\n\nYou can use tools like Pingdom, StatusCake or other uptime robots to monitor service status.\nThe `/ht/` endpoint will respond with an HTTP 200 if all checks passed\nand with an HTTP 500 if any of the tests failed.\nGetting machine-readable JSON reports\n\nIf you want machine-readable status reports you can request the `/ht/`\nendpoint with the `Accept` HTTP header set to `application/json`\nor pass `format=json` as a query parameter.\n\nThe backend will return a JSON response:\n\n```shell\n    $ curl -v -X GET -H \"Accept: application/json\" http://www.example.com/ht/\n\n    \u003e GET /ht/ HTTP/1.1\n    \u003e Host: www.example.com\n    \u003e Accept: application/json\n    \u003e\n    \u003c HTTP/1.1 200 OK\n    \u003c Content-Type: application/json\n\n    {\n        \"CacheBackend\": \"working\",\n        \"DatabaseBackend\": \"working\",\n        \"S3BotoStorageHealthCheck\": \"working\"\n    }\n\n    $ curl -v -X GET http://www.example.com/ht/?format=json\n\n    \u003e GET /ht/?format=json HTTP/1.1\n    \u003e Host: www.example.com\n    \u003e\n    \u003c HTTP/1.1 200 OK\n    \u003c Content-Type: application/json\n\n    {\n        \"CacheBackend\": \"working\",\n        \"DatabaseBackend\": \"working\",\n        \"S3BotoStorageHealthCheck\": \"working\"\n    }\n```\n\n## Writing a custom health check\n\nWriting a health check is quick and easy:\n\n```python\n    from health_check.backends import BaseHealthCheckBackend\n\n    class MyHealthCheckBackend(BaseHealthCheckBackend):\n        #: The status endpoints will respond with a 200 status code\n        #: even if the check errors.\n        critical_service = False\n\n        def check_status(self):\n            # The test code goes here.\n            # You can use `self.add_error` or\n            # raise a `HealthCheckException`,\n            # similar to Django's form validation.\n            pass\n\n        def identifier(self):\n            return self.__class__.__name__  # Display name on the endpoint.\n```\n\nAfter writing a custom checker, register it in your app configuration:\n\n```python\n    from django.apps import AppConfig\n\n    from health_check.plugins import plugin_dir\n\n    class MyAppConfig(AppConfig):\n        name = 'my_app'\n\n        def ready(self):\n            from .backends import MyHealthCheckBackend\n            plugin_dir.register(MyHealthCheckBackend)\n```\n\nMake sure the application you write the checker into is registered in your\n`INSTALLED_APPS`.\n\n## Customizing output\n\nYou can customize HTML or JSON rendering by inheriting from `MainView` in\n`health_check.views` and customizing the `template_name`, `get`, `render_to_response`\nand `render_to_response_json` properties:\n\n```python\n    # views.py\n    from health_check.views import MainView\n\n    class HealthCheckCustomView(MainView):\n        template_name = 'myapp/health_check_dashboard.html'  # customize the used templates\n\n        def get(self, request, *args, **kwargs):\n            plugins = []\n            status = 200 # needs to be filled status you need\n            # ...\n            if 'application/json' in request.META.get('HTTP_ACCEPT', ''):\n                return self.render_to_response_json(plugins, status)\n            return self.render_to_response(plugins, status)\n\n        def render_to_response(self, plugins, status):       # customize HTML output\n            return HttpResponse('COOL' if status == 200 else 'SWEATY', status=status)\n\n        def render_to_response_json(self, plugins, status):  # customize JSON output\n            return JsonResponse(\n                {str(p.identifier()): 'COOL' if status == 200 else 'SWEATY' for p in plugins},\n                status=status\n            )\n\n    # urls.py\n    import views\n\n    urlpatterns = [\n        # ...\n        path(r'ht/', views.HealthCheckCustomView.as_view(), name='health_check_custom'),\n    ]\n```\n\n## Django command\n\nYou can run the Django command `health_check` to perform your health checks via the command line,\nor periodically with a cron, as follow:\n\n```shell\n    django-admin health_check\n```\n\nThis should yield the following output:\n\n```\n    DatabaseHealthCheck      ... working\n    CustomHealthCheck        ... unavailable: Something went wrong!\n```\n\nSimilar to the http version, a critical error will cause the command to quit with the exit code `1`.\n\n\n## Other resources\n\n- [django-watchman](https://github.com/mwarkentin/django-watchman) is a package that does some of the same things in a slightly different way.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevsys%2Fdjango-health-check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frevsys%2Fdjango-health-check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevsys%2Fdjango-health-check/lists"}