Skip to main content
FlowWarden integrates with Spring Boot Actuator to expose stream health and a management endpoint. This is auto-configured when spring-boot-starter-actuator is on the classpath.

​
Prerequisites

Add the Actuator starter to your project: 
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

implementation 'org.springframework.boot:spring-boot-starter-actuator'
No additional FlowWarden configuration is needed — FlowWardenActuatorAutoConfiguration activates automatically via @ConditionalOnClass(Endpoint.class).

​
Health Indicator

FlowWarden contributes a flowWarden component to /actuator/health: 
{
  "status": "UP",
  "components": {
    "flowWarden": {
      "status": "UP",
      "details": {
        "streams": 3,
        "healthy": 3
      }
    }
  }
}

​
Health Logic

The health indicator considers only streams that are both enabled and autoStart:
ConditionStatus
All enabled + autoStart streams are runningUP
At least one enabled + autoStart stream is stoppedDOWN
No streams registeredUP
Stream is disabled (enabled = false)Not counted
Stream has autoStart = falseNot counted
Streams with autoStart = false are excluded from health checks because they are expected to be started manually or by the FlowWarden Console.

​
Configuration

To see health details, configure Actuator:
application.yml
management:
  endpoint:
    health:
      show-details: always  # or "when-authorized"
  endpoints:
    web:
      exposure:
        include: health, flowwarden

​
Custom Endpoint

FlowWarden exposes a dedicated endpoint at /actuator/flowwarden.

​
GET /actuator/flowwarden

Returns the status of all registered streams with detailed information per stream: 
{
  "streams": {
    "order-stream": {
      "status": "UP",
      "mode": "SINGLE_LEADER",
      "lastEventTime": "2024-01-15T10:35:45.123Z"
    },
    "analytics-stream": {
      "status": "UP",
      "mode": "ALL_INSTANCES",
      "lastEventTime": null
    },
    "legacy-stream": {
      "status": "DOWN",
      "mode": "SINGLE_LEADER",
      "lastEventTime": "2024-01-15T09:12:03.456Z"
    }
  },
  "healthy": false
}
FieldTypeDescription
streamsMap<String, Object>Each stream name mapped to its status object
streams.*.statusString"UP" if the stream is running, "DOWN" otherwise
streams.*.modeStringDeployment mode: ALL_INSTANCES or SINGLE_LEADER
streams.*.lastEventTimeString?ISO-8601 timestamp of the last processed event, or null if no event has been received yet
healthybooleantrue if all enabled + autoStart streams are running
Use the healthy field for Kubernetes readiness probes or load balancer health checks.

​
Lifecycle Actions

FlowWarden provides three lifecycle actions via POST requests:
EndpointActionDescription
POST /actuator/flowwarden/{streamName}/stopstoppedStops a running stream
POST /actuator/flowwarden/{streamName}/startstartedStarts a stopped stream
POST /actuator/flowwarden/{streamName}/restartrestartedStops and restarts a stream

​
Stop a stream

curl -X POST http://localhost:8080/actuator/flowwarden/order-stream/stop

{
  "stream": "order-stream",
  "action": "stopped",
  "running": false
}

​
Start a stream

curl -X POST http://localhost:8080/actuator/flowwarden/order-stream/start

{
  "stream": "order-stream",
  "action": "started",
  "running": true
}

​
Restart a stream

curl -X POST http://localhost:8080/actuator/flowwarden/order-stream/restart

{
  "stream": "order-stream",
  "action": "restarted",
  "running": true
}
Lifecycle actions take effect immediately. Use with caution in production — stopping a stream means events will be queued in MongoDB until the stream is restarted. Checkpoint ensures no events are lost on restart.
Attempting an unsupported action returns an error: 
{
  "stream": "order-stream",
  "error": "Unsupported action 'pause'. Available actions: stop, start, restart."
}

​
Architecture

​
Auto-Configuration

FlowWardenActuatorAutoConfiguration registers two beans:
BeanClassPurpose
flowWardenEndpointFlowWardenEndpointCustom /actuator/flowwarden endpoint
flowWardenHealthIndicatorFlowWardenHealthIndicatorHealth contributor to /actuator/health
The auto-configuration is conditional:
  • Requires spring-boot-actuator on the classpath (@ConditionalOnClass(Endpoint.class))
  • Loads after FlowWardenAutoConfiguration to ensure FlowWardenStreamManager and StreamRegistry are available

​
Disabling

Both beans can be disabled independently via standard Spring Boot properties:
application.yml
management:
  # Disable the /actuator/flowwarden endpoint
  endpoint:
    flowwarden:
      enabled: false
  # Disable the FlowWarden health indicator
  health:
    flowwarden:
      enabled: false
If you don’t have spring-boot-starter-actuator in your dependencies, neither bean is created — no configuration needed.

​
Kubernetes Integration

​
Readiness Probe

Use the health endpoint as a readiness probe to prevent traffic from reaching an instance with unhealthy streams:
deployment.yml
readinessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
  initialDelaySeconds: 15
  periodSeconds: 10

​
Liveness Probe

For liveness, you can use the dedicated FlowWarden endpoint:
deployment.yml
livenessProbe:
  httpGet:
    path: /actuator/flowwarden
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 15

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  template:
    spec:
      containers:
        - name: app
          image: my-service:latest
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /actuator/health
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /actuator/flowwarden
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 15
          env:
            - name: MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE
              value: "health,flowwarden"
            - name: MANAGEMENT_ENDPOINT_HEALTH_SHOW_DETAILS
              value: "always"

​
Best Practices

  • Expose only what you need — limit management.endpoints.web.exposure.include to health,flowwarden in production
  • Secure endpoints — use Spring Security to restrict access to management endpoints, especially lifecycle actions (stop, start, restart)
  • Use healthy for probes — the healthy field in the FlowWarden endpoint is a single boolean suitable for automated checks
  • Monitor lastEventTime — a null or stale lastEventTime can indicate that no events are being received, even if the stream is UP
  • Prefer restart over stop + start — the restart action is atomic and ensures the stream is properly recycled

​
See Also

@ChangeStream

Stream registration and configuration

Configuration

YAML properties reference