Skip to main content
The Reporter sends a heartbeat to the FlowWarden Console at regular intervals (default: every 30 seconds). Each heartbeat is a Protobuf message containing a snapshot of all your Change Streams, JVM health, and deployment metadata.

​
Heartbeat Contents

message Heartbeat {
  string instance_id = 1;
  int64 timestamp = 2;
  repeated StreamStatus streams = 3;
  SystemMetrics system = 4;
  DeploymentInfo deployment = 5;
}

​
Stream Status

For each @ChangeStream in your application:
FieldTypeDescription
namestringStream name (from @ChangeStream(name = ...))
statusenumRUNNING, PAUSED, ERROR, or STOPPED
events_processedlongTotal events successfully processed
events_errorslongTotal events that caused errors
dlq_sizelongNumber of events in the dead letter queue
lag_mslongProcessing lag in milliseconds
resume_tokenbytesLatest MongoDB resume token
zonestringZone name (if configured)
avg_processing_time_msdoubleAverage handler execution time (current window)
events_per_seconddoubleThroughput (current window)
checkpointCheckpointInfoCheckpoint health (see below)

​
Checkpoint Info

FieldTypeDescription
last_seen_agelongSeconds since last event was received
last_processed_agelongSeconds since last checkpoint was persisted
events_behindlongEvents processed but not yet checkpointed
events_behind > 0 means there are processed events that haven’t been checkpointed yet. This is normal during active processing — it becomes a concern only if the value keeps growing.

​
System Metrics

JVM health collected via standard APIs (no Micrometer dependency):
FieldTypeDescription
heap_used_mblongCurrent heap usage in MB
heap_max_mblongMaximum heap size in MB
cpu_usagedoubleProcess CPU load (0.0 to 1.0, or -1.0 if unavailable)
active_threadsintNumber of active threads
cpu_usage may return -1.0 on certain JVM implementations (GraalVM Native, IBM J9) where com.sun.management.OperatingSystemMXBean is not available. The Console handles this gracefully.

​
Deployment Info

Auto-detected at startup (see Instance Identity):
FieldTypeDescription
environmentstringResolved environment name
service_namestringspring.application.name
versionstringApplication version
hostnamestringResolved hostname

​
Dynamic Interval

The Console controls the heartbeat frequency via the ACK response: 
{
  "ack": true,
  "server_time": 1706954401000,
  "next_heartbeat_in": 60
}
When next_heartbeat_in is present and greater than 0, the Reporter adjusts its interval accordingly. This allows the Console to:
  • Increase frequency during incidents (e.g. 5s)
  • Decrease frequency for idle applications (e.g. 60s)
  • Adapt based on the organization’s plan limits

​
Retry & Resilience

If a heartbeat fails (network error, Console unavailable, HTTP 5xx):
  1. Retry up to 3 times with exponential backoff: 1s, 2s, 4s
  2. Skip and continue — if all retries fail, the heartbeat is dropped and the next one is scheduled at the current interval
  3. No data loss — stream metrics are cumulative counters, so the next successful heartbeat will contain the full state
The heartbeat loop never crashes. Unexpected exceptions are caught and logged as warnings.

​
Wire Format

AspectDetail
ProtocolHTTPS POST
Endpoint{console-url}/api/heartbeat
Content-Typeapplication/x-protobuf
HeadersX-API-Key, X-Instance-Id
SerializationProtocol Buffers (binary)

​
See Also

Configuration

Adjust heartbeat interval and other Reporter settings.

Instance Identity

How the Reporter identifies your application instance.