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

# Logs e métricas em tempo real (SSE)

> Abra um stream Server-Sent Events com GET /v2/apps/{app_id}/realtime para logs, métricas, status e progresso de deploy ao vivo. A conexão dura até 10 minutos.

<Info>O Playground da API está desativado para este endpoint devido à natureza das conexões SSE, que não são universalmente suportadas pelos navegadores.</Info>

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `apps:read`.

Use este endpoint sempre que precisar de uma visão ao vivo de uma aplicação em vez de fazer polling: acompanhar o progresso de um deploy, seguir os logs conforme são escritos, ou alimentar o gráfico de CPU/RAM de um dashboard sem bater repetidamente em [Obter status da aplicação](/pt-br/api-reference/endpoint/apps/status) ou [Obter logs](/pt-br/api-reference/endpoint/apps/logs) em um timer. Ele substitui os dois enquanto a conexão estiver aberta.

Internamente, abrir uma conexão aqui estabelece um único stream upstream no cluster da aplicação e o retransmite via SSE, com uma reconexão interna transparente caso esse upstream caia. Como cada conexão aberta mantém um socket por até 10 minutos, as aberturas têm limite de taxa separado dos limites de conexões simultâneas descritos abaixo: 1 abertura a cada 5 segundos por (usuário, aplicação), e 20 aberturas a cada 10 segundos por usuário somando todas as aplicações, seguidas de um cooldown curto.

## Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação cujos logs você deseja monitorar. Este ID pode ser encontrado na URL da sua aplicação no dashboard.
</ParamField>

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

Em caso de falha, a resposta incluirá um campo `code` juntamente com o status de erro, detalhando a causa.

Se a requisição for bem-sucedida, a resposta será um stream `text/event-stream` contendo o feed em tempo real da aplicação.

Cada conexão dura até **10 minutos**. Cada conta pode manter **5 conexões em tempo real simultâneas** (`REALTIME_MAX_CONNECTIONS`) e cada aplicação **30 no total entre todos os usuários** (`REALTIME_MAX_CONNECTIONS_APP`); exceder qualquer um dos limites retorna `429`.

## Estrutura do Server-Sent Events (SSE)

A resposta é um fluxo contínuo no formato `text/event-stream`. Cada mensagem é composta por um campo `event` e um campo `data`. O formato varia conforme o evento, então trate os payloads de forma defensiva.

### Tipos de evento

* `system`: Sinais de nível de protocolo. A linha `data` é um único código em maiúsculas: `REALTIME_CONNECTING | <sseId>` ao conectar, e depois qualquer um de `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT` ou `REALTIME_ERROR`.
* `logs`: Uma única linha de log cujo **primeiro caractere é um byte de identificação do stream**: `\x01` (stdout) ou `\x02` (stderr). Leia `data.charCodeAt(0)` (1 = stdout, 2 = stderr) e depois `data.slice(1)` para obter o texto. Uma linha sem esse byte de prefixo é stdout.
* `status`: Métricas do contêiner ao vivo como uma string JSON, cerca de um frame por segundo. O **primeiro frame** de cada (re)conexão é completo: `{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }` (`cpuLimit` é o número de núcleos de CPU alocados; `uptime` é o horário de início em ms epoch; `netIO.new` é bytes por segundo). **Todo frame seguinte é reduzido**, contendo apenas `{ cpu, ram, netIO, bIO }`: mescle cada um sobre o último frame completo, mantendo os valores anteriores de `cpuLimit`, `status` e `uptime`. Enquanto este stream estiver aberto, prefira-o em vez de consultar `GET /v2/apps/{app_id}/status`, que pode ficar até cerca de um minuto desatualizado para uma aplicação com um stream em tempo real aberto.
* `error`: Carrega um código de erro como `CONTAINER_NOT_FOUND`.

No exemplo abaixo, `\x01` / `\x02` representam os bytes brutos de prefixo de stdout / stderr.

<CodeGroup>
  ```text Exemplo de stream theme={"system"}
  event: system
  data: REALTIME_CONNECTING | abc123-1716000000000-deadbeef

  event: status
  data: {"cpu":12.5,"cpuLimit":1,"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>

## Erros comuns

| Código | HTTP | Significado |
| - | - | - |
| `REALTIME_MAX_CONNECTIONS` | 429 | Quem fez a chamada já possui 5 conexões em tempo real simultâneas abertas. |
| `REALTIME_MAX_CONNECTIONS_APP` | 429 | A aplicação já possui 30 conexões em tempo real simultâneas abertas somando todos os usuários. |

## Relacionados

* CLI: [`squarecloud app realtime`](/pt-br/cli-reference/logs#squarecloud-app-realtime)
* SDKs: [`api.apps.realtime()`](/pt-br/sdks/js/realtime) (JavaScript), [`client.apps.realtime()`](/pt-br/sdks/py/realtime) (Python), [`c.Apps.Realtime()`](/pt-br/sdks/go/realtime) (Go)


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