Logs und Metriken in Echtzeit streamen (SSE)

curl --request GET \
  --url https://api.squarecloud.app/v2/apps/{app_id}/realtime \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/realtime', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/realtime",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/realtime"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/realtime")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>"
}

Der API-Playground ist für diesen Endpoint deaktiviert, da SSE-Verbindungen ihrer Natur nach nicht von allen Browsern unterstützt werden.

string

erforderlich

Der API-Schlüssel für dein Konto. Du findest ihn in deinen Kontoeinstellungen.

Erfordert einen API-Schlüssel mit dem Scope apps:read. Verwende diesen Endpoint immer dann, wenn du eine Live-Ansicht einer Anwendung statt Polling brauchst: um den Fortschritt eines Deploys zu beobachten, Logs beim Schreiben live mitzuverfolgen oder das CPU/RAM-Diagramm eines Dashboards zu speisen, ohne Anwendungsstatus abrufen oder Anwendungslogs abrufen im Sekundentakt abzufragen. Er ersetzt beide für die Dauer der Verbindung. Intern wählt eine hier geöffnete Verbindung einen einzelnen Upstream-Stream auf dem Cluster der Anwendung an und leitet ihn über SSE weiter, mit einem transparenten internen Reconnect, falls dieser Upstream abbricht. Da jede offene Verbindung bis zu 10 Minuten lang einen Socket belegt, sind Verbindungsaufbauten separat von den unten beschriebenen Limits für gleichzeitige Verbindungen rate-limitiert: 1 Verbindungsaufbau alle 5 Sekunden pro (Benutzer, Anwendung) sowie 20 Verbindungsaufbauten alle 10 Sekunden pro Benutzer über alle Anwendungen hinweg, gefolgt von einer kurzen Abkühlphase.

Parameter

string

erforderlich

Die ID der Anwendung, deren Logs du überwachen möchtest. Diese ID findest du in der URL des Verwaltungspanels deiner Anwendung.

Antwort

string

Gibt an, ob der Aufruf erfolgreich war: success, wenn ja, error, wenn nicht.

Im Fehlerfall enthält die Antwort ein Feld code zusätzlich zum Fehlerstatus, das die Ursache erläutert. Ist die Anfrage erfolgreich, ist die Antwort ein text/event-stream-Stream, der den Echtzeit-Feed der Anwendung enthält. Jede Verbindung dauert bis zu 10 Minuten. Jedes Konto kann 5 gleichzeitige Echtzeit-Verbindungen halten (REALTIME_MAX_CONNECTIONS) und jede Anwendung 30 über alle Nutzer hinweg (REALTIME_MAX_CONNECTIONS_APP); wird eines der beiden Limits überschritten, wird 429 zurückgegeben.

Struktur der Server-Sent Events (SSE)

Die Antwort ist ein kontinuierlicher Stream im Format text/event-stream. Jede Nachricht besteht aus einem Feld event und einem Feld data. Die Formen variieren je nach Event, parse die Payloads daher defensiv.

Event-Typen

system: Signale auf Protokollebene. Die data-Zeile ist ein einzelner Code in Großbuchstaben: REALTIME_CONNECTING | <sseId> beim Verbindungsaufbau, danach einer von REALTIME_TIMEOUT, REALTIME_DISCONNECTED, REALTIME_RECONNECT oder REALTIME_ERROR.
logs: Eine einzelne Log-Zeile, deren erstes Zeichen ein Stream-ID-Byte ist: \x01 (stdout) oder \x02 (stderr). Lies data.charCodeAt(0) (1 = stdout, 2 = stderr), dann data.slice(1) für den Text. Eine Zeile ohne dieses Präfix-Byte ist stdout.
status: Live-Container-Metriken als JSON-String, etwa ein Frame pro Sekunde. Der erste Frame jeder (Wieder-)Verbindung ist vollständig: { cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime } (cpuLimit ist die Anzahl der zugewiesenen CPU-Kerne; uptime ist die Startzeit als Epoch-ms; netIO.new sind Bytes pro Sekunde). Jeder spätere Frame ist schlank und trägt nur { cpu, ram, netIO, bIO }: führe jeden mit dem letzten vollständigen Frame zusammen und behalte dabei die vorherigen Werte von cpuLimit, status und uptime. Solange dieser Stream offen ist, bevorzuge ihn gegenüber dem Polling von GET /v2/apps/{app_id}/status, das bei einer Anwendung mit offenem Echtzeit-Stream bis zu etwa einer Minute veraltet sein kann.
error: Trägt einen Fehlercode wie CONTAINER_NOT_FOUND.

Im folgenden Beispiel stehen \x01 / \x02 für die rohen stdout-/stderr-Präfix-Bytes.

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

Häufige Fehler

Code	HTTP	Bedeutung
`REALTIME_MAX_CONNECTIONS`	429	Der Aufrufer hat bereits 5 gleichzeitige Echtzeit-Verbindungen offen.
`REALTIME_MAX_CONNECTIONS_APP`	429	Die Anwendung hat bereits 30 gleichzeitige Echtzeit-Verbindungen über alle Benutzer hinweg offen.

Siehe auch

CLI: squarecloud app realtime
SDKs: api.apps.realtime() (JavaScript), client.apps.realtime() (Python), c.Apps.Realtime() (Go)

Logs und Metriken in Echtzeit streamen (SSE)

curl --request GET \
  --url https://api.squarecloud.app/v2/apps/{app_id}/realtime \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/realtime', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/realtime",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/realtime"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/realtime")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>"
}

Erste Schritte

Konto

Anwendungen

Datenbanken

Workspaces

KI

Logs und Metriken in Echtzeit streamen (SSE)

Parameter

Antwort

Struktur der Server-Sent Events (SSE)

Event-Typen

Häufige Fehler

Siehe auch

​Parameter

​Antwort

​Struktur der Server-Sent Events (SSE)

​Event-Typen

​Häufige Fehler

​Siehe auch

Parameter

Antwort

Struktur der Server-Sent Events (SSE)

Event-Typen

Häufige Fehler

Siehe auch