Server Health & Monitoring

Athena continuously checks its own vital signs and exposes them so you can watch the server from a monitoring system, a script, or a browser. A lightweight liveness probe answers anonymously for load balancers and container orchestration, and a detailed report breaks health down into four components — the database, the certificate authority, the audit trail, and disk space — each with its own status.

How health checks work#

Every time a health endpoint is called, the server runs four independent checks and rolls them up into one overall status. The check is computed on demand — there is nothing to schedule and no state to reset. Because the basic probe needs no credentials, an air-gapped monitoring host can poll it without holding an Athena account.

Each component, and the server as a whole, reports one of three statuses:

Status	Meaning
`healthy`	The component is fully operational.
`degraded`	Working, but something needs attention soon — for example, a certificate approaching expiry or disk space running low.
`unhealthy`	A component has failed or crossed a critical threshold and needs action now.

The overall status is the worst of the four: if any component is unhealthy the server reports unhealthy; otherwise if any is degraded the server reports degraded; only when all four are healthy does the server report healthy.

What is checked#

The detailed report includes a per-component breakdown with a short message and, for most components, extra details such as the provider name or free disk space. The four checks are:

Component	What it verifies	Degraded when…	Unhealthy when…
Database	The server is connected to its database and can run a simple query.	—	Not connected, the test query fails, or an error is raised.
PKI	The internal certificate authority files are present and the CA certificate is still valid. See Certificates & PKI.	The CA certificate expires in under one year — plan a renewal.	The CA certificate or its key is missing, the CA has expired, or it expires in under six months — renew immediately.
Audit	The audit trail provider is initialized and ready to record events. See Audit & SIEM.	—	The audit provider is not initialized or raises an error.
Disk	Free space on the volume that holds Athena's data (where certificates and the database live).	Less than 5 GB free.	Less than 1 GB free.

The disk and PKI checks tie together

Disk space is measured on the drive that stores the certificate authority and database files — the same volume you keep on a Docker persistent mount. Keeping that volume above the 5 GB mark keeps both the disk and (indirectly) the database checks green.

The endpoints#

Health is served on the standard API port 8443 over HTTPS. There is a plain liveness path for probes and an authenticated details path for the full breakdown. The liveness endpoints return only the overall status so that anonymous callers never see internal detail; the detail endpoints return the per-component report.

Endpoint	Auth	Returns
`GET /health`	Anonymous	Overall status only — `{ "status": "healthy" }`. This is the path the container healthcheck calls.
`GET api/Health`	Anonymous	Overall status and a timestamp. Use it to confirm a server is up before signing in.
`GET api/Health/details`	Any signed-in user	The full four-component report with per-component status, message, and details.
`GET /health/details`	Operator or Admin	The same detailed report rendered by the underlying health-check engine, including how long the check took to run.

All four are part of the JWT-authenticated REST API. Send the bearer token as Authorization: Bearer <token> on the two authenticated paths; the anonymous paths take no token at all.

# Liveness — no credentials needed
curl -k https://athena.example.com:8443/health
# → {"status":"healthy"}

# Full breakdown — signed-in user
curl -k -H "Authorization: Bearer <token>" \
  https://athena.example.com:8443/api/Health/details

Checking health from PowerShell#

The Athena PowerShell module wraps these endpoints in Get-AthenaHealth. It works with or without an established session, which makes it handy for a scheduled monitoring script:

When you are connected (Connect-Athena first), it calls the authenticated detail endpoint and returns the full per-component breakdown.
When you are not connected, pass -Server to probe a server directly; it returns the overall status without component detail.

Parameters:

Parameter	Description
`-Server`	Hostname or IP of the server to check. Optional when a session is active — the connected server is used.
`-Port`	Server port. Defaults to `8443`; valid range `1`–`65535`. Connections are HTTPS only.

# Full breakdown against the connected server
Connect-Athena -Server "athena.contoso.com"
Get-AthenaHealth

# Probe a server without signing in
Get-AthenaHealth -Server "athena.contoso.com"

# Alert when the server is not healthy
$health = Get-AthenaHealth
if ($health.OverallStatus -ne "healthy") {
    Write-Warning "Athena status: $($health.OverallStatus)"
}

# Inspect individual components
$health.Database | Format-List
$health.Pki      | Format-List

Docker healthcheck#

The container image ships with a built-in Docker HEALTHCHECK that polls the anonymous /health endpoint, so docker ps and orchestration platforms can see when the server is ready and when it has gone unhealthy. It runs every 30 seconds with a 10-second timeout, allows a 5-second start-up grace period, and marks the container unhealthy after 3 consecutive failures.

You can watch it directly:

# Current health state of the container
docker inspect --format '{{.State.Health.Status}}' athena

First-boot behaviour

On first start the server creates its certificate authority, seeds the default admin account, and applies database migrations. The container reports starting until the healthcheck first returns healthy — see Installation.

Using health in monitoring#

Because the liveness endpoint needs no credentials and returns a tiny JSON body, it drops straight into most monitoring tools — an HTTP check that expects "status":"healthy" in the response is enough for an up/down alert. For richer alerting (for example, warning weeks ahead of a certificate-authority expiry), poll api/Health/details with a service account and branch on the per-component status.

Up/down & load balancers — point the probe at /health and treat anything other than healthy (or a non-200 response) as down.
Capacity — a degraded Disk component is your early warning to free space or grow the data volume before it turns unhealthy.
Certificate lifecycle — a degraded PKI component flags a CA that will expire within a year; renew it well ahead of the six-month critical window. See Certificates & PKI.
Air-gapped sites — the anonymous probe means an internal monitoring host can watch the server without an account or outbound connectivity. See Air-Gapped Operation.