Metadata-Version: 2.5
Name: django-healthchecks
Version: 1.6.0
Summary: Simple Django app/framework to publish health checks
Project-URL: Homepage, https://github.com/labd/django-healthchecks
Project-URL: Documentation, https://django-healthchecks.readthedocs.io/
Project-URL: Changelog, https://github.com/labd/django-healthchecks/blob/master/CHANGELOG.md
Author-email: Michael van Tellingen <michaelvantellingen@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: certifi>=2020.6.20
Requires-Dist: django>=5.2
Requires-Dist: requests>=2.24.0
Description-Content-Type: text/x-rst

===================
django-healthchecks
===================

.. image:: https://img.shields.io/pypi/v/django-healthchecks.svg
    :target: https://pypi.org/project/django-healthchecks/

.. image:: https://github.com/labd/django-healthchecks/actions/workflows/python-test.yml/badge.svg
    :target: https://github.com/labd/django-healthchecks/actions/workflows/python-test.yml

Simple Django app/framework to publish health check for monitoring purposes

Features:

* Custom checks via Python functions
* Remote healthchecks
* Heartbeat monitoring


Installation
============

.. code-block:: shell

   pip install django_healthchecks


Usage
=====

Add the following to your urls.py:


.. code-block:: python

    url(r'^healthchecks/', include('django_healthchecks.urls')),


Add a setting with the available healthchecks:

.. code-block:: python

    HEALTH_CHECKS = {
        'postgresql': 'django_healthchecks.contrib.check_database',
        'cache_default': 'django_healthchecks.contrib.check_cache_default',
        'solr': 'your_project.lib.healthchecks.check_solr',
    }


You can also include healthchecks over http. This is useful when you want to
monitor if depending services are up:

.. code-block:: python

    HEALTH_CHECKS = {
        ...
        'my_microservice': 'https://my-service.services.internal/healthchecks/',
        ...
    }


By default, http health checks will time out after 500ms. You can override this
as follows:

.. code-block:: python

    HEALTH_CHECKS_HTTP_TIMEOUT = 0.5


By default the status code is always 200, you can change this to something
else by using the `HEALTH_CHECKS_ERROR_CODE` setting:

.. code-block:: python

    HEALTH_CHECKS_ERROR_CODE = 503


You can also add some simple protection to your healthchecks via basic auth.
This can be specified per check or a wildcard can be used `*`.

.. code-block:: python

    HEALTH_CHECKS_BASIC_AUTH = {
        '*': [('admin', 'pass')],
        'solr': [],
    }


Using heartbeats
================

Heartbeats give a periodic update, to see whether an service was recently active.
When the service doesn't report back within timeout, a healthcheck can be triggered.
To use heartbeats, add the application to the ``INSTALLED_APPS``:

.. code-block:: python

    INSTALLED_APPS = [
        ...
        "django_healthchecks",
    ]

Include one of these checks:

.. code-block:: python

    HEALTH_CHECKS = {
        ...
        'heartbeats': 'django_healthchecks.contrib.check_heartbeats'
        ...
        'expired_heartbeats': 'django_healthchecks.contrib.check_expired_heartbeats',
        ...
    }

Optionally, define an initial timeout:

.. code-block:: python

    HEALTHCHECKS_DEFAULT_HEARTBEAT_TIMEOUT = timedelta(days=1)

Let your code track the beats:

.. code-block:: python

    from datetime import timedelta
    from django_healthchecks.heartbeats import update_heartbeat

    update_heartbeat("myservice.name", default_timeout=timedelta(days=2))

Or use the decorator:

.. code-block:: python

    from django_healthchecks.heartbeats import update_heartbeat_on_success

    @update_heartbeat_on_success("myservice.name", default_timeout=...)
    def long_running_task():
        ....

Each time ``update_heartbeat()`` is called, the heartbeat is reset.
When a heartbeat didn't receive an update before it's ``timeout``,
the service name be mentioned in the ``check_expired_heartbeats`` check.

Updating timeouts
~~~~~~~~~~~~~~~~~

The ``default_timeout`` parameter is only assigned upon creation. Any updates
happen through the Django admin. To update the timeout automatically on
code deployment, use the ``timeout`` parameter instead. This will replace the
stored timeout value each time the ``update_heartbeat()`` function
is called, erasing any changes made in the Django admin.



Releasing
=========

Changes are tracked with `changie <https://changie.dev/>`_. Add a changelog
entry to every pull request with a user-facing change:

.. code-block:: shell

   changie new

When entries are merged to the default branch, a release pull request is
opened (or updated) automatically. Merging that pull request tags the release,
creates the GitHub release and publishes the package to PyPI.
