Grails Audit Logging Plugin

The Audit Logging plugin adds event-based audit logging to a Grails application. It was originally maintained by symentis and donated to the Grails community.

Requirements

Plugin 7.x supports Grails 8 and Java 21 only. Use plugin 6.x for Grails 7 applications.

Installation

Normal applications declare only the runtime plugin. While using the 7.0.0 snapshot, add the scoped Maven Central Snapshots repository and dependency to build.gradle:

repositories {
    maven {
        url = uri('https://central.sonatype.com/repository/maven-snapshots/')
        mavenContent { snapshotsOnly() }
        content {
            includeModule('org.grails.plugins', 'audit-logging')
            includeModule('org.grails.plugins', 'audit-logging-cli')
        }
    }
}

dependencies {
    implementation 'org.grails.plugins:audit-logging:7.0.0-SNAPSHOT'
}

When released 7.x artifacts are available, resolve them from Maven Central with the released version instead. Do not add audit-logging-cli to your application dependencies.

What Changed in 7.x

The runtime plugin and its CLI companion are separate artifacts. The runtime JAR advertises org.grails.plugins:audit-logging-cli through Grails-Cli-Artifact, so Grails 8 provisions the companion automatically only when running CLI commands. This keeps CLI dependencies out of bootRun, bootJar, and bootWar.

Plugin 7.x also moves to the Grails 8 and Java 21 baseline. It is not compatible with Grails 7.

First-Time Setup

For a new application, create an audit domain artifact once:

grails audit-quickstart org.example.audit AuditLogEvent

You can run the same command from the interactive shell:

./gradlew shell
grails> audit-quickstart org.example.audit AuditLogEvent

Quickstart generates an audit domain class and registers its fully qualified name under grails.plugin.auditLog.auditDomainClassName. Review the generated mappings and constraints, then update the database schema before using the application. Keep the required nullability constraints intact.

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

To audit a domain class, implement Auditable:

import grails.plugins.orm.auditable.Auditable

class Book implements Auditable {
    String title
}

Upgrading Existing Applications

When upgrading an application from plugin 6.x, keep your customized AuditLogEvent class and existing grails.plugin.auditLog.* configuration. Do not rerun quickstart: it does not overwrite the existing class and can append duplicate configuration. If you intentionally redesign the audit domain, update the class and configuration manually.

Move the application to Grails 8 and Java 21, change the runtime dependency to plugin 7.x, and refresh dependencies. The companion is still discovered from the runtime plugin, so no explicit CLI dependency is needed.

CLI Companion Architecture

Grails discovers the CLI companion from the runtime plugin manifest. The companion is added to the CLI classpath only for direct grails commands or the interactive shell, not to the runtime application classpath.

This separation is intentional. It avoids pulling CLI-only dependencies into application startup and packaged application artifacts while preserving the audit-quickstart command.

Troubleshooting

If audit-quickstart is unavailable:

1. Confirm that the application declares the runtime audit-logging dependency, not the CLI companion.
2. For snapshots, confirm that https://central.sonatype.com/repository/maven-snapshots/ is configured.
3. Keep grails.cliAutoProvision enabled.
4. Refresh the CLI classpath with ./gradlew --refresh-dependencies shell.
5. Inspect resolved CLI dependencies with ./gradlew dependencies --configuration grailsCli.

Documentation

• For Grails 8 and plugin 7.x development, see the Snapshot User Guide.
• For Grails 7 and plugin 6.x, see the 6.0.x User Guide.
• For older releases, see the 4.x User Guide, 3.x User Guide, and 2.x User Guide.

Compatibility

Grails Version	Audit Logging Plugin Line
Grails 8.0.x	7.0.x branch
Grails 7.0.x	6.0.x branch
Grails 4.0.x	5.0.x branch (recommended); 4.x_maintenance remains available through Grails 4.0.9
Grails 3.3.x	3.x_maintenance branch
Grails 3.0.x-3.2.x	2.x_maintenance branch
Grails 2.x	1.x_maintenance branch

Issue Management

See GitHub Issues.

Pull Requests

Pull requests are welcome. Please add integration tests for new features to the audit-test application.

Contributors

Special thanks to all the contributors (in alphabetical order):

• Aaron Long
• Alan Wikie
• Aldrin
• Andrey Zhuchkov
• Ankur Tripathi
• Burt Beckwith
• bzamora33
• Danny Casady
• Dennie de Lange
• Dhiraj Mahapatro
• Elmar Kretzer
• Felix Scheinost
• Fernando Cambarieri
• Graeme Rocher
• Jeff Palmer
• Jorge Aguilera
• Juergen Baumann
• Madhava Jay
• Matt Long
• Matthew A Stewart
• Paul Taylor
• Robert Oschwald
• Sami Mäkelä
• Sebastien Arbogast
• Semyon Atamas
• Shawn Hartsock
• Tom Crossland

Project lead: TBD.

---

YourKit supports Grails open source projects with its Java Profiler. YourKit, LLC creates tools for profiling Java and .NET applications. See YourKit Java Profiler and YourKit .NET Profiler.