# 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:

```
GET /admin/realms/{realm}/health
GET /admin/metrics/summary
```

## 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](../getting-started/api-authentication.md).

### Liveness & readiness — `GET /actuator/health`

Health is **anonymous** — point your load balancer and Kubernetes probes here, no session or token:

```bash
curl -s "$HELIX_URL/actuator/health"
curl -s "$HELIX_URL/actuator/health/liveness"
curl -s "$HELIX_URL/actuator/health/readiness"
```
```json
{"status":"UP","groups":["liveness","readiness"]}
{"status":"UP"}
{"status":"UP"}
```

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`.

```bash
curl -s -o /dev/null -w '%{http_code}\n' "$HELIX_URL/actuator/prometheus"
```
```
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:

```bash
curl -s -b cookies.txt "$HELIX_URL/actuator/prometheus" | grep '^helix_'
```
```
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](upgrade-rc8-rc9.md#6-legacy-encrypted-secrets-are-re-encrypted-at-startup).

### Health dashboard API

The console's Health dashboard reads these admin endpoints (admin session):

```bash
curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/health"
curl -s -b cookies.txt "$HELIX_URL/admin/metrics/summary"
```
```json
{"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:

```bash
HELIX_HTTP_HISTOGRAM=true
```

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](admin-roles.md) so every write is attributable.

## See also

- [Admin roles (RBAC)](admin-roles.md)
- [Backup & disaster recovery](backup.md)
- [Security hardening](security.md)
- [Configuration](../getting-started/configuration.md)