Administrative log console
The administrative log console is a desktop-only workspace view for finding recent operational and audit events. It lets an authorized member choose a log source, narrow results by time and fields, watch new events, and inspect one event in detail. It is a child experience of the web client, and it uses the application shell described in client application shell.
Console role
The console brings several event streams into one consistent investigation surface. Each source gives the user a table, a set of source-specific filters, and a detail view that turns event data into useful labels and links.
The main user flow is:
flowchart LR
A[Choose log source] --> B[Set time range and filters]
B --> C[Query stored events]
B --> D[Receive matching live events]
C --> E[Review table]
D --> E
E --> F[Open event details]
F --> G[Copy data or open related record or settings]
Log sources
The source tabs define what kind of event the user is investigating. They share the same table and filter experience, but their columns, labels, identity fields, and links match each event type.
Application logs
Application logs show messages produced while the product runs. The source presents a log level and time, can identify an execution and application, and exposes the event message and raw event data for diagnosis. When an event has a known application, the table shows its application identity as a name with an optional app chip. Repeated application events are also represented as usage metrics, while the application-log view keeps a representative event within its duplicate window.
References: packages/…/LogConsoleSources.tsx• L170-203 packages/…/LogConsoleApplicationLogColumns.tsx• L1-200 packages/…/LogConsoleApplicationLogAppColumn.tsx• L1-13 packages/…/LogConsoleAppCell.tsx• L7-25 packages/…/application-repeated-event-recorder.service.ts• L63-135 packages/…/application-log-deduplication-window-ms.constant.ts• L1
Record changes
Record changes show activity on workspace records. Their details explain the action, actor, object, and changed fields. When the record still exists, the user can open it in the record side panel.
References: packages/…/LogConsoleSources.tsx• L66-115 packages/…/LogConsoleRecordChangeDetail.tsx• L44-167
Security events
Security events show workspace access and identity-related activity. The source presents a security event, severity, time, actor, and user identifier so an administrator can review who performed the action. It also covers workspace actions such as a requested data export, with the export and actor available in the event data.
The security view presents the impersonation lifecycle. An administrator cannot impersonate their own account, and a workspace can disable impersonation. Requests that start in another workspace open that workspace in a new browser tab. The log presents requested, started, ended, and failed impersonation events. It can also identify a support actor when the actor is not a workspace member.
References: packages/…/LogConsoleSources.tsx• L116-169 packages/…/getLogConsoleSecurityEvent.ts• L1-72 packages/…/useHandleImpersonate.ts• L17-71 packages/…/SettingsAdminUserWorkspaceActions.tsx• L20-63 packages/…/useLogConsoleMember.ts• L10-59 packages/…/events.type.ts• L38-87 packages/…/workspace-data-export-requested.ts• L5-23
Usage events
Usage events show resource consumption in the workspace. Their details identify the spender and show the quantity and credits used for the operation.
References: packages/…/LogConsoleSources.tsx• L295-343 packages/…/LogConsoleUsageEventColumns.tsx• L1-160
Webhook responses
Webhook responses show the result of calls to configured webhook endpoints. The source highlights success or failure, the event name, the endpoint, and the webhook identifier. A detail view can link back to webhook settings.
References: packages/…/LogConsoleSources.tsx• L205-264 packages/…/LogConsoleWebhookEndpointLink.tsx• L1-100
Page views
Page views show workspace member visits and session context. They provide a member, path, time, user identifier, and session identifier for usage and access review.
References: packages/…/LogConsoleSources.tsx• L265-294 packages/…/LogConsolePageViewColumns.tsx• L1-160
Event log supply
The backend event data supplies the console with workspace, record, page-view, usage, application, and metric events. The event pipeline turns typed activity into stored rows and sends matching events to live sinks, so historical queries and real-time updates use the same event meaning.
Event capture
Workspace actions use typed event names and validated properties before they enter the event stream. Application activity can produce both a readable log entry and a countable metric entry, while unsupported metric entries without an application registration are not stored.
References: packages/…/event-log-emitter.service.ts• L33-119 packages/…/events.type.ts• L70-112 packages/…/build-application-platform-log-entry.ts• L3-19 packages/…/build-application-metric-event-envelopes.ts• L7-19
Event representation
The event registry maps each source to its stored table, entitlement rule, event label, and filterable fields. This shared contract lets the console query different sources while returning a common event shape for its tables and detail panels.
References: packages/…/event-log-registry.ts• L20-126 packages/…/workspace-event-envelope.type.ts• L24-85
Application event aggregation
Repeated application activity is counted by source, application, function, level, error code, and minute. The recorder flushes these counts in the background, which keeps usage totals useful without writing every repeated occurrence as a separate metric row.
References: packages/…/application-repeated-event-recorder.service.ts• L19-114 packages/…/application-metric-event-rollup-buffer.ts• L5-51 packages/…/to-application-metric-event.ts• L4-19
Query controls
The console combines a time window with filters that belong to the selected source. It sends the resulting table, date range, and field filters to the event-log query, then orders the returned entries with the newest events first.
Time ranges
The default window is the last 24 hours. Users can choose windows from 15 minutes through 24 hours, or longer windows of 7, 30, or 90 days. Today and yesterday are also available when the active retention window can cover them.
The time control also selects either the member time zone or UTC. The chosen zone affects displayed time and the date bounds sent to the query.
References: packages/…/LogConsoleTimeRangePresets.ts• L7-17 packages/…/LogConsoleTimeRangeDropdown.tsx• L41-190 packages/…/LogConsoleResults.tsx• L74-97
Field filters
The filter menu changes with the source. It can offer members, event names, record and object values, application levels, executions, actors, logic functions, or applications when those values apply. A filter supports inclusion or exclusion and can contain multiple selected values.
Changing the source removes filters that do not belong to the new source. Changing the time range or filters also clears the current live buffer and starts the result view again from the top.
References: packages/…/LogConsoleToolbar.tsx• L104-221 packages/…/LogConsoleToolbar.tsx• L309-465 packages/…/LogConsole.tsx• L521-533 packages/…/LogConsoleResults.tsx• L130-163
Result loading
The console loads stored events in pages of up to 100 records. It adds more records as the user reaches the end of the table. This keeps the first result set quick while still allowing review of the full selected window.
References: packages/…/LogConsoleResults.tsx• L36-39 packages/…/LogConsoleTable.tsx• L108-119 packages/…/useQueryEventLogs.ts• L19-64
Log details
Selecting a row opens a side panel that keeps the table context while showing the event in a source-aware format. The panel gives the user a readable view for investigation and the original event for deeper analysis.
Detail panel
The panel shows a source title, time, source-defined detail fields, useful identifiers, and any event message. It can copy a message, an identifier, or the full event as formatted JSON. On narrow screens, the detail view takes over the console body so the event remains readable.
References: packages/…/LogConsoleDetailPanel.tsx• L109-207 packages/…/LogConsoleDetailPanel.tsx• L211-327 packages/…/LogConsole.tsx• L657-684
Record change details
Record-change details add a field-level view of the record before and after the action. They show empty values clearly, explain when a permanently deleted record has no stored values, and provide an action to open the surviving record.
References: packages/…/LogConsoleRecordChangeDetail.tsx• L55-117 packages/…/LogConsoleRecordChangeDetail.tsx• L120-167
Access and retention
The console is an administrative surface. Its availability depends on the member's security permission and device type. Data service configuration, feature presentation, and plan entitlement also control what the member can see and which source tabs the member can use.
Console access
The console appears when the member has the security permission and the client is not on a mobile device. Its client toggle controls whether the panel is enabled and opened, while the permission and device checks control whether the console and its hotkey are available. The current administrative feature-flag metadata does not define a separate log-console flag. Log data also requires ClickHouse; without it, the console shows a configuration message instead of results.
References: packages/…/useIsLogConsoleAllowed.ts• L5-12 packages/…/isLogConsoleEnabledState.ts• L1-8 packages/…/useSetIsLogConsoleEnabled.ts• L8-28 packages/…/LogConsole.tsx• L257-301 packages/…/LogConsole.tsx• L363-367 packages/…/LogConsole.tsx• L565-581 packages/…/SettingsAdminFeatureFlagMetadata.ts• L1-91 packages/…/LogConsole.test.tsx• L243-257
Source entitlements
Application logs and record changes do not require the audit-log entitlement. Security events, webhook responses, page views, and usage events do require it. Without that entitlement, those sources remain visible as locked tabs and show an upgrade prompt rather than query results.
References: packages/…/LogConsoleSources.tsx• L66-74 packages/…/LogConsoleSources.tsx• L117-137 packages/…/LogConsoleSources.tsx• L205-217 packages/…/LogConsoleSources.tsx• L266-301 packages/…/LogConsole.tsx• L388-415 packages/…/LogConsole.tsx• L579-591 packages/…/event-log-registry.ts• L47-95
Retention windows
All log sources use the active event-log retention window. Without the audit-log entitlement, the window is two hours. With the entitlement, it uses the workspace retention setting, defaults to three days when the setting is absent, and is capped at 1,095 days. The time-range menu disables choices outside the active window. If the selected range becomes invalid, the console selects the longest preset that still fits, or 15 minutes when none fits.
References: packages/…/useLogConsoleRetention.ts• L11-39 packages/…/LogConsoleTimeRangeDropdown.tsx• L87-106 packages/…/LogConsoleTimeRangeDropdown.tsx• L167-184 packages/…/LogConsoleResults.tsx• L66-85 packages/…/getLogConsoleTimeRangeWithinRetention.ts• L7-29 packages/…/isLogConsoleTimeRangeWithinRetention.ts• L6-26 packages/…/getEventLogRetentionInHours.ts• L3-15 packages/…/EventLogRetention.ts• L1-6 packages/…/event-log-retention.service.ts• L20-62
Live presentation
The console presents a historical result set and a live stream as one table. The live stream is active for open-ended recent views with matching field filters, so new records appear above stored records without requiring a full refresh.
Live stream
New events arrive through the client event stream and are kept at the top of the table. Users can pause the stream to inspect a stable set of entries, resume it later, clear the current live entries, or refresh a historical view. Live updates reset when the source or filters change.
References: packages/…/LogConsoleResults.tsx• L95-175 packages/…/useEventLogsLiveStream.ts• L22-74 packages/…/event-log-emitter.service.ts• L33-43 packages/…/console-event.sink.ts• L8-41
Console layout
The console opens as a resizable bottom panel and can collapse, expand to full screen, or close while preserving a keyboard shortcut for reopening it. Its display mode is saved in local browser storage, so the user's open, collapsed, or closed choice persists. The console can remain open when Advanced mode is turned off. The table has a fixed header and adds new live rows with a visual entrance effect. Reduced-motion settings disable those transitions.
References: packages/…/LogConsole.tsx• L257-381 packages/…/LogConsole.tsx• L474-515 packages/…/LogConsole.tsx• L535-543 packages/…/LogConsoleTable.tsx• L23-57 packages/…/LogConsoleTable.tsx• L159-205 packages/…/logConsoleDisplayModeState.ts• L3-10
Change checklist
When these files or sections are changed, remember to consider these:
- When adding or changing a source, keep its event-log table, fixed event filter, columns, filters, detail fields, identifiers, retention class, and entitlement rule aligned.
- When changing application-log columns, keep application identifiers mapped to the application name and optional app chip shown in the table.
- When changing source switching, keep incompatible filter removal and selected-detail clearing in sync so old state cannot affect a new source.
- When changing query pagination or live delivery, preserve newest-first ordering and reset live entries when the source, time range, or field filters change.
- When changing retention values or presets, update both the selectable-range rules and the fallback to the longest valid preset or 15 minutes.
- When changing access rules, update the security-permission and device checks separately from locked-source behavior. A member can pass the first check and still lack an audit-log entitlement.
- When changing an event name or its properties, update the shared event type, validation schema, registry normalization, and source detail mapping together.
- When changing application event recording, preserve the difference between representative log entries and aggregated metric counts.
- When changing impersonation controls, keep the action guard, cross-workspace redirect, and security-event labels aligned.
{"path": "packages/twenty-front/src/modules/settings/admin-panel/constants/SettingsAdminFeatureFlagMetadata.ts", "status": "M"}{"path": "packages/twenty-front/src/modules/settings/admin-panel/hooks/useHandleImpersonate.ts", "status": "M"}
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| ClickHouse is not configured | The console cannot query or display log results. | Show the configuration placeholder and direct the member to the administrator. |
| Security permission is missing or the client is mobile | The console is not available to the member. | Gate the console before rendering its panel or hotkey behavior. |
| An administrator tries to impersonate their own account or a workspace disables impersonation | The impersonation request does not start. | Reject the action before login-token exchange and show the failure to the administrator. |
| A source needs the audit-log entitlement and the workspace does not have it | The source cannot be queried and shows an upgrade state. | Mark the source as locked and keep it out of the active result view. |
| A selected time range exceeds retention | The query could ask for data that the source no longer keeps. | Disable invalid range choices and reset the range to the longest valid preset or 15 minutes. |
| A historical query fails | The result area shows an error instead of a partial table. | Keep the refresh action available so the member can retry. |
| A record was permanently deleted | No record values remain for the detail diff. | Explain the missing values and show the raw event when available. |
| Repeated application events arrive within the duplicate window | The application-log view does not show every repeated occurrence as a separate row. | Keep the representative log and aggregate occurrence counts in the metric stream. |
| An application metric event has no application registration | The metric row is not stored. | Require an application registration before building the metric event envelope. |
Key files
| File | Why to read it |
|---|---|
| packages/…/LogConsole.tsx | Defines the console boundary, access-aware source selection, panel layout, resizing, and detail-panel placement. |
| packages/…/LogConsoleSources.tsx | Describes the supported log sources and maps each source to its table, filters, columns, details, and related actions. |
| packages/…/LogConsoleResults.tsx | Connects time and field controls to stored queries, live events, pause and clear actions, and table results. |
| packages/…/LogConsoleToolbar.tsx | Shows how source-specific filter fields become user-facing filter chips and value selectors. |
| packages/…/LogConsoleDetailPanel.tsx | Defines the common event detail experience, including readable fields, messages, identifiers, and raw JSON. |
| packages/…/LogConsoleRecordChangeDetail.tsx | Shows the record-change-specific diff and link back to a record. |
| packages/…/LogConsoleApplicationLogAppColumn.tsx | Maps an application-log event to the application identity shown in the table. |
| packages/…/LogConsoleAppCell.tsx | Presents the application name and optional app chip for an application-log row. |
| packages/…/useIsLogConsoleAllowed.ts | Defines the client-side security-permission and device conditions that make the administrative console available. |
| packages/…/useHandleImpersonate.ts | Shows how an administrative impersonation action starts in the current workspace or redirects to another workspace. |
| packages/…/SettingsAdminFeatureFlagMetadata.ts | Defines the current administrative feature-flag metadata used by the admin panel. |
| packages/…/useQueryEventLogs.ts | Provides paged historical event-log loading. |
| packages/…/useEventLogsLiveStream.ts | Provides filtered live event delivery and its lifecycle. |
| packages/…/useLogConsoleRetention.ts | Defines the active event-log retention window and its entitlement rules. |
| packages/…/event-log-registry.ts | Defines the shared source contract for stored tables, entitlements, labels, filters, and normalized results. |
| packages/…/event-log-emitter.service.ts | Connects typed workspace and application activity to the event-log sink and live event path. |
| packages/…/application-repeated-event-recorder.service.ts | Shows how repeated application logs remain useful as representative logs and aggregated metrics. |
| packages/…/event-log-retention.service.ts | Applies entitlement rules to the retention window used by event-log storage. |