Skip to main content

Logs

Log retrieval is part of the WebSocket protocol, not a REST endpoint.

Use the get_logs command on /ws.

Command request​

Envelope:

{
	"type": "command",
	"id": "cmd-123",
	"name": "get_logs",
	"payload": {
		"service": "api",
		"after_seq": 120,
		"limit": 200
	}
}

payload fields:

  • service (string, optional): filter by service name
  • after_seq (integer, optional): only return entries with seq > after_seq
  • limit (integer, optional): explicit max entries (> 0)

Command response (result.data)​

{
	"entries": [
		{
			"seq": 121,
			"service": "api",
			"phase": "running",
			"stream": "stdout",
			"message": "ready",
			"timestamp": "2026-04-18T10:30:00Z"
		}
	],
	"truncated": false,
	"effective_limit": 200
}

Core response fields:

  • entries: ordered log entries
  • truncated: whether older entries were dropped to fit the limit
  • effective_limit: actual limit applied by the server

Limit resolution​

Priority order:

  1. explicit limit in the command payload
  2. scope-specific server policy
  3. global server policy
  4. fallback 500

Scope-specific policy details:

  • all-services request (no service): logView.all.maxEntries then logView.maxEntries
  • service request (service set): services.<name>.logView.maxEntries then logView.maxEntries

Clients should trust effective_limit from each response as the source of truth.

Streaming vs reliable continuity​

Live log events are broadcast best-effort and can be dropped under pressure.

For reliable continuity:

  1. track the highest seen seq
  2. call get_logs with after_seq
  3. merge by seq

This is the canonical recovery path after reconnects or event loss.

Disk projection when logs.dir is set​

If server config sets logs.dir, runtime projects logs to JSONL files:

  • all.jsonl (all services)
  • <service>.jsonl (per service)

Disk projection is best-effort; runtime memory and live protocol stream remain the authoritative session behavior.