From bdc57895f0c435c77a0158b09c2f14ca59df7a6b Mon Sep 17 00:00:00 2001 From: veldakarimi Date: Thu, 30 Nov 2023 06:22:26 +0300 Subject: [PATCH] completed the external guides docs that include external monitoring, custom output and checks and django command --- docs/src/components/Layout.jsx | 2 +- docs/src/pages/checks/db.md | 8 +++- docs/src/pages/customize-output.md | 46 +++++++++++++++++++ docs/src/pages/management-command.md | 20 +++++++++ docs/src/pages/monitoring.md | 50 +++++++++++++++++++++ docs/src/pages/writing-your-own-checks.md | 54 +++++++++++++++++++++-- 6 files changed, 175 insertions(+), 5 deletions(-) diff --git a/docs/src/components/Layout.jsx b/docs/src/components/Layout.jsx index 6872f130..448de30f 100644 --- a/docs/src/components/Layout.jsx +++ b/docs/src/components/Layout.jsx @@ -47,7 +47,7 @@ const navigation = [ { title: 'Advanced guides', links: [ - { title: 'Writing sustom checks', href: '/writing-your-own-checks' }, + { title: 'Writing custom checks', href: '/writing-your-own-checks' }, { title: 'Customizing the output', href: '/customize-output' }, { title: 'Management Command', href: '/management-command' }, { title: 'External Monitoring', href: '/monitoring' }, diff --git a/docs/src/pages/checks/db.md b/docs/src/pages/checks/db.md index 4ea703db..863612f7 100644 --- a/docs/src/pages/checks/db.md +++ b/docs/src/pages/checks/db.md @@ -55,5 +55,11 @@ INSTALLED_APPS = [ 4.Run migrations ```shell -$ python manage.py migrate + python manage.py migrate ``` + +5.Run the health check +```shell +python manage.py health_check + +``` \ No newline at end of file diff --git a/docs/src/pages/customize-output.md b/docs/src/pages/customize-output.md index e69de29b..c9b9fe30 100644 --- a/docs/src/pages/customize-output.md +++ b/docs/src/pages/customize-output.md @@ -0,0 +1,46 @@ +--- +title: Custom django-health-check output +pageTitle: Writing custom django-health-check output +description: How to write your own health checks output. +--- +Customizing your output comes in handy when you need to match the needs your +application or integrate with specific frontend tools and monitoring tools + +You can customize your output (HTML or JSON) rendering by inheriting from MainView in +`health_check.views` and customize the `template_name`,` get`, `render_to_response `and + `render_to_response_json` properties: + +```python +# views.py +from health_check.views import MainView + +class HealthCheckCustomView(MainView): + template_name = 'myapp/health_check_dashboard.html' # customize the used templates + + def get(self, request, *args, **kwargs): + plugins = [] + status = 200 # needs to be filled status you need + # ... + if 'application/json' in request.META.get('HTTP_ACCEPT', ''): + return self.render_to_response_json(plugins, status) + return self.render_to_response(plugins, status) + + def render_to_response(self, plugins, status): # customize HTML output + return HttpResponse('COOL' if status == 200 else 'SWEATY', status=status) + + def render_to_response_json(self, plugins, status): # customize JSON output + return JsonResponse( + {str(p.identifier()): 'COOL' if status == 200 else 'SWEATY' for p in plugins}, + status=status + ) +``` + +```python +# urls.py +import views + +urlpatterns = [ + # ... + url(r'^ht/$', views.HealthCheckCustomView.as_view(), name='health_check_custom'), +] +``` diff --git a/docs/src/pages/management-command.md b/docs/src/pages/management-command.md index e69de29b..c461c5b9 100644 --- a/docs/src/pages/management-command.md +++ b/docs/src/pages/management-command.md @@ -0,0 +1,20 @@ +--- +title: Management Command +pageTitle: Management command +description: How to run your health checks +--- + +You can run the Django command `health_check` to perform your health checks via the command line, +or periodically with a cron, as follow: + +```shell +python manage.py health_check +``` + +This should yield the following output: + +```shell +DatabaseHealthCheck ... working +CustomHealthCheck ... unavailable: Something went wrong! +``` +A critical error will cause the command to quit with the exit code 1. diff --git a/docs/src/pages/monitoring.md b/docs/src/pages/monitoring.md index e69de29b..760eaffb 100644 --- a/docs/src/pages/monitoring.md +++ b/docs/src/pages/monitoring.md @@ -0,0 +1,50 @@ +--- +title: External Monitoring +pageTitle: setting up monitoring +description: How to setup external monitoring +--- + +You can use tools like [Pingdom](https://www.solarwinds.com/pingdom), [StatusCake](https://www.statuscake.com/) +or other uptime robots to monitor service status. + +The `/ht/` endpoint will respond with an `HTTP 200` if all checks passed and with an `HTTP 500` +if any of the tests failed. + +## Getting machine-readable JSON reports + +If you want machine-readable status reports you can request the `/ht/ `endpoint with the Accept +HTTP header set to` application/json` or` pass format=json` as a query parameter. + +The backend will return a JSON response: + +```python +$ curl -v -X GET -H "Accept: application/json" http://www.example.com/ht/ + +> GET /ht/ HTTP/1.1 +> Host: www.example.com +> Accept: application/json +> +< HTTP/1.1 200 OK +< Content-Type: application/json + +{ + "CacheBackend": "working", + "DatabaseBackend": "working", + "S3BotoStorageHealthCheck": "working" +} + +$ curl -v -X GET http://www.example.com/ht/?format=json + +> GET /ht/?format=json HTTP/1.1 +> Host: www.example.com +> +< HTTP/1.1 200 OK +< Content-Type: application/json + +{ + "CacheBackend": "working", + "DatabaseBackend": "working", + "S3BotoStorageHealthCheck": "working" +} +``` + diff --git a/docs/src/pages/writing-your-own-checks.md b/docs/src/pages/writing-your-own-checks.md index 887f22b9..c80050d0 100644 --- a/docs/src/pages/writing-your-own-checks.md +++ b/docs/src/pages/writing-your-own-checks.md @@ -1,5 +1,53 @@ --- -title: Writing your own custom django-health-check checks -pageTitle: Writing your own custom django-health-check checks +title: Writing custom health checks +pageTitle: Writing custom health checks description: How to write your own health checks to specifically tests aspects of your system when there isn't a standard or contrib health check already available. ---- \ No newline at end of file +--- + +Custom Django health checks is necessary for implementing application-specific checks, +monitoring external dependencies, and validating legacy system integrations. + +## Template to write custom health checks + +Start with this code + +```python + +from health_check.backends import BaseHealthCheckBackend + +class MyHealthCheckBackend(BaseHealthCheckBackend): + #: The status endpoints will respond with a 200 status code + #: even if the check errors. + critical_service = False + + def check_status(self): + # The test code goes here. + # You can use `self.add_error` or + # raise a `HealthCheckException`, + # similar to Django's form validation. + pass + + def identifier(self): + return self.__class__.__name__ # Display name on the endpoint. +``` + +After writing a custom checker, register it in your app configuration: + +```python +from django.apps import AppConfig + +from health_check.plugins import plugin_dir + +class MyAppConfig(AppConfig): + name = 'my_app' + + def ready(self): + from .backends import MyHealthCheckBackend + plugin_dir.register(MyHealthCheckBackend) + +``` + +***Note:*** +The application you write the checker into should already be registered in your `INSTALLED_APPS`. + +Remember to adapt the code based on your specific application requirements and the type of health check you want to perform. \ No newline at end of file