Heartbeat payload

The agent emits a heartbeat to the cloud on a fixed interval (typically every 30 seconds). The payload is the agent's view of its own runtime state. The cloud uses the payload to compute 24-hour uptime, restart counts, and lag alerts.

Endpoint

POST <CLOUD_SERVER_URL>/api/agent/heartbeat
Authorization: provided via Agent-Key header (key transport detail)
Content-Type: application/json

Body

{
  "version": "1.2.3",
  "uptime_seconds": 12345,
  "buffer_size": 0,
  "buffer_oldest_age_seconds": 0,
  "queue_depth": 0,
  "queue_oldest_age_seconds": 0,
  "queue_capacity": 10000,
  "agent_started_at": "2026-05-09T12:00:00Z",
  "source_types_active": ["prometheus", "http", "tcp"]
}

Field reference

Field	Type	Meaning
`version`	string	Build-time version of the agent.
`uptime_seconds`	integer	Wall-clock seconds since process start.
`buffer_size`	integer	Legacy alias for `queue_depth`. Accepted by older cloud builds; pre-21.5 fallback.
`buffer_oldest_age_seconds`	integer	Legacy alias for `queue_oldest_age_seconds`.
`queue_depth`	integer	Pushes currently waiting in the local queue.
`queue_oldest_age_seconds`	integer	Age of the oldest pending push, in seconds.
`queue_capacity`	integer	Hard cap on the queue (`BUFFER_MAX_ROWS`).
`agent_started_at`	ISO timestamp	When the process started. The cloud uses changes to this value to detect restarts.
`source_types_active`	string[]	Distinct source types the agent has actually run since boot.

Lag and uptime alerts

The cloud's heartbeat receiver runs two state machines per agent:

agent.lag_high: opens when queue_depth > 1000 or queue_oldest_age_seconds > 300. Clears when both signals stay below threshold for 60 seconds.
agent.uptime_degraded: opens when uptime over the last 24 hours falls below 95%. Same 60-second clear hysteresis.

These signals surface in the cloud console's agent detail page and as agent.offline webhook events when subscribed.

Versioning

The payload shape is part of the cloud-agent wire contract, maintained in the public @observer/protocol package. Field additions are additive; field removals require a major version bump on @observer/protocol.