Health service

The container is able to expose an HTTP health service, which offers startup, liveness and readiness probes. This may be especially helpful if you are deploying the container into a Kubernetes cluster. If you are using Kubernetes, we recommend that you also refer to the Kubernetes documentation around liveness and readiness probes (https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).

The health service is enabled by default and should run as a subprocess of the main entrypoint to the container.

Endpoints

The health service offers three endpoints:

The code examples below use the HTTPie tool

/started

This endpoint provides a startup probe. It can be queried using an HTTP GET request.

This probe indicates whether all services in the container have successfully started. Once it returns a successful response code, it should never return an unsuccessful response code later.

Possible responses:

• 200 if all of the services in the container have successfully started.
• 503 otherwise.

A JSON object is also returned in the body of the response, indicating the status.

Example:

$ http get address.of.container:8001/started
HTTP/1.0 200 OK
Content-Type: application/json
Date: Mon, 16 Mar 2020 17:28:46 GMT
Server: BaseHTTP/0.6 Python/3.5.2

{
    "started": true
}

/live

This endpoint provides a liveness probe. It can be queried using an HTTP GET request.

This probe indicates whether all services in the container are active. The services in the container send regular updates to the health service, if they don't send an update for more than 10 seconds then they will be marked as 'dead' and this endpoint will return an unsuccessful response code. For example, if the WebSocket server in the container was to crash, this endpoint should indicate that.

Possible responses:

• 200 if all of the services in the container have successfully started, and have recently sent an update to the health service.
• 503 otherwise.

A JSON object is also returned in the body of the response, indicating the status.

Example:

$ http get address.of.container:8001/live
HTTP/1.0 200 OK
Content-Type: application/json
Date: Mon, 16 Mar 2020 17:36:35 GMT
Server: BaseHTTP/0.6 Python/3.5.2

{
    "alive": true
}

/ready

This endpoint provides a readiness probe. It can be queried using an HTTP GET request.

This probe indicates whether the container is currently transcribing something; if the server is handling at least one audio stream then it is considered not ready.

We recommend limiting our container to one audio stream at a time, and using this probe as a scaling mechanism. That said, the container can handle multiple concurrent audio streams.

Note: The readiness check is accurate within a 2 second resolution. If you do use this probe for load balancing, be aware that bursts of traffic within that 2 second window could all be allocated to a single container since it's readiness state will not change.

Possible responses:

• 200 if the container is not currently transcribing audio.
• 503 otherwise.

A JSON object is also returned in the body of the response, indicating the status.

Example:

$ http get address.of.container:8001/ready
HTTP/1.0 200 OK
Content-Type: application/json
Date: Mon, 16 Mar 2020 17:37:00 GMT
Server: BaseHTTP/0.6 Python/3.5.2

{
    "ready": true
}