6.1.1. Monitor

The monitor.type endpoint provides an OpenMetrics compatible endpoint as well as health check endpoints which can signal the (un)ready and health states of the process.

This can be use useful when running behind a load balancer (such as HAProxy) or in a Kubernetes environment.

smtpd-app.yaml

monitor:
  apikeys:
    - badsecret

smtpd.yaml

monitor:
  listener:
    port: 8080

6.1.1.1. Endpoints

The following (HTTP/GET) endpoints are available.

6.1.1.1.1. /metrics

This endpoint provies data in a OpenMetrics compatible format.

Sample request

% curl http://mta1:8080/metrics -H "X-API-Key: badsecret"
# TYPE halon_monitor_ready gauge
# HELP halon_monitor_ready The current ready status (ready=1, notready=0)
halon_monitor_ready 1
# TYPE halon_monitor_healthy gauge
# HELP halon_monitor_healthy The current health status (healthy=1, unhealthy=0)
halon_monitor_healthy 1
# TYPE halon_process_pid gauge
# HELP halon_process_pid Process PID
halon_process_pid 38098
....

6.1.1.1.2. /ready

This endpoint returns a 200 OK if the service is ready (started) otherwise a 5XX error is returned. It’s a one time state transition from unready to ready once the system is started. It will not transition to unready again (unlike the /healthy endpoint). Information regarding the ready status is provided in the OpenMetrics output as well as using the halonctl process-stats command.

6.1.1.1.3. /healthy

This endpoint returns a 200 OK in if the service is ready and healthy to accept mail otherwise a 5XX error. The response body of this request may give a clue about why a system is unhealty (but the output is not meant to be used). The state may transition back and forth between unhealthy and healthy depending on the reason for the health/unheathly state. Information regarding the health status is provided in the OpenMetrics output as well as using the halonctl process-stats command.

Reason for not being ready are.

Service is not ready (see above)
Service is shutting down
Max messages affected by monitor.healthy.maxmessages.upper and monitor.healthy.maxmessages.lower
Spool free bytes affected by monitor.healthy.spoolfreebytes.upper and monitor.healthy.spoolfreebytes.lower
Spool free inodesbytes affected by monitor.healthy.spoolfreeinodes.upper and monitor.healthy.spoolfreeinodes.lower
Manually set unhealthy (halonctl health set --unhealthy or HalonMTA_health_set())

If none of the conditions currently triggered, the system is healthy.