---
title: Audit Log
description: Track every mutating action on your Sencho instance with a searchable trail for team accountability; export and extended retention on Admiral.
---

<Note>
  Audit requires the `system:audit` permission (Admin or Auditor). Community shows the rolling 14-day recent-activity window. Admiral adds the 24h signal rail, CSV/JSON export, anomaly detection, and configurable retention beyond that window.
</Note>

<Note>
  Audit is hub-only and is not shown in the nav strip when a remote node is the active selection. See [Multi-Node Management](/features/multi-node#what-top-level-views-show-when-a-remote-node-is-active).
</Note>

Sencho records every mutating action (deploy, stop, delete, settings changes, user management) with full attribution. The audit log answers the question every team eventually asks: **"Who changed what, and when?"**

## What gets logged

Every `POST`, `PUT`, `DELETE`, and `PATCH` request to the Sencho API is automatically recorded with:

| Field | Description |
|-------|-------------|
| **Timestamp** | When the action occurred |
| **User** | The authenticated username that performed the action |
| **Method** | HTTP method (`POST`, `PUT`, `DELETE`, `PATCH`), shown as a color-coded badge |
| **Action** | Human-readable summary (e.g., "Deployed stack: nginx-proxy") |
| **Status** | HTTP response status code, color-coded by result (green for success, amber for client errors, rose for server errors) |
| **Node** | Numeric node ID the action targeted, or `-` for local-only actions |

Expanding a row in the Table view reveals additional detail:

| Field | Description |
|-------|-------------|
| **Request Path** | Full API path of the request |
| **IP Address** | Client IP address as recorded by the gateway |
| **Node ID** | Numeric node ID, or "Local" for local actions |
| **Entry ID** | Unique identifier for the audit entry |

### Example actions tracked

- Stack lifecycle: deploy, take down, start, stop, restart, update, rollback, delete
- Stack creation, file edits, env file changes, label changes
- Per-service lifecycle (start, stop, restart of an individual compose service)
- Container operations: start, stop, restart
- Label management: create, update, delete, and label-based bulk actions
- Node management: add, update, delete, cordon, uncordon
- Fleet operations: backup creation, restore, deletion, single-node and fleet-wide updates
- Fleet replica role changes (re-anchor, demote to control)
- Fleet Secrets: create, update, delete, import-from-stack, push (and push preview)
- Blueprint federation pin updates
- Recovery Vault: config update, connection test, provisioning, snapshot upload, snapshot deletion
- User management: create, update, delete, role assignment and removal
- Password changes, two-factor authentication reset, and node token generation
- License activation and deactivation
- Webhook and notification agent configuration
- Notification route management and testing
- Notification suppression rule management
- SSO configuration changes and connection tests
- API token creation and revocation
- Registry credential management
- Scheduled task management and manual triggers
- Settings changes
- Auto-update execution
- Template deployments
- Console token generation
- System prune (general, orphans, system), image / volume / network deletion, network creation

## Viewing the audit log

The **Audit** tab appears for any signed-in user whose role grants the `system:audit` permission (by default **Admin** or **Auditor**). Community shows the last 14 days of activity. Admiral shows the full retained history; retention defaults to 90 days and is configurable up to 365.

Navigate to the **Audit** tab in the top navigation when it is available for your role.

The page has two views, toggled from the segmented control in the card header: **Stream** (default) and **Table**. The card subtitle reports the total number of entries that match the current filters.

### Stream view

Stream gives you an at-a-glance read on activity. The feed groups entries by day with severity dots and relative times.

<Note>
  The 24h signal rail and inline anomaly callouts require a Sencho **Admiral** license.
</Note>

<Frame>
  <img src="/images/audit-log/audit-stream.png" alt="Audit Log Stream view with the four-tile signal rail (Events 53 +218% vs 7d avg, Actors 2, Failure rate 0%, Peak hour 21:00) above a day-banded chronological feed of admin POST and DELETE entries, including a first seen anomaly flag on one entry." />
</Frame>

**Signal rail tiles (Admiral):**

| Tile | What it shows |
|------|---------------|
| **Events · 24h** | Count of audit entries in the last 24 hours, with a percent change versus the prior 7-day daily average |
| **Actors** | Unique users active in the last 24 hours; the detail line names a sample actor and the count of new IP addresses when any new IPs are seen for an existing user |
| **Failure rate** | Share of 24-hour requests with 4xx or 5xx responses, rendered with an inline sparkline of the hourly failure trend; tints amber at 5% and above, rose at 20% and above |
| **Peak hour** | The hour with the highest activity. Renders blank when the peak sits inside working hours (08:00 to 17:59); flips to amber and shows the hour when the peak falls outside that window |

**Feed entries:** each row shows the relative time (e.g. `58m ago`), a severity dot (green for 2xx, amber for 3xx, rose for 4xx and 5xx), the actor and action summary, a meta line with the exact timestamp, the node, the status code, the IP, and any anomaly flags, plus the method and path on the right.

Rows colored in rose or amber indicate failures; the tinting makes spikes of errors visible at a glance.

### Table view

Table keeps the full-featured detail grid for power users: exact timestamps, method badges, action summaries, and status codes in fixed columns. Clicking any row expands it to show the full request path, IP address, node ID, and entry ID.

<Frame>
  <img src="/images/audit-log/audit-log-overview.png" alt="Audit Log Table view with a filter strip (search box, All Methods dropdown, From and To date pickers) above a six-column table of admin POST and DELETE entries against /api/webhooks, /api/notifications, and /api/scheduled-tasks." />
</Frame>

<Frame>
  <img src="/images/audit-log/audit-log-expanded.png" alt="Audit Log Table view with the second row expanded to reveal Request Path /api/webhooks/4, IP Address ::ffff:203.0.113.10, Node ID 1, and Entry ID #2472 in a four-cell detail strip." />
</Frame>

Both views share the **Refresh** button in the card header and paginate at 50 entries per page with chevron controls at the bottom of the feed or table. On Admiral, both views also share the **Export** dropdown.

## Anomaly detection

<Note>
  Anomaly detection requires a Sencho **Admiral** license.
</Note>

In Stream view, Sencho annotates individual entries with lightweight anomaly flags that help you spot activity that deviates from an actor's normal pattern. Flags appear inline in the entry's meta line, after the IP address.

| Flag | When it fires |
|------|---------------|
| **unusual hour** | The entry's hour sits outside the central 90% of the actor's typical activity window, computed from the last 7 days. Requires a baseline of at least 5 prior entries to avoid flagging new users. |
| **new ip** | The IP address on this entry has not been seen for this actor in the last 30 days, and the actor already has at least one prior IP on record. |
| **first seen** | The actor has no prior entries in the 30-day history window. Useful for spotting brand-new service accounts, CLI tools, or compromised sessions. |

Flags are computed at read time against your existing audit history. No new tables, no per-entry storage overhead, and the logic is cache-friendly, so enabling Stream view does not slow down the audit log endpoint. On instances with a very large audit history, baselines are computed from the most recent slice of activity so the view stays responsive; this keeps memory and latency bounded without changing how flags behave for typical histories.

## Filtering and search

Filters live in the **Table view only**. Switching to Stream hides the filter strip; the Stream feed always shows the most recent unfiltered entries grouped by day.

In Table view you can combine:

- **Full-text search** across action summaries, API paths, and usernames
- **Method** filter (POST, PUT, DELETE, PATCH) via the dropdown
- **Date range** with **From** and **To** pickers, narrowing results to a specific time window

All filters AND together and are applied server-side with pagination.

## Export

<Note>
  CSV and JSON export require a Sencho **Admiral** license.
</Note>

Export the currently filtered audit log as **CSV** or **JSON** using the **Export** dropdown in the card header. The export respects every active filter, so you can narrow down to a date range or specific user before exporting.

Exports are capped at 10,000 entries per download. To export a larger window, narrow the date range and download in chunks.

## Auditor role

<Note>
  The **Auditor** role is available on every plan. Assign it under **Settings · Users**.
</Note>

The **Auditor** role provides read-only access to the audit log without granting any administrative privileges. Auditors can:

- View the audit log (Community: last 14 days; Admiral: full retained history)
- Search and filter entries (Table view)
- Export as CSV or JSON (Admiral)
- View stacks and nodes (read-only)

Auditors **cannot** modify settings, manage users, deploy stacks, or perform any other administrative action. The role is ideal for compliance officers, security reviewers, or team leads who need visibility into system activity without operational access.

To create an Auditor user, go to **Settings · Users** and select the **Auditor** role when creating a new user.

## Configurable data retention

<Note>
  Every tier can read the most recent 14 days of activity. Configurable retention beyond that window requires a Sencho **Admiral** license.
</Note>

On Admiral, audit log entries are automatically pruned based on your configured retention period. The default is **90 days**.

To change the retention period:

1. Open **Settings · Operations · Data Retention**
2. Set the **Audit log** value (1 to 365 days)
3. Click **Save settings**

<Frame>
  <img src="/images/audit-log/data-retention.png" alt="Data Retention settings page with retention rows for Container metrics (24 hrs), Notification log (30 days), Scan history per digest (50 scans), Remove scans for deleted images and stacks (on), and Audit log (90 days)." />
</Frame>

Cleanup runs automatically as part of Sencho's periodic maintenance cycle.

## Security at rest

Sensitive database values (such as remote node API tokens) are encrypted at rest. The encryption key is stored separately from the database, ensuring that database file exposure alone does not compromise secrets.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Audit tab is missing from the navigation">
    The Audit tab appears only for users with the `system:audit` permission (by default **Admin** or **Auditor**). If you are signed in as a Viewer, Deployer, or Node Admin, ask an admin to grant you a role that includes audit access.
  </Accordion>
  <Accordion title="Stream view shows everything but I want to filter to a specific user, action, or date">
    Filters live in **Table view only**. Toggle the segmented control in the card header from **Stream** to **Table** and the search box, method dropdown, and From / To date pickers will appear above the grid. Switching back to Stream clears the filter strip but does not remember the last filter.
  </Accordion>
  <Accordion title="An anomaly flag did not fire on a login I expected to be flagged">
    The three flags have intentional baseline thresholds so they do not fire on incomplete data. **first seen** requires the actor to have zero entries in the prior 30 days; if you have any history at all, you will not be flagged again. **new ip** requires the actor to already have at least one stored IP in the prior 30 days; the very first IP for an actor is implicit in **first seen**, not surfaced as **new ip**. **unusual hour** requires at least 5 prior entries in the last 7 days to build a baseline; sparse actors will not flag at all until they have built up history.
  </Accordion>
  <Accordion title="Export came back smaller than the row count in the table">
    Each export is capped at 10,000 entries. If your filter selects more than that, narrow the date range using the **From** and **To** pickers and download in chunks. The cap protects the API from generating very large CSVs in a single response; for full archives, schedule periodic exports from your own tooling.
  </Accordion>
  <Accordion title="Old entries vanished even though I never deleted anything">
    On Community, the list shows only the last 14 days of activity, so older rows are not returned even when they still exist in the database. On Admiral, cleanup also runs against the **Audit log** retention value in **Settings · Operations · Data Retention** (default 90 days). Entries older than the configured window are pruned on the next maintenance tick. Increase the value (up to 365 days) before the next cleanup runs to retain a longer history; the change applies forward only and cannot bring back already-pruned entries.
  </Accordion>
</AccordionGroup>
