We’re excited to announce our plans to release a new and improved set of Jira, Confluence and Bitbucket auditing functionality to our Server and Data Center customers.
In this document we want to walk the vendor community through these improvements ahead of release to allow appropriate planning and assist in better taking advantage of the newly introduced APIs.
Core points
Core auditing functionality has been re-implemented as a cross-product, cross-platform plugin. While the same plugin is used for both Server and Data Center, some differing functionality is exposed to the customer depending on their license.
We expose a new management experience to help customers choose the right level of event coverage and retention to suit their organisation. Customers are able to configure the audit coverage in multiple areas based on the following levels:
1… Base: Logs core events. This provides a minimum level of insight into the instance activity.
2… [Data Center only] Advanced - Logs more than just core events. This provides a more detailed picture of instance activity.
3… [Data Center only] Full - Logs all events for a comprehensive record of the instance activity.
4… Off - Turns off logging for this area.
The changes introduce improved search and filtering capabilities.
[Data Center only] The new auditing framework includes a significant expansion of Audit Event coverage across the products for a more complete record of the customer instance.
[Data Center only] Customers will now be able to selectively export audit log results.
[Data Center only] We’ve added write to file functionality for integration with best of breed log consumption tools like Splunk and ELK.
Milestone features
Milestone 1
Milestone 1.1
Updated UI
Audit Contents Translation support
File externalization
People & Project filters
Coverage/Retention Controls
Increased coverage
Export and selective export
Object Linking (user and location)
Full text search and time filter
Audit Delegation (users can see audit logs of project/space/etc they have admin permissions for)
Planned versions for release
The following product releases are expected to contain the new auditing framework
A few principles which may be of particular note to the vendor community:
The database is ephemeral and should be used by customers for short/medium-term storage. Long term retention is achieved using the write to file integration, or manual export.
Security events, data egress and data removal events are critical events for logging.
High-frequency audit events should be put in the Full category.
New APIs
There are two new APIs for producing and consuming auditing events.
Producing events
Import com.atlassian.audit.api.AuditService , can be done via
in atlassian-plugin-xml
spring scanner, i.e. @ComponentImport
spring java configuration
spring xml configuration
invoke void audit(@Nonnull AuditEvent event) method, for example
For troubleshooting you can also check and verify that the bundled plugin “Atlassian Audit Plugin” is enabled on your system (it is the plugin who provides the REST API).
As for the previous audit REST API from the link https://docs.atlassian.com/ConfluenceServer/rest/7.5.0/#api/audit-getAuditRecords - it should still work in the same way (because Confluence has to support all existing REST APIs). But it’s implementation has been changed to use the new auditing framework under the hood. I recommend to migrate from the old REST API to the new one, because it’s more powerful and better reflects the current model.
I’m trying to add auditing to our plugin, but cannot wrap my head around how this is supposed to work. More specifically, I would like to produce audit events when our plugin creates and deletes its own plugin-specific objects.
I’ve looked at the Jira source code (e.g., IssueLinkingHandlerImpl.java) but that code uses the API in a different way: it uses constants like com.atlassian.jira.auditing.AuditingCategory.ISSUE to create AuditType:s, which are then passed to auditService.audit().
Since neither source code or documentation for com.atlassian.audit.api.AuditService seem to be available, I’m not sure how to use these constants.
Also, I’m adding the package via a pom.xml dependency:
Hey Gustav, Audit API is designed to allow consumer specifying category/action/level, in your example you either call i18n api if you have Audit API version 1.7.0+ (assuming those properties key are defined in your plugin i18n files)
[ERROR] Failed to execute goal on project (plugin):
Could not resolve dependencies for project (plugin):
Could not find artifact com.atlassian:atlassian-audit-api:jar:1.5.0 in atlassian-public (https://maven.atlassian.com/repository/public) -> [Help 1]
We are in the process of deprecating all maven.atlassian.com urls. If you are using any of those, please change them to a url mentioned above as soon as practical. We will update the developer community more widely when we expect to decommision the old maven.atlassian.com urls permanently.
Are you planning to also create a wiki page in the Developer documentation? Just Javadoc is typically not sufficient to understand how to use a component and what the intension and scope is (like what is written and discussed above). Some background and sample code would be appriciated.
