Liveness probes

The purpose of liveness probes

Without any kind of probes set up for your application, the only failure scenario where your app will be considered as not working correctly is if the process exits on startup or any time during the application runtime. For example, if you run npm start but the application secrets are missing from the environment, most applications' processes will immediately exit. The operating system could also kill the process due to lack of memory.

Liveness probes can help you recover the application from a broken state when only restart can solve the problem. The application gets probed every few seconds to determine if the server can respond. If a timeout or error response is received instead of a success status code, the app is considered to be in a dead state (e.g. caught in an infinite loop due to an edge-case and developer error) and gets restarted.

This helps your application keep handling traffic despite an issue that causes it to lock, which gives you time to fix the underlying issue without impacting company operations (as much).

Implementation of liveness probes in your application

In order for your application to be covered by liveness probes, you need to ensure that it responds with a HTTP 200 OK status code to a GET request on a [your app URL]/healthz endpoint.

In the case of the Alokai middleware - as of version 3.0.0 of the @vue-storefront/middleware package, a liveness probe is enabled by default. You can launch the middleware locally and send a GET request to http://localhost:4000/healthz endpoint. The response will be a HTTP 200 OK containing the body "ok".

In the case of the frontend apps, /healthz endpoints are also present in Nuxt and Next templates generated from the Alokai CLI. If you will be deploying your own custom fronted app to Alokai Cloud, and your app is not generated from Alokai CLI, you will need to add the /healthz endpoint manually.

The below instructions help you create a simple /healthz endpoint that responds with a HTTP 200 OK status code and the text ok in the response body. You may be tempted to instead make /healthz a real application route in your app, which if queried will respond with the HTML of your actual application. At first glance it may seem more robust, as in theory it tests a larger part of your application stack.

In reality, requesting a full app route as part of a liveness check - especially during periods of heavy traffic - can lead to new connection being opened that will never be resolved. A full page app can take hundreds of miliseconds to respond and contain a few kilobytes of payload. The simple route described below will respond in a few miliseconds with a two byte body size.

Do not make /healthz or /readyz a full app route. Instead keep it as simple as possible, by following the instructions below. Do not consider liveness probes as a fully fledged application smoke test, but as a simple check if the app can serve a basic HTTP request.

Nuxt

In Nuxt, to create a /healthz endpoint, use server endpoints. Create a [Nuxt fronted app folder]/server/routes/healthz.ts file with the following contents:

server/routes/healthz.ts

export default defineEventHandler(() => 'ok');

Next: App router

If using Next.js with app router, use route handlers:

Create a [Next app directory]/app/healthz/route.ts file

Paste the following content inside

app/healthz/route.ts

import { NextResponse } from 'next/server';

export function GET() {
  return NextResponse.json({ status: 'ok' }, { status: 200 });
}

Next: Pages router

If using Next.js with pages router, use rewrites together with API routes:

Add the following code to your next.config.js:

next.config.js

module.exports = {
  // ...
  async rewrites() {
    return [
      {
        source: '/healthz',
        destination: '/api/healthz',
      },
    ];
  },
}

This is necessary because by default Next's API routes have an /api subpath, but we need it to be /healthz and not /api/healthz.

Create a [Next app directory]/pages/api/healthz.ts file

Paste the following content inside:

pages/api/healthz.ts

import { NextApiRequest, NextApiResponse } from 'next';

export default function handler(_req: NextApiRequest, res: NextApiResponse) {
  res.status(200).send('ok');
}