JavaScript SDK: live logs and status

api.apps.realtime(appId, { signal }) opens a live stream of an app’s logs, status and system events. It is an async iterable: consume it with for await. Examples use the api client from Creating the client. appId is the id of one of your apps: api.account.me() lists them.

const controller = new AbortController();

for await (const event of api.apps.realtime(appId, { signal: controller.signal })) {
    if (event.event === "logs") {
        console.log(event.stream, event.line); // "stdout" | "stderr"
    } else if (event.event === "status") {
        console.log(event.status.cpu, event.status.ram); // always the full, merged state
    } else {
        console.log(event.event, event.data); // "system" or "error"
    }
}

Events

Every event has event, data (the raw frame text) and id.

`event`	Extra fields	Description
`logs`	`stream`, `line`	One log line. The first character of `data` tells the stream (`\u0001` stdout, `\u0002` stderr); the SDK strips it into `line` and sets `stream` to `"stdout"` or `"stderr"`
`status`	`status`	Live container metrics. The first frame is complete and the next ones only carry what changed: the SDK merges them, so `status` is always the full state
`system`		Connection events such as `REALTIME_CONNECTING \| <id>`, `REALTIME_TIMEOUT` or `REALTIME_DISCONNECTED`
`error`		An error code such as `CONTAINER_NOT_FOUND`
`message`		A frame without an `event` name

The `status` object

Field	Description
`cpu`	CPU usage (%)
`cpuLimit`	Number of CPU cores allocated
`ram`	`[usedMB, limitMB]`
`status`	Container state, e.g. `running`
`netIO`	Network `{ i, o }` totals, with `new` for the latest interval
`bIO`	Disk `{ i, o }` totals
`uptime`	Unix ms of the container start

Ending the stream

The loop ends on its own when:

the server closes the connection cleanly (each connection lasts up to 10 minutes);
the server sends REALTIME_DISCONNECTED;
you break out of the loop;
you call controller.abort() (the loop just ends, it does not throw).

To keep watching past 10 minutes, open a new stream when the loop ends.

Reconnection

A dropped connection, or the server handing reconnection to the client (REALTIME_RECONNECT), reopens the stream on its own:

up to 3 times in a row; any logs or status event resets the count;
each reopen at least 5.5 s after the previous open, to stay under the API’s pace of one open per 5 seconds per app.

Past 3 failed reconnections, the loop throws a SquareCloudAPIError with NETWORK_ERROR.

Limits and errors

5 concurrent connections per account and 30 per app, across all users. Going over is 429 REALTIME_MAX_CONNECTIONS or REALTIME_MAX_CONNECTIONS_APP.
The HTTP status is checked before streaming, so these errors (and 404 for an unknown app) throw on the first iteration.
The timeout only covers the open, until the response headers arrive. The stream itself has no timeout.

Next steps

Snapshots

Back up and restore apps and databases.

Realtime API reference

The REST endpoint behind this stream.

Logs from the CLI

The same stream from the terminal.

CLI

VS Code

SDKs

JavaScript SDK: live logs and status

Events

The `status` object

Ending the stream

Reconnection

Limits and errors

Next steps

Snapshots

Realtime API reference

Logs from the CLI

​Events

​The status object

​Ending the stream

​Reconnection

​Limits and errors

​Next steps

Snapshots

Realtime API reference

Logs from the CLI

Events

The `status` object

Ending the stream

Reconnection

Limits and errors

Next steps