Audit Logs

KeenAgents keeps a permanent audit trail of your organization. Every admin operation — creating, changing, or deleting anything — is recorded as an action line naming the requester (email, user id, role), what was changed, and when. Platform errors are recorded the same way. This is the system audit — the platform's own record of who did what. Runtime lines your agents and scripts emit are kept separately, as per-space, per-agent Log Records you turn on and watch under Logs & Monitoring.

Delivery is buffered and durable: a log line is considered delivered only after it has been written. Lines emitted while the platform is briefly restarting or under maintenance wait and are written afterwards — the audit trail keeps recording even when other parts of the platform are in trouble, precisely because that is when you need it most.

{
  "timestamp": "2026-08-21T09:14:02.113Z",
  "level": "action",
  "channel": "system",
  "message": "Setting log-debug set to true",
  "metadata": { "email": "admin@example.com", "userId": "…", "role": "admin" }
}

Channel

A named on/off destination for the system audit — the platform's own action, error, warning, info, and debug lines. Each channel + level pair is a setting you can see — and, where allowed, toggle — on the Logs page. Runtime logging from your own flows and agents is separate: it lands in dynamic Log Records per space and agent, covered under Logs & Monitoring.

Action lines

The audit trail proper: one line per admin operation, always naming the requester's email, user id, and role, plus what was done. Recorded unconditionally — the platform refuses to switch this channel off, because an audit trail you can silence is not an audit trail.

Log records

One JSON record per line: timestamp, level, channel, message, and metadata. What you read back in the Logs page is exactly what was recorded — no summarizing, no rewriting.

Daily files

Lines are grouped into one file per channel + level per day — for example system-action-2026-08-21.log — and each channel keeps 30 days of history browsable from the Logs page.

Buffered delivery

A line is only counted as delivered once it has been written; until then it waits and is retried. Lines emitted during a restart or maintenance window are written when recording resumes, so a brief interruption never punches a hole in the trail.

System action and error lines are written unconditionally. Attempting to switch either off is refused with "This log is permanently engaged" — the audit and error trails cannot be silenced, by anyone, so they are always trustworthy evidence.

• Reading a file returns its last 40 records, newest first — a tail view built for quick triage.
• Each channel + level keeps 30 days of daily files; older days age out of the browsable list.
• Toggling a channel takes effect for lines emitted afterwards — a line that arrived while its channel was off is dropped by design, not held for later.

• List a channel's files — pick a channel + level to see its available daily files, newest first, together with the channel's current on/off state.
• Read a file — open a daily file to see its last 40 records as parsed JSON, newest first.
• Toggle a channel — flip any toggleable channel on or off. Flipping action or error is refused with "This log is permanently engaged", and every successful toggle is itself recorded as an audit line naming who flipped it, which setting, and the new value — changes to the trail are part of the trail.
• Access is role-gated: viewing requires the logs permission, toggling requires logs write permission. Without them the page refuses — audit data is sensitive, so access is deny-by-default.

• A line on a switched-off channel is gone, not buffered for later — toggling a channel on only affects lines emitted afterwards.
• System action and error lines are always written regardless of settings — do not expect those channels to go quiet.
• The file view shows the last 40 records only — it is a triage tail, not a full-file export.
• Right after maintenance, the Logs page may briefly refuse access — try again a moment later. Recording itself is unaffected, and nothing is missing from the trail.