Health Checks

All Java-based Causet services expose Spring Boot Actuator’s /actuator/health endpoint. Use this for ECS container health checks, ALB target group health checks, and uptime monitoring.

Health endpoint

GET /actuator/health

Response when healthy:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "PostgreSQL",
        "validationQuery": "isValid()"
      }
    },
    "kafka": {
      "status": "UP"
    },
    "s3": {
      "status": "UP"
    },
    "redis": {
      "status": "UP"
    },
    "diskSpace": {
      "status": "UP"
    }
  }
}

Response when unhealthy (HTTP 503):

{
  "status": "DOWN",
  "components": {
    "db": {
      "status": "DOWN",
      "details": {
        "error": "Connection refused"
      }
    }
  }
}

Health indicators per service

Service startup times

Java services take time to initialize before they can respond to health checks. Set startPeriod / initialDelaySeconds accordingly:

These times are for cold starts. Subsequent starts with a warm JVM class-data-sharing cache are faster.

ECS health check configuration

In ECS task definitions, configure health checks on each container:

"healthCheck": {
  "command": [
    "CMD-SHELL",
    "curl -f http://localhost:8080/actuator/health || exit 1"
  ],
  "interval": 30,
  "timeout": 5,
  "retries": 3,
  "startPeriod": 90
}

Adjust port and startPeriod per the table above.

If a health check fails retries times consecutively, ECS marks the container as unhealthy and replaces the task. ECS respects startPeriod before beginning to count failures, so a slow-starting service is not killed during initialization.

Projection worker health check

The projection worker has no exposed port. It binds an internal health endpoint on port 8083 (not mapped to the host). In ECS, run the health check inside the container:

"healthCheck": {
  "command": [
    "CMD-SHELL",
    "curl -f http://localhost:8083/actuator/health || exit 1"
  ],
  "interval": 30,
  "timeout": 5,
  "retries": 3,
  "startPeriod": 120
}

In Docker Compose, use docker exec:

docker exec causet-projection-worker \
  curl -s http://localhost:8083/actuator/health | jq .status

ALB target group health checks

Configure ALB target groups to check the /actuator/health path:

resource "aws_lb_target_group" "runtime" {
  name        = "causet-runtime-tg"
  port        = 8080
  protocol    = "HTTP"
  target_type = "ip"
 
  health_check {
    path                = "/actuator/health"
    healthy_threshold   = 2
    unhealthy_threshold = 3
    interval            = 30
    timeout             = 5
    matcher             = "200"
  }
}

The ALB will route traffic only to healthy targets. During a rolling deploy, new tasks are not added to the target group until their health check passes.

Readiness vs liveness

Spring Boot Actuator provides two additional endpoints for Kubernetes-style readiness and liveness probes:

GET /actuator/health/readiness   → { "status": "ACCEPTING_TRAFFIC" | "REFUSING_TRAFFIC" }
GET /actuator/health/liveness    → { "status": "CORRECT" | "BROKEN" }

For ECS, the single /actuator/health endpoint is sufficient — ECS does not distinguish readiness and liveness. Use the separate endpoints if you deploy on Kubernetes.

Monitoring health in production

Set up external uptime monitoring against the ALB endpoints:

https://api.yourdomain.com/actuator/health   (causet-runtime-service via ALB)
https://query.yourdomain.com/actuator/health (causet-query-service via ALB)
https://saas.yourdomain.com/actuator/health  (causet-saas-cloud via ALB)

Configure Grafana alerting or PagerDuty to alert when any health endpoint returns a non-200 status or status: DOWN.

Health check failures: what to do

When a health check fails:

1. Check /actuator/health to identify which component is DOWN
2. For db: DOWN: check network connectivity to the database, check RDS status
3. For kafka: DOWN: check Kafka broker status, check security group rules
4. For s3: DOWN: check S3/MinIO connectivity, check IAM permissions
5. Check service logs for the error message that caused the component to report DOWN
6. In ECS, the unhealthy task is replaced automatically — watch for the replacement to become healthy