Grails Audit Logging Plugin

This plugin is GORM agnostic, so you can use it with the GORM implementation of your choice (Hibernate 4 or 5, MongoDB, etc.).

Please note, that only Hibernate5 is tested during development. If an issue occurs with your ORM mapper, please file a GitHub issue.

While the plugin can log transactions for a MongoDB DataSource, it currently does not support MongoDB as an audit logging backend. If you use this plugin to log MongoDB transactions, you must configure a SQL DataSource for Audit Logging. See Ticket #181.

Add to your build.gradle project dependencies block:

Then run the following to refresh gradle dependencies:

For example:

This will create the Audit Domain class and adds to application.groovy:

Once created, you should open the generated file to adjust the mappings and constraints to suit your needs.

For every Domain class you want to be audited, implement the Auditable Trait.

For example:

If you additionally want to enable stamping, implement the Stampable Trait:

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, lastUpdatedBy to the domain class.