Pyjoyment.Plugin.Health - Liveness and readiness plugin¶
# Pyjoyment
app.plugin('Health')
# Pyjoyment.Lite
plugin('Health')
# The checks of readiness, of a function, a coroutine function or one that returns a promise
app.plugin('Health', checks={'db': lambda c: db.ping(), 'queue': queue_ready_p}, timeout=2)
# A check that another plugin adds
app.health.check('cache', lambda c: cache.connected)
Pyjoyment.Plugin.Health answers the probes of containers and
orchestrators, as the liveness, readiness and startup probes of Kubernetes,
the probes of Cloud Run, the health checks of load balancers and the
HEALTHCHECK of Docker, with the endpoints of Kubernetes itself.
GET /livezLiveness:
200 OKwithokwhile the server answers, as a server whose event loop is blocked does not answer. It has no checks of the application, as an orchestrator restarts a container whose liveness fails, and a database that is down does not get up with it.GET /healthzThe same as
/livez, under the name of the probes of Docker and of load balancers.GET /readyzReadiness:
200 OKwithokonce the checks of the application pass, and503 Service Unavailablewith the list of the checks while one of them fails, so that an orchestrator or a load balancer sends the requests to another instance. The checkshutdownfails from the moment that the server stops gracefully, also during itsshutdown_delay, asPyjo.IOLoop.Pyjo_IOLoop.is_stoppingof the event loop of the thread,Pyjo.IOLoop.singleton, which is the one of every server of Pyjoyment, and its workers, tells: a client whose connection is kept alive gets503with its last response.
The checks run at the same time, each with a timeout, and a check passes
unless it raises an exception, returns False, or returns a promise, a
coroutine or another awaitable that is rejected, is fulfilled with False,
or does not settle within its timeout. The reason of a failure goes to the
log, as the warn message Health check "db" failed: ..., not to the
response, which withholds it.
A query of verbose lists the checks on success too, exclude leaves a
check out, as many times as there are checks to leave out, and a check of its
own is under the name of the endpoint, as /readyz/db, as Kubernetes has
them.
$ curl 'http://127.0.0.1:3000/readyz?verbose'
[+]shutdown ok
[+]db ok
readyz check passed
$ curl 'http://127.0.0.1:3000/readyz?exclude=db'
ok
$ curl -i 'http://127.0.0.1:3000/readyz/db'
HTTP/1.1 503 Service Unavailable
...
[-]db failed: reason withheld
readyz check failed
The endpoints are answered in a hook of around_dispatch, before the hooks
of before_dispatch, the static files and the routes, so that a probe is
cheap, is not logged but on the level trace, and is answered also where a
hook rejects it, as Pyjoyment.Plugin.AllowedHosts would reject the
Host of the address of a pod, which a probe of Kubernetes sends. A hook of
around_dispatch that the application registers before the plugin wraps
the probes too.
See Pyjoyment.Plugins for a list of plugins that are available by
default.
Options¶
Pyjoyment.Plugin.Health supports the following options.
checks
app.plugin('Health', checks={'db': lambda c: db.ping()})
The checks of readiness, the names and the functions that take the
controller of the probe, defaults to none.
healthz
app.plugin('Health', healthz='/health')
app.plugin('Health', healthz=None)
The path of the alias of liveness, defaults to ``/healthz``, ``None``
leaves it out.
livez
app.plugin('Health', livez='/-/live')
The path of liveness, defaults to ``/livez``, ``None`` leaves it out.
readyz
app.plugin('Health', readyz='/-/ready')
The path of readiness, defaults to ``/readyz``, ``None`` leaves it out.
timeout
app.plugin('Health', timeout=0.5)
The time in seconds that a check may take, defaults to ``1``, the
timeout of a probe of Kubernetes.
Helpers¶
Pyjoyment.Plugin.Health implements the following helpers.
health.check
app.health.check('db', lambda c: db.ping())
app.health.check('search', search_ready_p, timeout=5)
Add a check of readiness, with a timeout of its own, or replace the
check of the name, as a plugin that connects to a service does.
health.path
path = c.health.path('livez')
The path of an endpoint, ``livez``, ``readyz`` or ``healthz``, or
``None`` for one that is left out, as
:mod:`Pyjoyment.Command.Author.generate.dockerfile` takes it for the
``HEALTHCHECK`` of the image.
See also¶
Pyjoyment, https://mojolicious.org.
It has no counterpart in Mojolicious.
Classes¶
- class Pyjoyment.Plugin.Health.Pyjoyment_Plugin_Health[source]¶
Pyjoyment.Plugin.Healthinherits all methods fromPyjoyment.Pluginand implements the following new ones.- register(app: Pyjoyment_App, conf: dict[str, Any] | None = None) None[source]¶
plugin.register(Pyjoyment.new()) plugin.register(Pyjoyment.new(), {'checks': {'db': lambda c: True}})
Register the hook and the helpers in
Pyjoymentapplication.