Auditing in Confluence
Audit log features
Audit logging in Confluence Data Center has the following features:
| Functionality | Available in Data Center |
|---|---|
| Coverage areas |  Yes |
| Selecting coverage areas | Yes |
| Setting database log retention | Yes |
| Storing audit logs in two locations | Yes |
| Integrating with 3rd party monitoring tools | Yes |
| Exporting the latest 100,000 results | Yes |
| Filter by category and summary | Yes |
| Exporting filtered results | Yes |
| Space-level audit log | Yes |
Audit log storage
Confluence writes audit logs to the database and a log file. The database helps to easily view, search, and export data.
The log file saves you the effort of periodically exporting your audit logs from the database for long-term storage. However, its main purpose is to easily integrate with a third-party logging platform.
For Confluence Data Center clustered instances, each node has its own log, which can be found in the <home-directory/log/audit> directory. The log is stored as a JSON file.
View the audit log
To view the global audit log in Confluence:
- Go to Administration
> General Configuration - Select Audit log.
- Select an event to expand it and see details.
Different details will be shown depending on the event itself. These can include:
- IP address — IP address of the user who performed the action. This is not recorded for system-generated events.
- Load balancer/proxy IP address — IP address of the load balancer or proxy server that forwarded the request.
- Node ID — unique ID of the cluster node where the action was performed.
- Method — depending on how the action was performed, this will be either Browser (end user) or System (system process).
View the space audit log
System admins, Confluence admins, and space admins can also access audit logs for a specific space if they have permission to administer that space.
The space audit log records events related to space permissions and configuration, user actions within the space, and some events related to space security (for example, events related to accessing and granting permissions to restricted pages with a particular space).
To view the audit log for a specific space, go to Space tools > Audit log.
Search and filter the audit log
You can search the log by keyword, and narrow your results by date, author, and space. You can also filter by category and summary.
Your query can be up to 100 characters long. To speed up the search, we only search the most recent 1 million events. After this search is performed, you can choose to run a full database search. If you have a large or busy Confluence site, running a full search can take a while.
Can't find a specific event?
Changing coverage level changes the individual events that are logged. If you can't find a specific event, it might be because the coverage level was changed, and these events were not logged for a period of time. Check the audit log configuration events to determine if this might be the case.
Export the audit log
You can export up to 100,000 latest or filtered events as a CSV file. If you have more than 100,000 events, only the 100,000 newest events are included in the export.
To export the audit log:
- Go to Audit log, then select Export.
- Select to export the latest 100,000 or filtered results.
- Confirm by selecting Export.
Space admins can also export from the space-level audit log.
Edit log settings
In the audit log settings, you can decide how long you want to retain the logged events in the database and the areas from which you want to collect the logs.
Update database retention
The database retention is limited by the retention period, with a maximum of 10 million records.
To update the database retention period:
- Select More options> Settings.
- Enter the period of time. This can be in days, months, or years.
- Select Save.
If you choose a long retention period, it can affect the size and performance of your database. Learn more about setting an optimal retention period for your Confluence instance.
If you decide to lower the retention period, all the events that exceed the newly set period will be deleted, and disappear from the page. It's a good idea to create a backup before you lower the retention period.
If you migrated from a previous Confluence version, your default retention period is 20 years. If you have a new Confluence installation, it’s 3 years.
Select events to log
The events that are logged are organized in categories that belong to specific coverage areas.
For example, import and export-related events are logged in the Import/Export category that belongs to the Local configuration and administration coverage area. For all coverage areas and events logged in each area, see Audit log events in Confluence.
To adjust the coverage:
- Go to More options> Settings.
- In the Coverage level drop-down, select the level to log the events you need, or Off to stop collecting events from a particular area.
Coverage level definitions
Coverage levels reflect the number and frequency of events that are logged.
Coverage level | Definition |
|---|---|
Off | Turns off logging for this coverage area. |
Base | The lowest level of coverage. Logs only the core events. Base coverage provides a minimum level of insight into your site’s activity. |
Advanced | Logs all the events covered in Base, plus additional events. Advanced coverage provides a more detailed record of your site’s activity. |
Full | The highest level of coverage available. Logs all events in Base and Advanced. Depending on your site's activity, setting your coverage level to Full can generate a large volume of events, which can impact your database and disk space. |
Change the audit log file retention
You can choose how many audit log files to store in the local home directory on each node. By default we store 100 files. Make sure you've provisioned enough disk space for these files, especially if you have set the logging level to Advanced or Full.
To change the file retention setting:
- Go to More options> Settings.
- Enter the maximum number of files to be stored per node and select Save.
Once a node reaches the log file retention limit, the oldest one is deleted. If you need to keep these logs, for example for compliance purposes, you may want to manually back up the files in this directory on a regular basis, or send them to a third party logging platform. See Audit Log Integrations in Confluence.
Integrate with external software
You can use the log file to integrate with third-party tools such as ELK, Splunk, Sumologic, and Amazon CloudWatch. For more information on integrations, see Audit Log Integrations in Confluence.
Audit log and migration
Migrate database
If your database contains more than 10 million events stored in your database, and you move to a new database, only the latest 10 million will be migrated, and the remaining data will be removed.
To have access to your older events, you can create a backup before you migrate and access the data in the backup.
Migrate from a previous Confluence version
Migrating audit log records can take a while, depending on the size of the audit log and your database.
Auditing and the REST API
The audit log can also be accessed via the REST API.