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 monitoring probes, 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 — on the appliance, its /data disk. Keeping that disk 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 appliance health check 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

On the appliance#

The appliance runs its own health check against /health, including the database probe. Its state shows on the VM console status screen and under Settings → Appliance → Overview.

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.

These checks answer "is the server up and are its components OK?". For performance counters (agent connections, API latency, heartbeat and database write times, CPU and memory), use the Settings → System Health tab or scrape the Prometheus /metrics endpoint — see System Health & Prometheus Metrics.