Reference → Logs — Reference

Logs — Reference

The Logs surface is the observability plane for every SGEN site. It owns the captured record of what the platform did, what it tried to do, what it rejected, and what it deferred. Anything that an operator wants to inspect after the fact — a failed login, a queued email that never sent, a slow page render, a controller that returned an error — traces back to a record managed here.

This page is a reference for platform engineers, integrators, and on-call support operators who need to understand the surface before reading from it, scripting against it, or scoping a retention policy. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Logs live under the Logs module in SG-Admin. The module renders a small set of stream views — one per log channel — and exposes read, search, filter, export, and prune operations on the captured records. Writes into the log streams are produced by the rest of the platform; the module itself does not accept user-authored entries.

The module is paired by convention: one half renders the stream views and prepares the data, the other half handles administrative writes (prune, export, retention configuration) and returns AJAX responses. The two halves are split across separate controller files but appear to a calling integration as a single surface.

Adjacent to the Logs module is the Activity Log surface, which captures operator actions (create / edit / delete on records). Activity Log is treated separately because it has its own retention policy and its own permission model; this page covers the technical log channels only — application errors, debug traces, request lines, mail-delivery records, scheduler runs, and authentication attempts.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Logs
URL prefix: /sg-admin/logs/
View templates: application/views/Admin/Logs/

The module surface is intentionally read-heavy. Most of the day-to-day work is filtering down a noisy stream to the handful of entries that explain the incident at hand. The write surface (prune, export, retention) is small and gated to administrators.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Logs [Export] [Prune] │├──────────────────────────────────────────────────────────────────────┤│ Channel: [Errors ▾] Level: [All ▾] Range: [Last 24h ▾] [Apply] ││ Filter: ___________________________________________________________│├──────────────────────────────────────────────────────────────────────┤│ Time Level Source Message ││ ─────────────── ────── ────────────────── ──────────────────────││ 10:42:18 today error Pages/Edit Save rejected: title… ││ 10:41:55 today warn Mail/Send Retry 2 of 3 — host… ││ 10:40:02 today info Auth/Login Operator authenticated ││ 10:39:11 today debug Cache/Warm Warm cycle started… ││ 10:38:47 today error Forms/Submit Validation failed on… ││ ││ [⋯ Expand] [⋯ Copy ID] [⋯ Open source view] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Logs surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.

List a channel

Returns the most recent entries on the selected channel, paginated, with timestamp, level, source, and message columns. Each row carries an opaque entry identifier suitable for citation in a bug report or a runbook. Driven by the data-table contract used across SG-Admin modules — responses arrive as a row collection plus a total count, suitable for direct binding to a paged grid.

Filter and search

Narrows the stream by level (error, warn, info, debug), source module, free-text match against the message body, and timestamp range. Filters compose; the result is a single narrowed stream. Free-text search uses substring match by default and supports a simple quoted-phrase form for exact-string match.

Open an entry

Expands a single row into its full captured form. The expanded view shows the message, the captured context (operator identity if authenticated, originating page or controller, request identifier), and any structured payload the source attached. The expanded view is read-only.

Export

Writes the current filtered view to a downloadable file. Export honors the active filter — the exported file contains only the rows that match the filter on screen, not the full channel. File naming carries the channel slug and the export timestamp for traceability.

Prune

Removes entries older than a chosen cutoff from the selected channel. Prune is irreversible. The surface requires the operator to type the channel name as a confirmation before the action commits; soft-deletion is not offered for log entries because retention is treated as a storage decision, not a recovery decision.

Configure retention

Sets the auto-prune cutoff per channel — the age beyond which entries are removed by the scheduled retention task. Retention is configured separately for each channel because the storage and compliance characteristics of (for example) error logs and request logs are different. Changes take effect at the next scheduled retention run.

Mail-delivery inspection

A dedicated view for the mail channel. In addition to the standard columns, it shows the recipient address, the rendered subject, the send status (queued, sent, retrying, failed, suppressed), the most recent provider response, and the retry count. Used to answer the recurring "did this email go out" question without requiring access to the upstream mail provider.

Scheduler-run inspection

A dedicated view for the scheduler channel. Each row represents one scheduled task invocation — the task slug, the start time, the duration, the exit state, and any captured output. Used to confirm that recurring jobs (sitemap regeneration, search index refresh, cache warm cycles, retention prune) are running on their declared cadence.

Data model

A log entry carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`id`	integer	Primary key. Stable across the lifetime of the entry.
`channel`	enum	One of the configured channels (errors, debug, request, mail, scheduler, auth).
`level`	enum	`error`, `warn`, `info`, `debug`.
`source`	string	Module slug or controller name that produced the entry.
`message`	string	Short human-readable summary.
`context`	structured	Optional structured payload — operator identifier, request identifier, source URL, attached values.
`operator_id`	integer	Optional. Populated when the producing request was authenticated.
`request_id`	string	Optional. Correlates entries that originated from a single inbound request.
`created_at`	timestamp	Set on write, immutable.

Channel semantics: channels are independent streams. Filtering on the errors channel does not surface a related request-channel row even if they share a request_id. Cross-channel correlation is the responsibility of the operator — typically by copying the request_id from one channel into the filter of another.

Retention semantics: retention is per-channel and time-based. The scheduled retention task removes entries older than the configured cutoff. Pruned entries are gone — there is no soft-deleted state and no recoverable archive in the standard configuration.

Operator attribution: an authenticated request populates operator_id; an unauthenticated or system request leaves it empty. The expanded view resolves the identifier into a name and email at display time, so renaming or deleting the operator account does not retroactively rewrite the captured entry.

LOG ENTRY├── id integer primary key├── channel enum errors | debug | request | mail | scheduler | auth├── level enum error | warn | info | debug├── source string producing module / controller├── message string short human summary├── context struct operator + request + url + payload├── operator_id integer set when request was authenticated├── request_id string correlation id across channels└── created_at timestamp immutable↓ on retention pruneENTRY REMOVED (no recovery)cutoff per-channelscheduled task runs nightly

Permissions

Access to the Logs surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Logs surface.

Layer 2 — per-action capability. Within SG-Admin, each Logs action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:

Capability	Administrator	Editor	Viewer
View any channel	✔	✔	—
Filter and search	✔	✔	—
Open entry detail	✔	✔	—
Export current view	✔	✔	—
Prune entries	✔	—	—
Configure retention	✔	—	—
Read mail-delivery channel	✔	✔	—
Read auth channel	✔	—	—

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Sensitive channels. The auth channel and the mail channel carry data that can be sensitive on a per-site basis (login attempts, recipient addresses, rendered subject lines). The default map restricts auth to administrators and exposes mail to editors; sites with stricter requirements should redefine the capabilities for the editor role.

Audit. Prune and retention-configuration changes themselves emit Activity Log entries — the surface that captures operator actions on records also captures operator actions on log retention. The log channels do not emit Activity Log entries for ordinary read access.

REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action, per-channel) │ (custom roles override defaults)└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Channel sensitivity gate │ auth / mail channels enforce│ │ per-role read restriction└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry(only for prune / retention-config writes)

Related references

Settings — Reference. Owns the retention cutoffs, the scheduled retention task, and the role capability definitions that gate access to sensitive channels.
Users — Reference. Operator identifiers in log entries resolve through the Users surface. Renamed operators show their current name in the expanded view of past entries.
Tools — Reference. The Activity Log surface (operator actions on records) lives under Tools and follows a separate retention policy.
Mail — Reference. Mail-delivery log rows reference outbound messages composed and queued by the Mail surface.
Scheduler — Reference. Scheduler log rows reference task definitions and run history maintained by the Scheduler surface.
Pages — Reference. Save errors against page records typically appear on the errors channel with a Pages/Edit source.
Forms — Reference. Validation failures on inbound form submissions typically appear on the errors channel with a Forms/Submit source.

For the corresponding customer-facing walkthrough — reading the audit trail, investigating a missing email, configuring retention — see the Logs section of the customer docs at /docs/logs.

On this page

Guides

Reference

Changelog

Roadmap