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 — each line tagged with the level it was written at ([LOG], [INFO], [WARNING], [ERROR], [DEBUG]) — plus the run-time errors the platform raises for that agent. KeenAgents does not summarize or rewrite the text. Records are created and managed from the admin console, under System → Log Records (also reachable from System → Logs).

Every captured line is available two ways, independently: in a stored trail kept for 30 days, and as a live stream a partner site can subscribe to and watch in real time. You mark per record whether you intend to hand its stream to a partner.

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's lines are not stored while the rest of the space is captured, and its stream answers only to its own token. Only an agent with no record of its own falls back to the space-wide record.

Emitting / Paused

A record is either Emitting — its scope's runtime lines are written to the stored trail — or Paused, which keeps the record and all its settings but stops writing lines to the stored trail. Pause and resume take effect immediately; lines produced while paused are not stored and are not backfilled on resume. Pausing does not close the live stream: a client that is already watching keeps receiving lines while the record is paused. To stop a partner watching, delete the record.

Client-readable / Private

Client Read marks a record as one whose stream token you intend to hand to a partner; left off, the record is Private — meant for your eyes in the console only. It is a label for your own discipline and is shown as a badge on the board; it does not gate the stream itself (the token does), and it 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 — by the Reveal stream token button on the record's detail page, or to an AI agent using the Keen MCP Server. It cannot be rotated: a new token comes only with a new record. 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. A new record starts Emitting. 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 the stored trail; resume takes effect at once. The live stream is unaffected by the switch.
• 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. A record that no longer exists answers Log not found.

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 30 days, so the record exists whether or not anyone was watching at the time. A console view for reading these lines back is not available yet — today the live stream is the way to watch a record's lines as they happen; the stored trail is retained for support and for a future read view.

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 connection is interrupted, open streams drop and clients simply reconnect. For anything after the fact, the stored trail is kept for 30 days (no console view yet).

Live monitoring lets you give a partner or developer real-time visibility into their agent's runs without any server access. Mark the record Client-readable (your own record that a partner holds its token), 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 — a welcome frame, then 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 stream always names one agent: for a whole-space record you open one stream per agent slug in that space, all with the record's single token. A browser WebSocket cannot set request headers, so the token rides the query string. Right after the handshake you receive one welcome frame naming the channel; every line after that is a small JSON object:

{ "type": "welcome", "spaceId": "<spaceId>", "agentSlug": "checkout-agent" }

{
  "spaceId": "<spaceId>",
  "agentSlug": "checkout-agent",
  "level": "info",
  "logMessage": "[INFO] Checkout step 3 completed for order #4821",
  "meta": { "correlationId": "…" }
}

level is one of error, warn, info, debug; the message text carries the tag the script used ([LOG], [INFO], [WARNING], [ERROR], [DEBUG]). A frame with type: "closed" means the record was deleted — stop reconnecting.

• 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 channel's stream, not a specific user — anyone holding it can read, whether Client Read is on or off. Client Read is your own bookkeeping of which records you have handed out; it does not lock the stream. A token cannot be rotated: if one leaks, delete the record and create it again — the new record gets a new token and every stream open on the old one is closed.
• Tenant-scoped. A stream carries only the lines of the agent it names, in the space it names. A whole-space record's token opens the stream of any agent in that space — you still subscribe one agent at a time, by slug; an agent that has its own record answers only to that record's token.
• 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 stores nothing, and lines produced while it was paused are not backfilled when you resume — pausing affects the stored trail going forward only. It does not interrupt a live stream that is already open.
• The live stream never carries history. A client that connects mid-run sees lines from the moment it connects onward; earlier lines are kept in the stored trail (retained 30 days; no console view yet).
• 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.
• An AI agent connected through the Keen MCP Server with the logs permission can list, create, edit, pause and delete records and reveal stream tokens — so the read grant hands out stream access to bots as well as people.
• A record with no Client Read is fully usable to you in the console; Client Read only records whether you have chosen to let a partner watch the live stream — keep the tokens of Private records to yourself.