View logs and metrics

In this guide you find out what an app is doing: build output, its runtime log, resource usage, and alerts when something crosses a threshold.

Prerequisites

Any role on the app’s team to read logs and metrics. Running console commands needs developer.

PANEL=https://panel.example.com
H='Authorization: Bearer gsl_xxxxxxxxxxxxxxxx'
J='Content-Type: application/json'

Steps

1. Build logs

Every deployment keeps its build output:

curl -s $PANEL/apps/42/deployments/101/logs -H "$H" \
  | jq -r '.results[] | "\(.stream)\t\(.line)"'

stream is stdout, stderr or system. A failed deployment also has a short failure_reason on the deployment row.

2. Runtime logs (one response)

curl -s "$PANEL/apps/42/runtime-logs/?lines=200" -H "$H" | jq -r '.lines[]'

lines is 1 to 2000 (default 200). The panel reads the app’s journal through the agent. Before the first deploy you get an empty list and a detail message.

On the server you can read the same journal directly:

journalctl -fu gisila-app_ab12cd

3. Live streams over WebSocket

The UI uses these sockets. Each one expects a first text frame with a session JWT (the access token from /auth/login) and the ids, then answers {"ready": true} or {"error": "…"}.

Socket	First frame
`wss://panel.example.com/ws/apps/{id}/logs`	`{"token": "<jwt>", "appId": 42}`
`wss://panel.example.com/ws/apps/{id}/build-logs/{deploymentId}`	`{"token": "<jwt>", "appId": 42, "deploymentId": 101}`
`wss://panel.example.com/ws/apps/{id}/exec/{execId}`	`{"token": "<jwt>", "appId": 42, "execId": "<uuid>"}`
`wss://panel.example.com/ws/services/{id}/logs`	`{"token": "<jwt>", "serviceId": 3}` (superuser)

Each message is {"message": "{\"stream\":\"stdout\",\"line\":\"…\"}", "ts": "…"}. Build, exec and service sockets replay recent history first, then follow.

# with websocat
TOKEN=$(curl -sX POST $PANEL/auth/login -H "$J" \
  -d '{"email":"you@example.com","password":"…"}' | jq -r .access)
printf '{"token":"%s","appId":42}\n' "$TOKEN" \
  | websocat -n wss://panel.example.com/ws/apps/42/logs

4. Run a one-off command

curl -sX POST $PANEL/apps/42/exec -H "$H" -H "$J" \
  -d '{"command": "./current/app migrate"}'
# → {"execId": "6f1c…"}

The command runs as the app’s Linux user, in its directory, with its env vars (and the virtualenv activated for Python and Celery apps). Stream the output on /ws/apps/42/exec/{execId}.

5. Metrics

The worker samples each running app’s CPU and memory.

# The last 60 minutes for one app
curl -s "$PANEL/apps/42/metrics/?minutes=60" -H "$H" \
  | jq '.samples[] | {sampled_at, cpu_percent, mem_bytes}'

# The latest sample for every running app you can see
curl -s $PANEL/apps/metrics-summary -H "$H" \
  | jq '.results[] | {name, cpuPercent, memBytes, memoryMbLimit, cpuQuotaPercent}'

cpuPercent is percent of one core, the same unit as cpuQuotaPercent. Samples older than 5 minutes are left out of the summary. Superusers can read a whole-host snapshot with GET /notifications/host-stats.

6. Alerts

Create a rule that notifies the app’s team when memory stays high:

curl -sX POST $PANEL/notifications/rules -H "$H" -H "$J" -d '{
  "scope": "app",
  "appId": 42,
  "metric": "memory_percent",
  "comparison": "gte",
  "thresholdPercent": 90,
  "severity": "warning",
  "cooldownMinutes": 15
}'

Field	Values
`scope`	`app` (any developer of the app’s team), or `system`, `postgres`, `mongo`, `mail`, `service`, `runtime` (superuser)
target	`appId`, `postgresInstanceId`, `mongoInstanceId`, `managedServiceId` or `applicationId`, matching the scope. `system` and `mail` take none.
`metric`	`cpu_percent`, `memory_percent`, `disk_percent`, `connections_percent`, `status_down`
`thresholdPercent`	Required except for `status_down`. 0 to 100, or up to cores × 100 for `cpu_percent`.
`comparison`	Default `gte`
`severity`	Default `warning`
`cooldownMinutes`	1 to 1440, default 15
`notifyEmail`	Default `true`. Needs SMTP configured by a superuser (`PUT /notifications/settings/smtp`).

App alerts go to every member of the app’s team. Other scopes go to all active superusers. Fired alerts appear in GET /notifications/events and in each recipient’s inbox (GET /notifications/inbox).

Verify it works

curl -s $PANEL/notifications/inbox/unread-count -H "$H"
curl -s "$PANEL/audit/?limit=20" -H "$H" | jq '.results[] | {action, created_at}'

/audit/ lists your own recent state-changing requests.