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, 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. A check that returns a value has run to its end before its
timeout starts, so the timeout does not bound it: it blocks the event loop
while it runs, as any code that blocks does, and the timeouts of its own
client bound it, as connect_timeout of a database, and a library that
refuses a running loop of asyncio, as the ORM of Django, runs in
Pyjo.IOLoop.blocking(). 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. So an endpoint takes the path from the routes of the
application, and from an application that Pyjoyment.Plugin.Mount
mounts: one with a /healthz of its own, which its monitors request, keeps
it with healthz=None.
A server whose workers serve one connection at a time, as prefork -c 1
for an application that blocks, keeps a probe in the backlog while every
worker is busy, so that a liveness probe of HTTP restarts a container that is
only busy. Its liveness probe connects to the port, as tcpSocket of
Kubernetes, which the kernel accepts into the backlog, as
Pyjoyment.Command.Author.generate.kubernetes makes it with
--liveness-probe, and /readyz stays its readiness probe.
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 of a promise, a coroutine or another
awaitable 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.