> ## 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.

# SDK JavaScript: logs e status ao vivo

> Acompanhe ao vivo os logs, o status e os eventos de sistema de uma aplicação com api.apps.realtime(), um async iterable que se reconecta sozinho.

`api.apps.realtime(appId, { signal })` abre um stream ao vivo dos logs, do status e dos eventos de sistema de uma aplicação. É um **async iterable**: consuma-o com `for await`.

Os exemplos usam o cliente `api` de [Criando o cliente](/pt-br/sdks/js/client#criando-o-cliente). `appId` é o id de uma das suas aplicações: [`api.account.me()`](/pt-br/sdks/js/client#conta) lista todas.

```typescript theme={"system"}
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"
    }
}
```

## Eventos

Todo evento tem `event`, `data` (o texto bruto do frame) e `id`.

| `event` | Campos extras | Descrição |
| - | - | - |
| `logs` | `stream`, `line` | Uma linha de log. O primeiro caractere de `data` indica o stream (`\u0001` stdout, `\u0002` stderr); o SDK o remove em `line` e define `stream` como `"stdout"` ou `"stderr"` |
| `status` | `status` | Métricas do container ao vivo. O primeiro frame é completo e os seguintes trazem apenas o que mudou: o SDK os mescla, então `status` é sempre o estado completo |
| `system` | | Eventos de conexão como `REALTIME_CONNECTING \| <id>`, `REALTIME_TIMEOUT` ou `REALTIME_DISCONNECTED` |
| `error` | | Um código de erro como `CONTAINER_NOT_FOUND` |
| `message` | | Um frame sem nome de `event` |

### O objeto `status`

| Campo | Descrição |
| - | - |
| `cpu` | Uso de CPU (%) |
| `cpuLimit` | Número de núcleos de CPU alocados |
| `ram` | `[usedMB, limitMB]` |
| `status` | Estado do container, por exemplo `running` |
| `netIO` | Totais de rede `{ i, o }`, com `new` para o intervalo mais recente |
| `bIO` | Totais de disco `{ i, o }` |
| `uptime` | Unix ms do início do container |

## Encerrando o stream

O loop termina sozinho quando:

* o servidor fecha a conexão de forma limpa (cada conexão dura até **10 minutos**);
* o servidor envia `REALTIME_DISCONNECTED`;
* você sai do loop com `break`;
* você chama `controller.abort()` (o loop simplesmente termina, sem lançar erro).

Para continuar acompanhando além de 10 minutos, abra um novo stream quando o loop terminar.

## Reconexão

Uma conexão perdida, ou o servidor delegando a reconexão ao cliente (`REALTIME_RECONNECT`), reabre o stream sozinho:

* até **3 vezes seguidas**; qualquer evento `logs` ou `status` zera a contagem;
* cada reabertura ocorre pelo menos **5,5 s** após a abertura anterior, para respeitar o ritmo da API de uma abertura a cada 5 segundos por aplicação.

Após 3 reconexões falhas, o loop lança um `SquareCloudAPIError` com `NETWORK_ERROR`.

## Limites e erros

* **5** conexões simultâneas por conta e **30** por aplicação, somando todos os usuários. Ultrapassar resulta em 429 `REALTIME_MAX_CONNECTIONS` ou `REALTIME_MAX_CONNECTIONS_APP`.
* O status HTTP é verificado antes do streaming, então esses erros (e o 404 para uma aplicação desconhecida) são lançados na primeira iteração.
* O timeout cobre apenas a abertura, até os headers da resposta chegarem. O stream em si não tem timeout.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Snapshots" icon="clock-rotate-left" href="/pt-br/sdks/js/snapshots">
    Faça backup e restaure aplicações e bancos de dados.
  </Card>

  <Card title="Referência da API de tempo real" icon="code" href="/pt-br/api-reference/endpoint/apps/realtime">
    O endpoint REST por trás deste stream.
  </Card>

  <Card title="Logs pela CLI" icon="terminal" href="/pt-br/cli-reference/logs">
    O mesmo stream pelo terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.