Skip to main content

Live Channel

The live channel is an optional outbound WebSocket connection that a SLAW instance opens to stream fact events in real time. It activates only when an Operator is viewing the instance's drill-down screen in Botfather, and closes automatically when the session ends.

Prerequisites: Familiarity with the Reporting Protocol and its directive system. The live channel is activated via a directive.

Overview​

Under normal operation, the tower receives data via the polling sync endpoint (approximately every 60 seconds). The live channel supplements this with a persistent WebSocket stream for the duration of an active drill-down, giving the Operator a real-time view of cost events, run events, and activity.

The instance opens the connection — the tower never initiates it. The channel carries only the same fact events that the sync endpoint already sends; it does not expose any additional data.

Activation and deactivation​

The tower signals the instance to open or close the channel via directives returned in heartbeat or sync responses.

DirectiveEffect
request_live_stream with durationSecInstance opens the WebSocket and streams for up to durationSec seconds.
stop_live_streamInstance closes the WebSocket immediately if open.

The instance should not hold the connection open beyond the requested duration. If the directive is not renewed before durationSec elapses, the instance closes the socket.

Connection​

The instance connects to:

wss://<tower-host>/api/ingest/v1/live

Authentication is part of the handshake — the instance sends a hello frame immediately after the WebSocket connection is established.

Hello frame​

{
  "type": "hello",
  "protocolVersion": 1,
  "apiKey": "<instance-api-key>"
}
FieldDescription
typeAlways "hello".
protocolVersionMust be 1.
apiKeyThe instance's API key (same credential used on HTTPS endpoints).

Acknowledgement​

The tower responds with an ack frame:

{
  "type": "ack",
  "subscribed": true
}

subscribed: false means the tower accepted the connection but is not currently serving a drill-down for this instance (for example, the Operator navigated away between the directive and the connection). The instance should close the socket gracefully.

Streaming frames​

After a successful ack, the instance streams fact events as they occur:

Fact frame​

{
  "type": "fact",
  "event": {
    "type": "cost_event",
    "localId": "cost-1002",
    ...
  }
}

The event field is a fact event — the same cost_event, run_event, or activity_event that would appear in a sync batch.

Ping frame​

{
  "type": "ping"
}

The instance sends a ping frame periodically to keep the connection alive through proxies and load balancers. The tower does not send pings — the instance is responsible for keepalive.

Relationship to sync​

The live channel and the sync endpoint report the same fact events. The instance should not deduplicate between them at the source — the tower handles deduplication server-side using localId. Fact events that arrive via the live channel before the next sync batch are stored immediately; the batch's copy is deduplicated on receipt.

When to use the live channel​

ScenarioRecommendation
Normal fleet monitoringUse the polling sync endpoint. The ≈60-second cadence is sufficient for Fleet View and cost analytics.
Active drill-down in the tower UIThe live channel is activated automatically by the request_live_stream directive when an Operator opens instance detail. No manual action is needed.
High-frequency run environmentsThe live channel is still triggered by the tower on demand; the instance does not self-activate it.

The live channel is optional — instances that set "liveStream": false in their enrollment capabilities will not receive request_live_stream directives.

Next steps​