> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Log in Tempo Reale

> Stabilisci una connessione Server-Sent Events (SSE) per ricevere il feed in tempo reale della tua applicazione (log, metriche live, stato, avanzamento del deploy). Alla connessione vengono inviate le 200 righe di log più recenti, seguite dai nuovi aggiornamenti. La connessione può essere mantenuta per un massimo di 10 minuti.

<Info>L'API Playground è disabilitato per questo endpoint a causa della natura delle connessioni SSE, che non sono supportate universalmente dai browser.</Info>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La chiave API del tuo account. Puoi trovarla nelle [impostazioni del tuo account](https://squarecloud.app/it/account/security).
</ParamField>

### Parametri

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  L'ID dell'applicazione di cui vuoi monitorare i log. Questo ID può essere trovato nell'URL del pannello di gestione della tua applicazione.
</ParamField>

### Risposta

<ResponseField name="status" type="string">
  Indica se la chiamata è andata a buon fine. `success` in caso di successo, `error` in caso contrario.
</ResponseField>

In caso di fallimento, la risposta includerà un campo `code` insieme allo stato di errore, che ne dettaglia la causa.

Se la richiesta ha esito positivo, la risposta sarà uno stream `text/event-stream` contenente il feed in tempo reale dell'applicazione.

Ogni connessione dura fino a **10 minuti**. Ogni account può mantenere **5 connessioni realtime simultanee** (`REALTIME_MAX_CONNECTIONS`) e ogni applicazione **30 tra tutti gli utenti** (`REALTIME_MAX_CONNECTIONS_APP`); il superamento di uno dei due limiti restituisce `429`.

### Struttura dei Server-Sent Events (SSE)

La risposta è uno stream continuo in formato `text/event-stream`. Ogni messaggio è composto da un campo `event` e da un campo `data`. Le forme variano a seconda dell'evento, quindi analizza i payload in modo difensivo.

#### Tipi di Evento

* `system`: Segnali a livello di protocollo. La riga `data` è un singolo codice in maiuscolo: `REALTIME_CONNECTING | <sseId>` alla connessione, poi uno qualsiasi tra `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT` o `REALTIME_ERROR`.
* `logs`: Una singola riga di log il cui **primo carattere è un byte di identificazione dello stream**: `\x01` (stdout) o `\x02` (stderr). Leggi `data.charCodeAt(0)` (1 = stdout, 2 = stderr), poi `data.slice(1)` per il testo. Una riga senza quel byte di prefisso è stdout.
* `status`: Metriche live del container come stringa JSON, circa un frame al secondo. Il **primo frame** di ogni (ri)connessione è completo: `{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }` (`uptime` è l'orario di avvio in ms epoch; `netIO.new` è in byte al secondo). **Ogni frame successivo è ridotto**, portando solo `{ cpu, ram, netIO, bIO }` — unisci ciascuno all'ultimo frame completo, mantenendo i precedenti `cpuLimit`, `status` e `uptime`. Mentre questo stream è aperto, preferiscilo al polling di `GET /v2/apps/{app_id}/status`, che può essere fino a circa un minuto obsoleto per un'app con uno stream realtime aperto.
* `error`: Porta un codice di errore come `CONTAINER_NOT_FOUND`.

Nell'esempio seguente, `\x01` / `\x02` rappresentano i byte di prefisso grezzi stdout / stderr.

<CodeGroup>
  ```text Stream example theme={null}
  event: system
  data: REALTIME_CONNECTING | abc123-1716000000000-deadbeef

  event: status
  data: {"cpu":12.5,"cpuLimit":100,"ram":[128,512],"status":"running","netIO":{"i":2048,"o":4096,"new":{"i":64,"o":128}},"bIO":{"i":0,"o":0},"uptime":1716000000000}

  event: status
  data: {"cpu":13.1,"ram":[131,512],"netIO":{"i":2176,"o":4288,"new":{"i":72,"o":140}},"bIO":{"i":0,"o":0}}

  event: logs
  data: \x01Server listening on :3000

  event: logs
  data: \x02Error: connect ECONNREFUSED
  ```
</CodeGroup>