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

# 实时日志

> 建立一个 Server-Sent Events (SSE) 连接以接收应用的实时数据流（日志、实时指标、状态、部署进度）。连接建立后，会先发送最近的 200 行日志，随后推送新的更新。连接最长可维持 10 分钟。

<Info>由于 SSE 连接的特性（并非所有浏览器都普遍支持），此端点的 API Playground 已禁用。</Info>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

### 参数

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  你想要监控其日志的应用的 ID。此 ID 可以在应用管理面板的 URL 中找到。
</ParamField>

### 响应

<ResponseField name="status" type="string">
  指示调用是否成功。成功时为 `success`，否则为 `error`。
</ResponseField>

失败时，响应将在错误状态之外包含一个 `code` 字段，说明具体原因。

如果请求成功，响应将是一个 `text/event-stream` 流，包含应用的实时数据流。

每个连接最长持续 **10 分钟**。每个账户最多可保持 **5 个并发实时连接**（`REALTIME_MAX_CONNECTIONS`），每个应用最多 **跨所有用户 30 个**（`REALTIME_MAX_CONNECTIONS_APP`）；超出任一限制将返回 `429`。

### Server-Sent Events (SSE) 结构

响应是一个 `text/event-stream` 格式的持续流。每条消息由一个 `event` 字段和一个 `data` 字段组成。不同事件的结构各异，因此请以防御性方式解析负载。

#### 事件类型

* `system`：协议级信号。`data` 行是单个大写代码：连接时为 `REALTIME_CONNECTING | <sseId>`，随后可能是 `REALTIME_TIMEOUT`、`REALTIME_DISCONNECTED`、`REALTIME_RECONNECT` 或 `REALTIME_ERROR` 中的任意一个。
* `logs`：单行日志，其**第一个字符是流 ID 字节**：`\x01`（stdout）或 `\x02`（stderr）。读取 `data.charCodeAt(0)`（1 = stdout，2 = stderr），然后用 `data.slice(1)` 获取文本。没有该前缀字节的行为 stdout。
* `status`：以 JSON 字符串形式呈现的实时容器指标，大约每秒一帧。每次（重新）连接的**第一帧**是完整的：`{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }`（`uptime` 是以毫秒计的 epoch 起始时间；`netIO.new` 是每秒字节数）。**之后的每一帧都是精简的**，仅携带 `{ cpu, ram, netIO, bIO }` —— 将每一帧合并到上一个完整帧上，保留之前的 `cpuLimit`、`status` 和 `uptime`。在此流保持打开期间，请优先使用它，而非轮询 `GET /v2/apps/{app_id}/status`；对于已打开实时流的应用，后者可能有最多约一分钟的延迟。
* `error`：携带一个错误代码，例如 `CONTAINER_NOT_FOUND`。

在下面的示例中，`\x01` / `\x02` 代表原始的 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>