Events that happen anywhere on an instance of LabKey Server are logged for later use by administrators who may need to track down issues or document what has occurred for compliance purposes. Different types of events are stored in separate log categories on the main Audit Log
. In addition, there are other locations where system and module-specific activities are logged.
Main Audit Log
The main Audit Log
is available to site administrators from the Admin Console
. Users with the site-wide role "Troubleshooter" can also read the audit log.
- Select (Admin) > Site > Admin Console.
- Under Management, click Audit Log.
- Use the dropdown to select the specific category of logged events to view. See below for detailed descriptions of each option.
The categories for logged events are listed below. Some categories are associated with specific modules that may not be present on your server.
- Assay/Experiment events: Assay run import and deletion, assay publishing and recall.
- Comments entered when assay data is deleted from Sample Manager or Biologics LIMS will be shown in the User Comment column.
- Attachment events: Adding, deleting, and downloading attachments on wiki pages and issues.
- Authentication settings events: Information about modifications to authentication configurations and global authentication settings.
- Client API Actions: Information about audit events created by client API calls. See Insert into Audit Table via API.
- Data Transaction events: Basic information about certain types of transactions performed on data, such as insert/update/delete of sample management data.
- Dataset events: Inserting, updating, and deleting dataset records. QC state changes.
- For dataset updates, the audit log will record only the fields that have changed. Both values, "before" and "after" the merge are recorded in the detailed audit log.
- Note that dataset events that occurred prior to upgrading to the 20.11 release will show all key/value pairs, not only the ones that have changed.
- Domain events: Data about creation, deletion, and modification of domains: i.e. data structures with sets of fields like lists, datasets, etc.
- Domain property events: Records per-property changes to any domain.
- If a user changed 3 properties in a given domain, the "Domain events" log would record one event for changes to any properties; the "Domain property events" log would show all three events.
- The Comment field of a domain property event shows the values of the attributes of the property that were created or changed, such as PHI level, URL, dimension, etc.
- Any comments entered when users delete Sample Types or Sources from Sample Manager or Biologics LIMS are recorded in the User Comments column.
- File batch events: Processing batches of files.
- File events: Changes to a file repository.
- Flow events: Information about keyword changes in the flow module.
- Group and role events: Information about group modifications and role assignments. The following are logged:
- Administrator created a group.
- Administrator deleted a group.
- Administrator added a user or group to a group.
- Administrator removed a user or group from a group.
- Administrator assigned a role to a user or group.
- Administrator unassigned a role from a user or group.
- Administrator cloned the permissions of a user from another user.
- Administrator renamed a group.
- Administrator configured a container to inherit permissions from its parent.
- Administrator configured a container to no longer inherit permissions from its parent.
- Inventory Events: Events related to freezer inventory locations, boxes, and items.
- LDAP Sync Events (Premium Feature): The history of LDAP sync events and summary of changes made.
- Link to Study events: Events related to linking assay and/or sample data to a study.
- List events: Creating and deleting lists. Inserting, updating, and deleting records in lists.
- Details for list update events show both "before" and "after" values of what has changed.
- Logged query events - Shows the SQL query that was submitted to the database. See Compliance: Logging.
- Logged select query events - Lists specific columns and identified data relating to explicitly logged queries, such as a list of participant id's that were accessed, as well as the set of PHI-marked columns that were accessed. See Compliance: Logging.
- Logged sql queries (Premium Feature): SQL queries sent to external datasources configured for explicit logging, including the date, the container, the user, and any impersonation information. See SQL Query Logging.
- Message events: Message board activity, such as email messages sent.
- Pipeline protocol events: Changes to pipeline protocols
- Project and Folder events: Creation, deletion, renaming, and moving of projects and folders. Changes to file roots are also audited.
- Query export events: Query exports to different formats, such as Excel, TSV, and script formats.
- Query update events: Changes made via SQL queries, such as inserting and updating records using the query. Note that changes to samples are not recorded in the query update events section; they are tracked in sample timeline events instead.
- Sample timeline events: Events occurring for individual samples in the system.
- Creation, update, storage activity, and check in/out are all logged.
- Comments entered when Samples are deleted from Sample Manager or Biologics LIMS will be shown in the User Comment column.
- Sample Type events: Summarizes events including Sample Type creation and modification.
- Samples workflow events: Events related to jobs and tasks created for managing samples in Sample Manager and Biologics.
- Search: Text searches requested by users and indexing actions.
- Signed Snapshots: Shows the user who signed, i.e. created, the signed snapshot and other details. For a full list, see Electronic Signatures / Sign Data
- Site Settings events: Changes to the site settings made on the "Customize Site" and "Look and Feel Settings" pages.
- Study events: Study events, including sharing of R reports with other users.
- Study Security Escalations: Audits use of study security escalation.
- TargetedMS Representative State Event: When uploading multiple Panorama libraries, logs the number of proteins in a conflicted state and their resolutions.
- User events: All user events are subject to the 10 minute timer. For example, the server will skip adding user events to the log if the same user signs in from the same location within 10 minutes of their initial login. If the user waits 10 minutes to login again then the server will log it.
- User added to the system (via an administrator, self sign-up, LDAP, or SSO authentication).
- User verified and chose a password.
- User logged in successfully (including the authentication provider used, whether it is database, LDAP, etc).
- User logged out.
- User login failed (including the reason for the failure, such as the user does not exist, incorrect password, etc). The IP address from which the attempt was made is logged for failed login attempts. Log only reflects one failed login attempt every 10 minutes. See the Primary Site Log File for more frequent logging. Failed login attempts using API Keys are not logged. Instead, see the Tomcat Access logs.
- User changed password.
- User reset password.
- User login disabled because too many login attempts were made.
- Administrator impersonated a user.
- Administrator stopped impersonating a user.
- Administrator changed a user's email address.
- Administrator reset a user's password.
- Administrator disabled a user's account.
- Administrator re-enabled a user's account.
- Administrator deleted a user's account.
Allowing Non-Admins to See the Audit Log
By default, only administrators and troubleshooters can view audit log events and queries. If an administrator would like to grant access to read audit log information to a non-admin user or group, they can do so assigning the role "See Audit Log Events". For details see Security Roles Reference
Other event-specific logs are available in the following locations:
|Logged Event||Location of Log|
|Assays Linked to a Study||See Link-To-Study History.|
|Datasets||Go to the dataset's properties page, click Show Import History. See Dataset Properties.|
|ETL Jobs||See ETL: Logs and Error Handling.|
|Files Web Part||Click Audit History. See File Repository Administration.|
|Lists||Go to (Admin) > Manage Lists. Click View History for the individual list.|
|Project Users||Go to (Admin) > Folder > Project Users, then click History.|
|Queries (for external data sources)||See SQL Query Logging.|
|Site Users||Go to (Admin) > Site > Site Users, then click History.|
|All Site Errors||Go to (Admin) > Site > Admin Console > Settings and click View All Site Errors under Diagnostics. Shows the current contents of the labkey-errors.log file from the <CATALINA_HOME>/logs directory, which contains critical error messages from the main labkey.log file.|
|All Site Errors Since Reset||Go to (Admin) > Site > Admin Console > Settings and click View All Site Errors Since Reset under Diagnostics. View the contents of labkey-errors.log that have been written since the last time its offset was reset through the Reset Site Errors link.|
|Primary Site Log File|| Go to (Admin) > Site > Admin Console > Settings and click View Primary Site Log File under Diagnostics. View the current contents of the labkey.log file from the <CATALINA_HOME>/logs directory, which contains all log output from LabKey Server.|
Setting Audit Detail Level
For some table types, you can set the level of auditing detail on a table-by-table basis, determining the level of auditing for insert, update, and delete operations. This ability is supported for:
- Study Datasets
- Participant Groups
- Sample Types
- Inventory (Freezer Managment) tables
- Electronic Lab Notebooks
You cannot use this to set auditing levels for Assay events.
Audit Level Options
Auditing level options include:
- NONE - No audit record.
- SUMMARY - Audit log reflects that a change was made, but does not mention the nature of the change.
- DETAILED - Provides full details on what change was made, including values before and after the change.
When set to detailed, the audit log records the fields changed, and the values before and after. Hover over a row to see a (details)
link. Click to see the logged details.
The audit level is set by modifying the metadata XML attached to the table. For details see Query Metadata: Examples
Write Audit Log to File System
Audit Log messages can be written to the filesystem in addition to being stored in the database. Such additional archiving may be required for compliance with standards and other requirements.
To configure filesystem logging, an administrator edits the log4j2.xml file, which is deployed to the $LABKEY_HOME/build/deploy/labkeywebapp/WEB-INF/classes directory. Note that any other options permitted by log4j
can be enabled, including writing the audit log content to the console, using multiple files, etc.
The administrator first creates a log name corresponding to the name of the particular log to record on the filesystem. For example, the GroupAuditEvent log would be written to "labkey.audit.GroupAuditEvent." Within the default log4j2.xml file, there is a default template available showing how to include the audit logs and columns to be written to each designated file. See comments in the file close to this line for more detail:
<Logger name="org.labkey.audit.event.UserAuditEvent" additivity="false" level="OFF">
These log messages are not part of any transaction, so even if the writing of the audit event to the database fails, the writing to the filesystem will already have been attempted.
The format of audit messages written to the designated file(s) or other output source is:
<eventType> - key: value | key: value | …
UserAuditEvent - user: firstname.lastname@example.org (1003) | auditEventCreatedBy: email@example.com (1003)
| container: / (48d37d74-fbbb-1034-871f-73f01f3f7272) | comment: firstname.lastname@example.org logged in
successfully via Database authentication. |
Audit Event Types
The audit event types available for writing to the filesystem include, but are not limited to:
- AppPropsEvent - written upon change to a System setting (such as one of the Compliance settings)
- AssayPublishAuditEvent - written when an assay is published
- AttachmentAuditEvent - one action that triggers this is to attach a file to a message
- AuthenticationProviderConfiguration - written upon a change to authentication settings (e.g., enable/disable self-signon)
- ClientAPIActions - triggered when client script code explicitly calls the log
- ComplianceActivityAuditEvent - written from the complianceActivities module
- ContainerAuditEvent - creating or deleting containers are two examples
- DatasetAuditEvent -
- DomainAuditEvent - creating a new list will create a domain audit event
- GroupAuditEvent - creating or modifying a group will create one of these events
- ListAuditEvent - updating a list will create such an event
- LoggedQuery - written from the compliance module
- MessageAuditEvent - generated when an email message is sent
- SampleSetAuditEvent (legacy name used for Sample Type Audit Events)