Developer Guide

Extend Hurricane with custom application health checks, business metrics, and remote debugging tools.

Custom Health Checks

Hurricane integrates directly with Django's native System Check Framework. You can register custom checks that run during /alive and /ready probes.

1. Readiness Checks (tags=["readiness"])

Readiness checks evaluate whether external dependencies (Redis, Celery brokers, 3rd party APIs) are operational:

myapp/checks.py
from django.core.checks import Error, register, Tags
import redis


@register("readiness")
def check_redis_connection(app_configs, **kwargs):
    errors = []
    try:
        client = redis.Redis(host="redis-service", port=6379, socket_timeout=1.0)
        client.ping()
    except Exception as e:
        errors.append(
            Error(
                f"Redis service unreachable: {e}",
                hint="Verify Redis service connectivity in the cluster.",
                id="myapp.E001",
            )
        )
    return errors

If check_redis_connection returns an Error, /ready responds with 500 Internal Server Error, and Kubernetes temporarily sheds traffic from the pod until Redis recovers.

2. Liveness Checks (tags=["liveness"])

Liveness checks evaluate internal process health:

myapp/checks.py
from django.core.checks import Error, register


@register("liveness")
def check_internal_worker(app_configs, **kwargs):
    errors = []
    # Verify internal worker threads or queue states
    return errors

Custom Prometheus Metrics

You can register custom application metrics that are exposed directly on /metrics:

myapp/metrics.py
from hurricane.metrics import CalculatedMetric, CounterMetric
from myapp.models import Order


class ActiveOrdersMetric(CalculatedMetric):
    """Current number of active processing orders."""

    code = "active_orders_count"

    @classmethod
    def get_value(cls, *args):
        return Order.objects.filter(status="processing").count()


class UserSignupCounter(CounterMetric):
    """Total user registrations."""

    code = "user_signups_total"

Increment counter in your views:

UserSignupCounter.increment()

Remote Debugging in Kubernetes

Debugging containerized Django applications in a remote Kubernetes cluster is easy with Hurricane's built-in DAP debugger support:

VS Code (Debugpy)

Start Hurricane with the --debugger flag:

python manage.py serve --debugger --debugger-port=5678

Add a configuration to .vscode/launch.json:

{
  "name": "Attach: Remote Hurricane",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "localhost",
    "port": 5678
  },
  "pathMappings": [
    {
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app"
    }
  ]
}

Port-forward the debugger port (kubectl port-forward pod/my-pod 5678:5678) and press F5 in VS Code!

JetBrains PyCharm

Start Hurricane pointing to your PyCharm debug server:

python manage.py serve --pycharm-host=host.docker.internal --pycharm-port=8071
Edit this page on GitHub
Table of Contents