Observability & health¶
Prometheus metrics, health probes, a built-in health dashboard, and SIEM-bound audit forwarding.
What it is¶
HelixIAM exposes Prometheus metrics and a console health view so you always know how authentication is performing across your realms.
Metrics¶
Prometheus scrapes the standard endpoint. Alongside JVM and HTTP metrics, HelixIAM publishes purpose-built counters, each tagged by realm:
| Counter | Measures |
|---|---|
helix_login_total |
Login attempts / outcomes |
helix_tokens_issued_total |
Tokens issued |
helix_mfa_challenge_total |
MFA challenges raised |
helix_admin_write_total |
Administrative write operations |
Health dashboard¶
The console Health dashboard summarises component health, realm inventory, and live login/token metrics in one place:
Over the monitoring endpoints¶
The server exposes two actuator endpoints: health (with its liveness / readiness groups) and prometheus. /actuator/info is not exposed. The examples assume $HELIX_URL from Authenticating to the API.
Liveness & readiness — GET /actuator/health¶
Health is anonymous — point your load balancer and Kubernetes probes here, no session or token:
curl -s "$HELIX_URL/actuator/health"
curl -s "$HELIX_URL/actuator/health/liveness"
curl -s "$HELIX_URL/actuator/health/readiness"
Probe the group endpoints — /actuator/health/liveness and /actuator/health/readiness — to gate restarts and traffic; the Helm chart's probes do. With both stores on queue, Redis is never contacted and its health indicator is off, so readiness does not depend on it.
Scrape metrics — GET /actuator/prometheus¶
The Prometheus endpoint is not anonymous by default: without credentials it answers 401.
To let Prometheus scrape it, set HELIX_ACTUATOR_PROMETHEUS_ANONYMOUS=true (Helm: config.prometheusAnonymous) and restrict the path at the network layer — the chart's NetworkPolicy admits scrapes from the namespace you set in networkPolicy.prometheusNamespaceSelector. With an admin session (-b cookies.txt) you can read it for a quick look:
helix_db_encryption_legacy_failed_columns 0.0
helix_email_retry_queued 0.0
helix_login_total{outcome="success",realm="master"} 1.0
The purpose-built counters carry a realm tag, so a single Prometheus target gives you per-realm login, token and admin-write rates; a counter appears once it has been incremented. helix_db_encryption_legacy_failed_columns should stay 0 — see the upgrade guide.
Health dashboard API¶
The console's Health dashboard reads these admin endpoints (admin session):
curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/health"
curl -s -b cookies.txt "$HELIX_URL/admin/metrics/summary"
{"overall":"healthy","components":[{"name":"Database (PostgreSQL)","status":"up","detail":"Reads succeeding"}, …],"counts":{"applications":3,"oidcClients":3,"samlRelyingParties":0,"identityProviders":0},"checkedAt":"2026-10-13T05:00:37.372594717Z"}
{"realm":null,"loginSuccess":1,"loginFailure":0,"loginTotal":1,"loginSuccessRate":1.0,"mfaSuccess":0,"mfaFailure":0,"tokensIssued":0,"adminWrites":0}
Which release is running¶
/actuator/info is not exposed (build information is not disclosed). Check the image tag you deployed (kubectl get deploy helixiam -o jsonpath='{.spec.template.spec.containers[0].image}', or docker compose images) and that readiness is UP after a rollout.
Dashboards & alerts¶
HelixIAM does not ship Grafana dashboards or alert rules. Build them on the helix_* counters above and the standard JVM / HTTP server metrics (http_server_requests_seconds_*) that the Prometheus endpoint also exports.
Latency histograms¶
Enable HTTP latency histograms to unlock p99 panels:
Leave this off unless you need percentile latency, since histograms add metric cardinality.
Audit forwarding to SIEM¶
The audit log records administrative and authentication events and can be forwarded to your SIEM for long-term retention, correlation and alerting — pair it with admin RBAC so every write is attributable.