Grails Audit Logging
One of my projects needed a way to perform audit logging for Grails Hibernate domain classes. The audit log should contain at least the time and the property name and values that have been updated/inserted for a specific domain class.
I came across the Grails Audit-Loggin Plugin but unfortunately there were various reasons why the plugin wasn’t a good fit for us:
- configuration of the included fields was needed (instead of the excluded ones)
- usage of Hibernate stateless sessions for writing the AuditLog domain objects (better performance)
- some things seemed to be broken after writing the first integration tests, e.g. keeping the correct version number in the audit log
- more object-oriented structure to enable encapsulated unit tests and easier writing of integration tests
- last but not least: we wanted full control over the ongoing development of the plugin because the audit logging will be an important functionality of the application
In a nutshell: we started a new plugin that was initially based on the Grails Audit-Plugin to get some core components (like the
AuditLogListener) without starting completely from scratch.
Grails Hibernate Audit Log Plugin
That’s how we named the new plugin. Right now the audit log mechanism registers itself only by the
hibernateDatastore, no other datastores are supported. Besides completely changing the interal structure of the plugin, we threw some features over board we hadn’t any use for. We thought it would be better to keep it simple instead of preparing for complex scenarios we didn’t see any use for in our application.
As the time of writing, the plugin supports the following configuration variables:
auditLog.disabled switch is global one to turn off audit logging for the entire application. If it is
false an additional step is needed to enable audit logging for a particular domain class:
The domain class needs to have a static property
auditable = true. Alternatively, the static property might be referring to a map to provide local configuration attributes:
As a default setting all domain class properties are enabled for audit logging as long as
defaultInclude in the
Config.groovy) aren’t specified in the
auditable map. In the case of
include only the specified properties are logged, in the case of
exclude all other persistent properties are logged.
Once the audit log is enabled for a domain class all insert/update/delete operations will be kept track of by the plugin in the
audit_log table. Actually the table comes as GORM domain class
AuditLogEvent that is supplied by the plugin. For every property values that changes a new
AuditLogEvent is created. Here are the domain class properties:
All properties should be self speaking except for the
actor and the
uri properties (I guess). The
actor property has been introduced to keep track of the principal (name) that triggered the event. In the configuration options above the
actorClosure was shown that can be specified to retrieve the principal name from the HTTP request or session. The
uri contains the web URI that was used to initially trigger the domain class change.
Here is a testcase method that shows how the
AuditLogEvent will be filled when a new
Person object is saved to the DB:
AuditLogEvent class is a pure Grails domain class its dynamic methods can be used for querying the audit log table.
Be aware that the
oldValue (on upates) and the
newValue will be stored for every property (as per configuration) of the auditable domain class. One way to truncate these strings is by using the
auditLog.truncateLength option. In the most current version all values are persisted as type
String by using the default Groovy type coercion to
String. This will definitely change in future versions as needed.
The plugin is available at Github. A plugin zip can be created with
grails package-plugin from the root project directory. Right now the plugin is not stable enough to be published via the Grails plugin portal but as time goes by a stable version will definitely be published in the portal.
The Grails Hibernate Audit Log Plugin can be used for audit logging changes in Grails domain classes. Every domain class under target needs to specify a static
auditable property that is either
true or contains a
Map of local settings. The plugin is currently only accessible via Github but a stable version is planned to be released at the Grails plugin portal.