Health and monitoring

Wire liveness/readiness probes to ODD Platform's /actuator/health and scrape metrics from /actuator/prometheus — what the health verdict does and does not cover.

ODD Platform ships with Spring Boot Actuator as its monitoring surface. The bundled configuration disables every actuator endpoint by default and enables exactly four: health, prometheus, env, and info. The whole /actuator/** namespace is served on the platform's regular HTTP port (8080 by default) and is reachable without authentication in every auth.type — which is what load balancers, Kubernetes probes, and Prometheus scrapers need, and also why the namespace must be network-restricted in production (see Security considerations below).

Health endpoint

GET /actuator/health returns HTTP 200 with body {"status":"UP"} while the platform is healthy, and HTTP 503 with {"status":"DOWN"} when any contributing health indicator fails. No authentication, session, or header is required in any authentication mode.

The verdict aggregates Spring Boot's standard autoconfigured health indicators for the components on the platform's classpath — in a default deployment that means connectivity of the platform's PostgreSQL database plus free disk space and a basic liveness ping. The platform registers no custom health indicators of its own, and the bundled configuration explicitly disables two of the standard ones:

• management.health.ldap.enabled: false — an unreachable LDAP server fails logins, not the health verdict.

• management.health.redis.enabled: false — see the warning below.

What a green health verdict does not tell you.

• Redis session store. With session.provider: REDIS, a Redis outage fails every authenticated request — but the health endpoint stays UP, because the Redis health indicator is disabled in the bundled defaults. If you run the REDIS session provider, set management.health.redis.enabled: true so the verdict covers your session store.

• Background subsystems. A subsystem wedged on a PostgreSQL advisory-lock collision (notifications, housekeeping, partition rotation) keeps reporting healthy — see the advisory-lock registry for the failure mode and the audit rule.

• Ingestion write path. A 200/UP does not exercise ingestion. And do not point a probe at the ingestion API instead: POST /ingestion/metrics returns 201 even for an empty no-op payload — see the metrics-ingestion caveats.

Wiring probes

The images and Compose files distributed with the platform define no health checks themselves — wiring probes is the operator's responsibility. Both examples below target the platform's default port 8080.

Kubernetes liveness and readiness probes:

livenessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
  initialDelaySeconds: 60   # first boot runs database migrations; allow extra time on the first deploy
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

Docker Compose health check:

services:
  odd-platform:
    image: ghcr.io/opendatadiscovery/odd-platform:latest
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/actuator/health"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 60s

On a fresh database the platform runs its schema migrations during startup, so the first boot takes noticeably longer than subsequent ones. Size initialDelaySeconds / start_period for the first-boot case, or a restart loop can kill the platform mid-migration.

Prometheus metrics

GET /actuator/prometheus exposes the platform's runtime metrics (JVM, HTTP server, connection pools) in the Prometheus text format, backed by the bundled Micrometer Prometheus registry. Like the health endpoint, it requires no authentication. A minimal scrape configuration:

scrape_configs:
  - job_name: odd-platform
    metrics_path: /actuator/prometheus
    static_configs:
      - targets: ["odd-platform.your-domain.com:8080"]

This endpoint is the platform's operational telemetry about itself. It is unrelated to the Metrics Ingestion feature, which ingests data-quality metrics about your datasets (and whose optional metrics.storage: PROMETHEUS backend is a separate, operator-run Prometheus instance).

Security considerations

The unauthenticated reachability that makes /actuator/health convenient for probes applies to the entire /actuator/** namespace — including env and info, which are also enabled in the bundled configuration. Canonical hardening guidance (separate management port, firewalling the path, restricting the exposed endpoint set) lives at Management endpoint exposure and credential hygiene. If you restrict the exposed set with management.endpoints.web.exposure.include, keep health (and prometheus, if you scrape it) so your probes keep working.