PLAT-4895: document audit log v2 and config changes for Enterprise 26.1

platform-enterprise_docs/enterprise/configuration/configtables/tower_logging.yml

@@ -1,63 +1,61 @@
 ---
--
-  Environment variable:            '`TOWER_CRON_AUDIT_LOG_CLEAN_UP_TIME_OFFSET`'
-  Description: >
-     Application event audit log retention period. Logged events older than this period are deleted. Value includes units (`30d`, `24h`, `60m`, etc.).
-  Value:                'Default: `365d`'
--
-  Environment variable:            '`TOWER_LOG_APPENDER`'
-  Description: >
-     The output format of Platform logs.
-  Value:                'Options: `STDOUT`, `JSON`'
--
-  Environment variable:            '`TOWER_LOG_LEVEL`'
-  Description: >
-     Platform backend logging detail level.
-  Value:                'Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`'
--
-  Environment variable:            '`TOWER_SECURITY_LOGLEVEL`'
-  Description: >
-     Platform authentication logging detail level.
-  Value:                'Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`'
--
-  Environment variable:            '`TOWER_LOG_DIR`'
-  Description: >
-     Base directory to store Platform logs.
+- Environment variable: "`TOWER_CRON_AUDIT_LOG_CLEAN_UP_ENABLED`"
+  Description: >
+    Set `false` to disable automatic deletion of audit log records. In 26.1, this applies to both the legacy `tw_audit_log` table and the new `tw_audit_log_v2` table. Restart Platform after changing this value.
+  Value: "Default: `true`"
+- Environment variable: "`TOWER_CRON_AUDIT_LOG_CLEAN_UP_TIME_OFFSET`"
+  Description: >
+    Application event audit log retention period. When cleanup is enabled, audit log records older than this period are deleted from both v1 and v2 audit log tables. Value includes units (`30d`, `24h`, `60m`, etc.).
+  Value: "Default: `365d`"
+- Environment variable: "`TOWER_AUDIT_LOG_V2_WRITE_MODE`"
+  Description: >
+    Determines which audit log tables receive new write operations. Use `v1` for the legacy table only, `dual` to write to both legacy and v2 tables during the 26.1 migration period, or `v2` for the new table only.
+  Value: "Options: `v1`, `dual`, `v2`. Default: `dual`"
+- Environment variable: "`TOWER_AUDIT_LOG_V2_CSV_EXPORT_MAX_LOGS`"
+  Description: >
+    Maximum number of audit log v2 records allowed in a single CSV export.
+  Value: "Default: `500000`"
+- Environment variable: "`TOWER_LOG_APPENDER`"
+  Description: >
+    The output format of Platform logs.
+  Value: "Options: `STDOUT`, `JSON`"
+- Environment variable: "`TOWER_LOG_LEVEL`"
+  Description: >
+    Platform backend logging detail level.
+  Value: "Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`"
+- Environment variable: "`TOWER_SECURITY_LOGLEVEL`"
+  Description: >
+    Platform authentication logging detail level.
+  Value: "Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`"
+- Environment variable: "`TOWER_LOG_DIR`"
+  Description: >
+    Base directory to store Platform logs.
   Value:
--
-  Environment variable:            '`TOWER_LOG_PATTERN`'
+- Environment variable: "`TOWER_LOG_PATTERN`"
   Description: >
     The logging format emitted to STDOUT. See [here](https://logback.qos.ch/manual/layouts.html#conversionWord) for a reference of the full logback pattern syntax.
-  Value:                '`%d{MMM-dd HH:mm:ss.SSS} [%t] %X{ip:--} %-5level %logger{36} - %msg%n}  # Default logging pattern shown`'
--
-  Environment variable:            '`TOWER_LOG_MAX_HISTORY`'
+  Value: "`%d{MMM-dd HH:mm:ss.SSS} [%t] %X{ip:--} %-5level %logger{36} - %msg%n}  # Default logging pattern shown`"
+- Environment variable: "`TOWER_LOG_MAX_HISTORY`"
   Description: >
-     The maximum number of backend log files retained by the system.
+    The maximum number of backend log files retained by the system.
   Value:
--
-  Environment variable:            '`TOWER_LOG_MAX_SIZE`'
+- Environment variable: "`TOWER_LOG_MAX_SIZE`"
   Description: >
-     The maximum file size of the Platform backend log file. When this limit is reached, a new log file is created.
+    The maximum file size of the Platform backend log file. When this limit is reached, a new log file is created.
   Value:
-# TODO(26.1): not in platform repo's ENVIRONMENT-VARIABLES.md — verify still valid
--
-  Environment variable:            '`LOGGER_LEVELS_IO_SEQERA_TOWER_AGENT`'
-  Description: >
-     Tower Agent logging detail level.
-  Value:                'Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`'
-# TODO(26.1): not in platform repo's ENVIRONMENT-VARIABLES.md — verify still valid
--
-  Environment variable:            '`TOWER_AGENT_HEARTBEAT`'
-  Description: >
-     Tower Agent polling interval.
-  Value:                'Example: `10s`'
--
-  Environment variable:            '`TOWER_SSH_LOGLEVEL`'
-  Description: >
-     Event logging detail level for the SSH connection library used by Seqera.
-  Value:                'Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`'
--
-  Environment variable:            '`TOWER_ALLOW_NEXTFLOW_LOGS`'
-  Description: >
-     Set `true` to allow Seqera to retrieve logs and reports for runs launched with Nextflow CLI.
-  Value:                'Default: `false`'
+- Environment variable: "`LOGGER_LEVELS_IO_SEQERA_TOWER_AGENT`"
+  Description: >
+    Tower Agent logging detail level.
+  Value: "Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`"
+- Environment variable: "`TOWER_AGENT_HEARTBEAT`"
+  Description: >
+    Tower Agent polling interval.
+  Value: "Example: `10s`"
+- Environment variable: "`TOWER_SSH_LOGLEVEL`"
+  Description: >
+    Event logging detail level for the SSH connection library used by Seqera.
+  Value: "Options: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`"
+- Environment variable: "`TOWER_ALLOW_NEXTFLOW_LOGS`"
+  Description: >
+    Set `true` to allow Seqera to retrieve logs and reports for runs launched with Nextflow CLI.
+  Value: "Default: `false`"

platform-enterprise_docs/enterprise/configuration/overview.mdx

@@ -6,8 +6,8 @@ last updated: "2026-01-30"
 tags: [configuration]
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 :::note
 Nextflow Tower Enterprise is now Seqera Platform Enterprise. Existing configuration parameters, configuration files, and API endpoints that include _Tower_ currently remain unchanged.
@@ -105,10 +105,11 @@ Basic configuration options such as the Seqera instance server URL, application
 YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value:
 
 ```yaml
+
 ...
 mail:
-    smtp:
-        host: "your.smtphost.com"
+  smtp:
+    host: "your.smtphost.com"
 ...
 ```
 
@@ -136,10 +137,12 @@ Configuration values that control Seqera's interaction with databases and Redis
 **Database version requirements:**
 
 From Seqera Enterprise version 23.4:
+
 - MySQL 8 is the officially supported and tested database version.
 - MySQL versions 5.6 and 5.7 are no longer supported.
 
 From Seqera Enterprise version 24.2:
+
 - Redis version 6.2 or greater is required.
 - Redis version 7 is officially supported.
 
@@ -213,9 +216,9 @@ TOWER_REDIS_URL=redis://<redis private IP>:6379
 
 If you run the Redis service as a container in your Docker or Kubernetes installation, specify the service name as part of the `TOWER_REDIS_URL`:
 
-  ```bash
-  TOWER_REDIS_URL=redis://redis:6379
-  ```
+```bash
+TOWER_REDIS_URL=redis://redis:6379
+```
 
 </TabItem>
 </Tabs>
@@ -241,10 +244,11 @@ We recommend using managed cloud database services for production deployments.
 YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value:
 
 ```yaml
+
 ...
 mail:
-    smtp:
-        host: "your.smtphost.com"
+  smtp:
+    host: "your.smtphost.com"
 ...
 ```
 
@@ -316,10 +320,11 @@ Do not modify your crypto secret key between starts. Changing this value will pr
 YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value:
 
 ```yaml
+
 ...
 mail:
-    smtp:
-        host: "your.smtphost.com"
+  smtp:
+    host: "your.smtphost.com"
 ...
 ```
 
@@ -372,9 +377,10 @@ Enable rotation by setting the following configuration values:
 With rotation enabled and the previous and new key values set, secret key rotation will run as part of the Platform cron service during application startup. Normal application startup is not affected by this process, and Platform is fully operational while the credentials and secrets in your database are being encrypted using your new secret key.
 
 :::warning
+
 - To prevent data loss, perform a backup of your Platform database and securely back up your current crypto secret key before enabling and performing key rotation.
 - All backend pods or containers for your Enterprise deployment must contain the same previous and new secret key values in their Platform config and must be in a ready/running state before starting the Platform cron service.
-:::
+  :::
 
 The [Admin panel](../../administration/overview.md#encryption) **Encryption** tab displays the status of completed or errored encryption tasks.
 
@@ -433,10 +439,11 @@ Credentials and other secrets must not be stored in plain text in production env
 YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value:
 
 ```yaml
+
 ...
 mail:
-    smtp:
-        host: "your.smtphost.com"
+  smtp:
+    host: "your.smtphost.com"
 ...
 ```
 
@@ -492,10 +499,11 @@ Your organization's email security policy may prevent the `TOWER_CONTACT_EMAIL`
 YAML configuration keys in this table are listed in "dot" notation, i.e., a nested value:
 
 ```yaml
+
 ...
 mail:
-    smtp:
-        host: "your.smtphost.com"
+  smtp:
+    host: "your.smtphost.com"
 ...
 ```
 
@@ -527,9 +535,9 @@ To configure AWS SES as your Seqera email service:
 
 1. Set `TOWER_ENABLE_AWS_SES=true` in your environment variables.
 2. Specify the email address used to send Seqera emails with one of the following:
-    - the `TOWER_CONTACT_EMAIL` environment variable
-    - a `mail.from` entry in `tower.yml`
-    - a `/config/<application_name>/mail/from` AWS Parameter Store entry
+   - the `TOWER_CONTACT_EMAIL` environment variable
+   - a `mail.from` entry in `tower.yml`
+   - a `/config/<application_name>/mail/from` AWS Parameter Store entry
 3. The [AWS SES service](https://docs.aws.amazon.com/ses/index.html) must run in the same region as your Seqera instance.
 4. The [Seqera IAM role](../../compute-envs/aws-batch#iam-user-creation) must include the `ses:SendRawEmail` permission.
 
@@ -542,9 +550,9 @@ Do not replace the [Seqera-provided default image](../../functionality_matrix/ov
 <Tabs>
 <TabItem value="Environment variables" label="Environment variables" default>
 
-| Environment Variable      | Description                                                                                                     | Value                              |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| `TOWER_LAUNCH_CONTAINER`  | The container image to run the Nextflow execution. This setting overrides the launch container selection for all organizations and workspaces in your account. | Example: `quay.io/seqeralabs/nf-launcher:j17-23.04.3` |
+| Environment Variable     | Description                                                                                                                                                    | Value                                                 |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `TOWER_LAUNCH_CONTAINER` | The container image to run the Nextflow execution. This setting overrides the launch container selection for all organizations and workspaces in your account. | Example: `quay.io/seqeralabs/nf-launcher:j17-23.04.3` |
 
 </TabItem>
 </Tabs>
@@ -560,12 +568,12 @@ To configure API rate limit environment variables, you must add `ratelim` to the
 <Tabs>
 <TabItem value="Environment variables" label="Environment variables" default>
 
-| Environment variable   | Description                                                                   | Value           |
-| ---------------------- | ----------------------------------------------------------------------------- | --------------- |
-| `TOWER_ENABLE_OPENAPI` | Enable the OpenAPI documentation endpoint, e.g., [cloud.seqera.io/openapi/index.html](https://cloud.seqera.io/openapi/index.html). | Default: `false` |
-| `TOWER_RATELIMIT_PERIOD` | Specify the maximum number of HTTP requests that can be made during the `TOWER_RATELIMIT_REFRESH` period. | Default: `20` |
-| `TOWER_RATELIMIT_REFRESH` | API rate limit refresh period. | Default: `1s` |
-| `TOWER_RATELIMIT_TIMEOUT` | The waiting period before rejecting requests over the `TOWER_RATELIMIT_PERIOD` limit during the refresh period. | Default: `500ms` |
+| Environment variable      | Description                                                                                                                        | Value            |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| `TOWER_ENABLE_OPENAPI`    | Enable the OpenAPI documentation endpoint, e.g., [cloud.seqera.io/openapi/index.html](https://cloud.seqera.io/openapi/index.html). | Default: `false` |
+| `TOWER_RATELIMIT_PERIOD`  | Specify the maximum number of HTTP requests that can be made during the `TOWER_RATELIMIT_REFRESH` period.                          | Default: `20`    |
+| `TOWER_RATELIMIT_REFRESH` | API rate limit refresh period.                                                                                                     | Default: `1s`    |
+| `TOWER_RATELIMIT_TIMEOUT` | The waiting period before rejecting requests over the `TOWER_RATELIMIT_PERIOD` limit during the refresh period.                    | Default: `500ms` |
 
 </TabItem>
 </Tabs>
@@ -592,7 +600,7 @@ tower:
 
 ## Logging
 
-Logging-related configuration values to aid troubleshooting. See [Audit logs](../../monitoring/audit-logs) for more information on application event logging.
+Logging-related configuration values to aid troubleshooting. See [Audit logs](../../monitoring/audit-logs) for more information on application event logging. In 26.1, use `TOWER_AUDIT_LOG_V2_WRITE_MODE` to control whether audit events are written to the legacy schema, the v2 schema, or both. Use `TOWER_CRON_AUDIT_LOG_CLEAN_UP_ENABLED` to disable automatic audit log deletion, and restart Platform after changing audit log settings.
 
 <Tabs>
 <TabItem value="Environment variables" label="Environment variables" default>

platform-enterprise_docs/monitoring/audit-logs.md

@@ -2,30 +2,56 @@
 title: "Audit logs"
 description: An overview of application event audit logs in the Admin panel
 date created: "2024-04-08"
-last updated: "2025-07-17"
+last updated: "2026-05-11"
 tags: [logging, audit logs, admin panel]
 ---
 
 Root users can view application event audit logs from the [Admin panel](../administration/overview) **Audit logs** tab.
 
 :::info
-Application event audit logs are retained for 365 days by default. In Platform Enterprise, this retention period can be [customized](../enterprise/configuration/overview#logging).
+Application event audit logs are retained for 365 days by default. In Platform Enterprise, this retention period can be [customized](../enterprise/configuration/overview#logging). You can also disable automatic audit log deletion with `TOWER_CRON_AUDIT_LOG_CLEAN_UP_ENABLED`.
 :::
 
-### Audit log event format
+## Audit log versions in 26.1
 
-Audit log entries record the following event details:
+Seqera Platform Enterprise 26.1 introduces the audit log v2 schema as a **breaking change** for direct database consumers and custom ETL jobs.
 
-- **Type**: A brief event description, such as `user_sign_in`, `credentials_created`, etc.
-- **Target**: ID of the resource associated with the event, such as ID of created credentials, etc.
-- **Principal**: ID of the user that performed the action. User IDs for user-initiated events, `system` for Seqera-initiated events.
-- **Status**: Additional event information, such as workflow completion status, user sign-in method, etc.
-- **Organization ID**
-- **Organization name**
-- **Workspace ID**
-- **Workspace name**
-- **Client IP**: IP address of user/client initiating the event. Empty for Seqera-initiated events.
-- **Creation date**: Event timestamp in `YYYY-MM-DD-HH-MM-SS` format.
+- The legacy audit log schema remains in the `tw_audit_log` table.
+- The new audit log v2 schema is written to a separate `tw_audit_log_v2` table.
+- The v2 schema is not backward-compatible with the legacy schema. Field names, structure, and pagination behavior differ.
+- The v2 Admin panel view and CSV export are available when `TOWER_AUDIT_LOG_V2_WRITE_MODE` is set to `dual` or `v2`.
+
+Use `TOWER_AUDIT_LOG_V2_WRITE_MODE` to control how new audit events are written:
+
+- `v1`: Write new events to the legacy `tw_audit_log` table only. This is the default in 26.1.
+- `dual`: Write new events to both `tw_audit_log` and `tw_audit_log_v2`. This is the recommended 26.1 migration mode if you need to validate the v2 schema while keeping existing v1 integrations unchanged.
+- `v2`: Write new events to `tw_audit_log_v2` only.
+
+## Upgrade path for existing integrations
+
+If you have existing scripts, exports, or ETL processes that read from the legacy audit log schema, plan the 26.1 upgrade in two stages:
+
+1. Upgrade to 26.1 and set `TOWER_AUDIT_LOG_V2_WRITE_MODE=dual`.
+2. Validate your integrations against the v2 schema while your existing v1 readers continue to work from the legacy table.
+
+In the 26.1 migration plan, dual-write is transitional. Plan for 26.2 to make v2 the only write-side schema, while the legacy v1 data remains available for reads as long as your retention policy still covers the required historical period.
+
+## Audit log event format
+
+When audit log v2 is enabled, the Admin panel shows the following event details:
+
+- **Timestamp**: Event timestamp in ISO 8601 format.
+- **Event**: The audit event name, such as `user_sign_in` or `credentials_created`.
+- **Actor**: Whether the event was triggered by a user or by the system, including point-in-time user details for user-initiated events.
+- **Client**: Client IP address, user agent, and access token ID when available. Client details are empty for system-initiated events.
+- **Target**: The resource type, ID, and resource name associated with the event.
+- **Organization**: The organization ID and name for organization-scoped or workspace-scoped resources.
+- **Workspace**: The workspace ID and name for workspace-scoped resources.
+- **Correlation ID**: An identifier that links all audit events emitted as part of the same cascade action.
+
+For organization-scoped, personal workspace-scoped, or system-wide targets, the organization and workspace columns display `N/A` labels to indicate when a field does not apply to that resource scope.
+
+CSV exports use the same v2 schema and date filters as the Admin panel view. You can control the maximum export size with `TOWER_AUDIT_LOG_V2_CSV_EXPORT_MAX_LOGS`.
 
 ### Audit log events