--- title: "Audit Log" description: "Review the tamper-evident record of who changed what, when, and from where" source_url: https://ai-ops.com/docs/system/audit-log --- # Audit Log Navigate to **System > Audit Log** to review the platform's audit trail: an append-only record of configuration changes, access attempts, and control actions, with the identity behind each one. The audit trail is separate from the **Events** feed. Events are operational: they show what the system is doing right now, drive the timelines and chart markers on each entity's page, and can be cleared once handled. Audit records are accountability facts — *who* did something, from where, and *what the result was* — and they cannot be edited or deleted from within Koios. A configuration change appears in both: as an event you can clear, and as an audit record you cannot. Clearing the event never removes the audit record. Attempts that were refused appear only here — a denied action leaves an audit record, never an event. --- ## Reading the log Each row is one recorded action: | Column | Meaning | |--------|---------| | **Time** | When the action occurred. Hover for the exact UTC timestamp. | | **Actor** | The user or API client responsible. Shows the live name where the account still exists, and a saved name if it was later deleted. System actions (scheduled jobs, background work) show as *system*. | | **Action** | What kind of action it was — create, update, delete, enable/disable, login, permission change, control write, export, and so on. | | **Outcome** | Whether it succeeded, failed, or was denied. | | **Entity** | The device, tag, model, user, or other object the action was about. | | **Source IP** | The network address the request came from, when available. | | **Message** | A short human-readable summary. | Click any row to open a detail panel with the full picture: before-and-after field changes, the request's source IP, user agent, and request ID, plus any extra context captured for that action. --- ## Outcomes The log captures not just what happened but what was attempted and refused. A burst of **Denied** outcomes is often the first sign of misconfigured access or probing. - **Success** — the action completed. - **Failure** — the action was attempted by a permitted actor but did not complete (for example, invalid input). - **Denied** — the actor lacked permission; the action never ran. --- ## Finding what you need - **Search** matches the message and detail text. - **Actor** narrows to a specific user or client. - **Action** and **Outcome** filter by type and result — use these together to answer questions like "show me every denied permission change." - **Time** filters to a range of calendar days, read in your local time zone. The end date is included in full. - **Refresh** re-checks for records logged since you opened the page. The log does not auto-refresh, so use this after making a change you expect to see. --- ## What gets recorded The trail covers the actions an auditor asks about first, including: - **Access** — logins (including *failed* logins), API client authentication, and permission denials. - **Identity and access management** — creating, changing, or deleting users and roles, password changes, and permission or group assignments. - **Configuration** — changes to devices, tags, models, components, and system settings, with the fields that changed. - **Control actions** — writing values to live component inputs and other operator actions that affect running logic. - **Sensitive operations** — backup, restore, license changes, certificate upload and rotation, private-key downloads, log deletion, and data exports. Secrets (passwords, tokens, private keys) are redacted from recorded field changes — the fact of the change is captured, the secret value is not. --- ## Exporting Use **Export** to download the current view as CSV or JSON. The export honors whatever filters are active, so you can produce a scoped, inspection-ready copy (for example, all denied actions in a date range). The export itself is recorded in the log. Exporting requires a dedicated permission, separate from viewing; grant it only to the roles that need to produce compliance evidence. See [Roles & Permissions](https://ai-ops.com/docs/system/roles-permissions.md). --- ## Retention and integrity Audit records are **append-only**. Koios exposes no way to edit or delete an individual record through the application. The trail carries its own retention period — one year by default — independent of the operational event feed's retention, and enforces a 90-day minimum floor that cannot be shortened below the compliance baseline. > [!NOTE] Expired records are purged nightly > Koios deletes records past the retention period once a day, as part of the > nightly maintenance run. Nothing needs to be started by hand, and there is no > purge action in the interface. A run that actually removes records writes a > purge entry to the trail; a run with nothing to delete leaves no trace. > [!WARNING] Restoring a backup replaces the trail > A full restore overwrites the database, including the audit trail, with the > contents of the backup. The restore action is itself recorded beforehand, but > records created after the backup was taken are not carried across. Treat restore > as a deliberate, audited operation. ### When a record cannot be written Recording never blocks the action it records. If a write to the trail fails, the underlying operation still completes and the trail is left with a gap rather than the operation being rolled back. Two things happen instead: - An **Audit write failed** entry is raised in the operational [Events](https://ai-ops.com/docs/events/introduction.md) feed, with the underlying error. - A running count of failed writes is kept by the platform and reported on the system-information API as `auditWriteFailures`. It is not shown on the System Overview page in this release. A non-zero count means the trail is incomplete for that period — treat it as an incident, not a warning to be cleared. --- ## Permissions | Permission | Grants | |------------|--------| | **View audit records** | Open and read the Audit Log. | | **Export audit records** | Download the log as CSV or JSON. | | **Purge expired audit records** | Reserved. Retention is enforced by the nightly maintenance run, which acts on its own rather than on behalf of a user, so this permission gates nothing in this release. | All three are managed under [Roles & Permissions](https://ai-ops.com/docs/system/roles-permissions.md). On upgrade, the Administrator role receives view and export; purge is granted to no role by default, and granting it changes nothing while retention is enforced automatically. No role can create, edit, or delete an individual audit record from the interface.