Grails Audit Logging Plugin

Plugin 7.x supports Grails 8 and Java 21 only. Applications declare the runtime audit-logging artifact. Its Grails-Cli-Artifact manifest entry identifies org.grails.plugins:audit-logging-cli, which Grails 8 provisions only for CLI execution. This keeps CLI dependencies out of application startup and packaged artifacts while making audit-quickstart available from the direct Grails CLI and interactive shell.

Plugin 7.x does not support Grails 7. Use plugin 6.x for Grails 7 applications. Existing historical plugin lines remain available for earlier Grails releases.

Since plugin 5.x, auditing participates in the current Hibernate transaction and requires a Hibernate datastore. Persistence events from non-Hibernate datastores are not audited. The audit domain may use the same Hibernate datasource as the audited entity or another configured Hibernate datasource.

The 7.x plugin line supports Grails 8 and Java 21 only. Use the 6.x plugin line for Grails 7 applications.

Applications use only the runtime plugin dependency. During 7.0.x snapshot development, configure the scoped Maven Central Snapshots repository and add the snapshot version in build.gradle:

When released 7.x artifacts are available, use the released version from Maven Central. The snapshot is not a final release, and availability depends on publication.

Do not add org.grails.plugins:audit-logging-cli to the application. The runtime JAR advertises that companion with the Grails-Cli-Artifact manifest entry. Grails 8 provisions the companion only for CLI execution, so its dependencies stay out of bootRun, bootJar, and bootWar.

For a new application, run quickstart once with the direct Grails CLI:

Or start the interactive shell and run the same command:

The command creates the audit domain class and registers it with grails.plugin.auditLog.auditDomainClassName. Open the generated class to adjust mappings and constraints for the application. Preserve its required nullability constraints, then update the database schema through DDL or the database-migration plugin.

The generated dateCreated and lastUpdated properties default to java.util.Date. Both properties may use any type supported by Grails' DefaultTimestampProvider, but they must use the same type.

audit-quickstart is a legacy script packaged in META-INF/commands, not an ApplicationCommand. Do not use runCommand or expect a generated auditQuickstart Gradle task.

Add the Auditable trait to every domain class that should be audited:

To enable stamping, add the Stampable trait as well:

See Configuration to configure audit behavior.

Plugin 7.x supports Grails 8 and Java 21 only. It does not support Grails 7.

The CLI companion is now a separate artifact. Consumer applications still declare only org.grails.plugins:audit-logging. The runtime JAR advertises org.grails.plugins:audit-logging-cli through Grails-Cli-Artifact, and Grails 8 provisions it only when executing CLI commands. Do not add the companion directly.

audit-quickstart remains available as grails audit-quickstart <package> <DomainClass>, or from ./gradlew shell followed by audit-quickstart <package> <DomainClass>. It is a legacy script in META-INF/commands, not an ApplicationCommand, so do not use runCommand or a generated auditQuickstart task.

The audit domain class remains application-owned. Existing customizations continue to be the source of truth, and configuration keys remain under grails.plugin.auditLog.*.

The auditing and stamping traits, including Auditable and Stampable, keep their established usage. Follow the configuration guide for supported settings.

Prior versions of the plugin used a static property syntax to enable and customize logging:

Starting with version 3.0.0, the plugin uses an Auditable trait and/or a Stampable trait as both a marker as well as a way to configure and override auditing behavior.

For the first example, just adding implements Auditable will enable the default behavior.

For the second example above, you simply override the appropriate method on the Auditable trait, in this case the method is getLogIncluded():

To support unifying the configuration, trait, and context usage, some of the configuration properties have been renamed. The following table should help to map old values and types to the new ones:

Previously, the audit logging plugin had a transactional flag that indicated whether to include the audit log saves in a transaction. However, the audit logging plugin should really just participate (or not) in existing transactions and not make any attempts to control transactionality at that grain. For most usage, you want your Audit domain instances to be atomically created in the same transaction as the changes that are triggering them. If there’s no existing transaction for the changes, it’s not clear why there should be a transaction just for the audit events or vice versa.

The Audit instances are still saved in a new session within any existing transaction.

The handler callbacks such as onChange, onSave, etc. have been removed starting with version 3.0.0.

This behavior is already provided by Grails now using the before* and after* callback methods.

For example, you could do something like:

The actor closure has been replaced with a more formalized AuditRequestResolver strategy for resolving actor and URI information.

By default, the plugin uses the DefaultAuditRequestResolver, which gets Principal information from the current Grails web request context. This is essentially the same as the prior default actor closure.

If your application uses Spring Security, the plugin will register an instance of the SpringSecurityRequestResolver which will use the springSecurityService to resolve the current principal.

For other security frameworks, you can implement the AuditRequestResolver interface and register a bean named auditRequestResolver to override the resolver provided by the plugin.

The @Stamp annotation was removed in favor of a Stampable trait. This keeps the usage more in line with the direction of Grails in general as well as simplifying the implementation and usage.

However, there are some limitations to implementing this as a trait:

The stampAlways has been removed. If you want to mark all of your domain objects as stampable, you could define the following TraitInjector:

When enabled (default), per-property logging is enabled for all operations.

or you can enable verbose logging for specific event types using:

If both verbose=true and verboseEvents are set, verbose has precedence.

If verbose=true, or verboseEvents contains AuditEventType.DELETE, deletion of an entity will cause all properties of the deleted entity to be logged, except associations (Collections), as this is currently not possible. See issue #153

You can log the object-ids of associated objects. Logging will be performed in the format: "[id:<objId>]objDetails".

This setting is enabled by default.

You can configure properties to mask on a per-Domain-Class base. If properties are defined as masked, their values are not stored into the audit log table if verbose mode is enabled. Instead, a mask of "" will be logged.

By default, "password" properties are masked. You can mask property fields in domain classes like this:

If you enabled verbose mode, you can configure the truncation length of detail information in the oldValue and newValue columns (Default is 255). Configure the truncateLength in application.groovy:

You can disable auditing by config. If you disable auditing, event handlers are still triggered but no changes are comitted to the audit log table. This can be used e.g. if you need to bootstrap many objects and want to programmatically disable auditing to not slow down the bootstrap process or if you want to audit log by Enviroment.

This setting is "false" by default (auditing is enabled).

By default, only the entity class name is logged. If you want to log the entity full name (including the package name), you can enable full logging. Thanks to tcrossland for this feature.

This setting is "true" by default (full name is logged).

To ignore certain events on a per-domain base, override the getLogIgnoreEvents() method:

You can also ignore them either globally with:

Or for a specific logging context by using:

See the Context Overrides for help using AuditLogContext to override configuration for a block.

Example application.groovy configuration with various settings as described above:

To enable auditing using the default configuration, simply implement the Auditable trait.

For example:

This will enable auditing for the domain using your configuration in grails.plugin.auditLog merged with the defaults from DefaultAuditLogConfig.groovy (in the plugin jar).

There are many scenarios where you want to use a default configuration for most operations, but need to explicitly override for certain scenarios.

One fairly common example is the need to disable audit logging completely for a particular set of changes. This is often the case for bulk operations or operations that might be performed "by the system" such as cleanup, purge, expiration jobs, etc.

The context gives you programmatic control over configuration of auditing but you can go even finer grained, if needed, to control auditing on a per-entity basis.

To override auditing for a specific entity or based on runtime values, just override the trait method:

Another example is to override which properties get ignored for a specific entity:

Control the specific whitelist of attributes logged:

Customize the id that is logged for the entity, for example instead of using Author’s id property, log the Author’s name and age as Tolkien:85:

The ability to override and augment the default behavior provided by the trait is what makes the trait implementation so flexible.

You could also extend the trait entirely to override the default auditing behavior:

Audit logging usually requires auditing the user and/or request context for a specific action. The plugin supports a pluggable method of resolving request context by registering an auditRequestResolver bean that applications can override if needed.

Previous versions used an AST transformation to apply the stamping and could allow more configuration. For now, the stamping support has been boiled down to just the basic trait attributes and the ability to disable the plugin globally.

If you want to mark all of your domain objects as stampable, you could define the following TraitInjector:

The Audit Logging plugin registers a PersistenceEventListener (AuditLogListener) bean per datasource, which listens to GORM events.

The plugin registers a separate StampEventListener that responds to validate events. Ideally, we would stamp when an insert or update event occurs, but since the attributes are non-null by default, we need to populate them before the default validation is triggered.

The Plugin Descriptor (AuditLogListenerGrailsPlugin) configures the plugin during startup.

Enabling auditing on a Domain class is done by implementing the Auditable trait.

Enabling stamping on a Domain class is done by implementing the Stampable trait. This trait adds the properties dateCreated, lastUpdated, createdBy and lastUpdatedBy to the domain class.