Logs & Monitoring

A Log Record turns on runtime logging for a scope of your choosing: a whole Space — capturing every agent's runtime lines in it — or a single Agent. What gets captured is what that agent's scripts write while a run is in progress; KeenAgents does not summarize or rewrite it. Records are created and managed from the admin console, on the Logs → Log Records page.

Every captured line is available two ways, independently: as a stored trail you browse after the fact, and as a live stream a partner site can subscribe to and watch in real time. You choose per record whether the live stream is partner-readable at all.

Scope

Each record is either whole space (captures every agent's runtime lines in that space, names no agent) or single agent (captures just that one agent, and must name it). The scope is fixed when you create the record — switching a log from one to the other is a new record, not an edit.

Most-specific wins

When a space has both a space-wide record and a record for one of its agents, the agent record wins for that agent — its own setting decides. This is by existence, not by state: a paused agent record still overrides an emitting space-wide one, so that agent stays quiet while the rest of the space is captured. Only an agent with no record of its own falls back to the space-wide setting.

Emitting / Paused

A record is either Emitting — its scope's runtime lines are captured — or Paused, which keeps the record and all its settings but stops capturing lines. Pause and resume take effect immediately; nothing is captured while paused (lines are not held for later).

Client-readable / Private

Client Read marks a record partner-readable: only then do you hand its stream token to a partner so their site can watch the live stream. Left off, the record is Private — for your eyes in the console only. It governs whether you give a partner live visibility, and is independent of whether the record is emitting.

Stream token

A per-record secret that acts as the key to that record's live stream. It is generated for you when the record is created and shown only on demand, in one place — the Reveal stream token button on the record's detail page. Anyone presenting the correct token can read that stream, so treat it like a password.

Give the log a name, choose whether it captures a whole space or one agent, and pick the target. Choosing Single agent reveals the agent picker and requires an agent; Whole space hides it and captures the space. You can keep at most one record per exact target — a second record for the same space, or the same agent, is refused with "A log already exists for this space/agent".

The board lists your records — optionally filtered to one space — with each record's scope (an agent slug, or a Space-wide tag), its Status (Emitting / Paused), and its Client Read state (Client-readable / Private). From a record's detail page you can:

• Pause or resume it — the Emitting switch. Paused keeps everything but stops capture; resume takes effect at once.
• Rename it, edit its description, move its space or agent, or flip Client Read — Save activates only once you actually change something. The scope (space vs agent) itself is shown as a badge and cannot be changed here.
• Reveal the stream token — see the partner-access section below.
• Delete it — a two-step confirm. Deleting a record also removes its stored lines and ends any live stream on it (see below), so this is a full teardown, not just a hide.

Access is role-gated: viewing records (and revealing a stream token) requires the logs permission; creating, editing, pausing and deleting require logs write permission. Without write, the record page is read-only and its Save and Delete controls do not appear.

Stored trail

Captured lines are written to a durable, dated trail and kept for after-the-fact review — you read them back later, in order. This is the record of what happened, available whether or not anyone was watching at the time.

Live stream

A partner site opens a WebSocket to the record's stream and receives each line as it is produced. The live stream is ephemeral by design: it carries lines going forward, holds no history, and if the streaming layer restarts, open streams drop and clients simply reconnect. For history, read the stored trail.

Live monitoring lets you give a partner or developer real-time visibility into their agent's runs without any server access. Turn on Client Read for the record, reveal its stream token in the console, and hand that token to the partner — the same out-of-band way the certificate material is delivered. Their site then opens a WebSocket to the record's stream, presenting the token, and receives the runtime log lines as they happen.

wss://<your-keenagents-host>/monitor/stream/<spaceId>/<agentSlug>?token=<stream_token>

→ 101 Switching Protocols            // token accepted — runtime log lines stream in
→ 401 Unauthorized (socket closed)   // missing or unknown token — nothing ever opens

The space id and agent slug identify the channel — the same values a site already reads when it fetches its spaces and their agents. A browser WebSocket cannot set request headers, so the token rides the query string. Each line arrives as a small JSON object:

{
  "level": "log-info",
  "message": "Checkout step 3 completed for order #4821",
  "metadata": { "agentId": "checkout-agent", "…": "…" }
}

• Fail-closed, before the socket opens. A missing, wrong, or unknown token is refused with a plain 401 and no socket is ever established — an unauthorized caller never sees an open stream.
• The token is the capability. It authorizes that one channel's stream, not a specific user — anyone holding it can read, so share it only with the partner meant to watch, and only while Client Read is on. If it leaks, edit the record to turn Client Read off.
• Tenant-scoped. A stream only ever carries the lines of the space or agent it names — one channel, one scope.
• Closed cleanly on delete. If an admin deletes the record while a partner is watching, the stream sends a closed notice and closes — treat a close as the end of that log, and stop reconnecting to it.

• A paused record captures nothing, and lines produced while it was paused are not backfilled when you resume — pausing affects capture going forward only.
• The live stream never carries history. A client that connects mid-run sees lines from the moment it connects onward; earlier lines live in the stored trail.
• Revealing a stream token needs only the read logs permission — the same as viewing the record — so anyone who can see a record can hand out its stream. Keep tokens for Private records to yourself.
• A record with no Client Read is fully usable to you in the console; Client Read only concerns whether a partner may watch the live stream.