Python SDK: live logs and status

client.apps.realtime(app_id) opens a live stream of an app’s logs, status and system events. With SquareCloud it is an iterator consumed with for; with AsyncSquareCloud it is an async iterator consumed with async for. Use it in a with / async with block so leaving the block closes the connection. Examples use the client from Creating the client. app_id is the id of one of your apps: client.account.me() lists them.

Sync
Async

with client.apps.realtime(app_id) as stream:
    for event in stream:
        if event["event"] == "logs":
            print(event["stream"], event["line"])  # "stdout" | "stderr"
        elif event["event"] == "status":
            print(event["status"].get("cpu"), event["status"].get("ram"))  # always the full, merged state
        else:
            print(event["event"], event["data"])  # "system" or "error"

async with client.apps.realtime(app_id) as stream:  # no await: realtime() is not a coroutine
    async for event in stream:
        if event["event"] == "logs":
            print(event["stream"], event["line"])  # "stdout" | "stderr"
        elif event["event"] == "status":
            print(event["status"].get("cpu"), event["status"].get("ram"))  # always the full, merged state
        else:
            print(event["event"], event["data"])  # "system" or "error"

With AsyncSquareCloud, apps.realtime(app_id) returns an AsyncRealtime directly: do not await it. A background reader thread feeds the events to your event loop, so no executor thread is held while you wait.

Events

Every event is a dict with event, data (the raw frame text) and id (None when the frame has none).

`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 (then leave the with block, which closes the connection);
you call stream.close(), from any thread, even while the loop waits for data or for a reconnection (the loop just ends, it does not raise).

close() is synchronous on both Realtime and AsyncRealtime. To keep watching past 10 minutes, open a new stream when the loop ends.

import threading

stream = client.apps.realtime(app_id)
threading.Timer(60, stream.close).start()  # stop after one minute

for event in stream:
    print(event["event"], event["data"])

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 raises a SquareCloudAPIError with NETWORK_ERROR. Each open is a GET, so a network error while opening is also retried up to max_retries times; an open that still fails raises.

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) raise on the first iteration.
The timeout only covers the open, until the response headers arrive. The stream itself has no timeout: a half-open connection (a laptop resuming from sleep) waits until you call close().

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

Python 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