> ## 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 en temps réel

> Établissez une connexion Server-Sent Events (SSE) pour recevoir le flux temps réel de votre application (logs, métriques en direct, statut, progression du deploy). À la connexion, les 200 lignes de logs les plus récentes sont envoyées, suivies des nouvelles mises à jour. La connexion peut être maintenue jusqu'à 10 minutes.

<Info>Le Playground de l'API est désactivé pour cet endpoint en raison de la nature des connexions SSE, qui ne sont pas universellement prises en charge par les navigateurs.</Info>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clé d'API de votre compte. Vous pouvez la trouver dans les [paramètres de votre compte](https://squarecloud.app/fr/account/security).
</ParamField>

### Paramètres

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  L'ID de l'application dont vous souhaitez surveiller les logs. Cet ID se trouve dans l'URL du panneau de gestion de votre application.
</ParamField>

### Réponse

<ResponseField name="status" type="string">
  Indique si l'appel a réussi. `success` en cas de succès, `error` sinon.
</ResponseField>

En cas d'échec, la réponse inclura un champ `code` accompagné du statut d'erreur, détaillant la cause.

Si la requête réussit, la réponse sera un flux `text/event-stream` contenant le flux temps réel de l'application.

Chaque connexion dure jusqu'à **10 minutes**. Chaque compte peut maintenir **5 connexions temps réel simultanées** (`REALTIME_MAX_CONNECTIONS`) et chaque application **30 tous utilisateurs confondus** (`REALTIME_MAX_CONNECTIONS_APP`) ; dépasser l'une ou l'autre renvoie un `429`.

### Structure des Server-Sent Events (SSE)

La réponse est un flux continu au format `text/event-stream`. Chaque message est composé d'un champ `event` et d'un champ `data`. Les structures varient selon l'événement, analysez donc les charges utiles de manière défensive.

#### Types d'événements

* `system` : signaux au niveau du protocole. La ligne `data` est un unique code en majuscules : `REALTIME_CONNECTING | <sseId>` à la connexion, puis l'un de `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT` ou `REALTIME_ERROR`.
* `logs` : une seule ligne de log dont le **premier caractère est un octet d'identifiant de flux** : `\x01` (stdout) ou `\x02` (stderr). Lisez `data.charCodeAt(0)` (1 = stdout, 2 = stderr), puis `data.slice(1)` pour le texte. Une ligne sans cet octet de préfixe est du stdout.
* `status` : métriques du conteneur en direct sous forme de chaîne JSON, environ une trame par seconde. La **première trame** de chaque (re)connexion est complète : `{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }` (`uptime` est l'heure de démarrage en ms epoch ; `netIO.new` est en octets par seconde). **Chaque trame ultérieure est allégée**, ne transportant que `{ cpu, ram, netIO, bIO }` — fusionnez chacune sur la dernière trame complète, en conservant les précédents `cpuLimit`, `status` et `uptime`. Tant que ce flux est ouvert, privilégiez-le plutôt que d'interroger `GET /v2/apps/{app_id}/status`, qui peut être obsolète d'environ une minute pour une application ayant un flux temps réel ouvert.
* `error` : transporte un code d'erreur tel que `CONTAINER_NOT_FOUND`.

Dans l'exemple ci-dessous, `\x01` / `\x02` représentent les octets de préfixe stdout / stderr bruts.

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