I am starting this topic because I had troubles understanding the dhis2 audit and changelog rationality. I hope that this compilation of information helps other people.
Currently, there are 2 different mechanisms for saving “what users are doing in the system”:
- Audit is registering almost any change or access to the system and store them. The information is stored in files and/or the database (or it is not stored), but it is not accesible using the API.
- Changelog is manually populating some tables, just for some changes (attributes, datavalues and tracked entitites) and offers some API endpoints to retrieve this data.
Even though some data will overlap, this 2 mechanisms are meant for different purposes:
- Audit is there in case an audit is needed, for example if there someone enter the system without permission it would be possible to check what he did and what he saw. The system does not offer any tool to inspect those data, but the data is there.
- Changelog is there to store and provide the history of some specific objects.
Naming is not helping, because everything used to be called audit (the file storing and the table storing). dhis2 team is trying to call the first one audit and the second one changelog but this distinction is not clear and it is still in progress.
In dhis2 v40, these db tables contain the string ‘audit’, but actually only the first one (audit) is an audit table. The other tables are changelog tables:
| Table name (until dhis2 version 41) | Table name (from dhis2 version 42) | type |
|---|---|---|
audit |
audit | |
dataapprovalaudit |
changelog | |
datavalueaudit |
changelog | |
programtempownershipaudit |
changelog | |
trackedentityattributevalueaudit |
trackedentitychangelog |
changelog |
trackedentityaudit |
changelog | |
trackedentitydatavalueaudit |
eventchangelog |
changelog |
trackedentityinstanceaudit |
changelog |
As a side note, the changelog that appears on Capture is coming from the changelog tables.
Audit
audit can be configured (in dhis.conf) for storing the information in files, in a table of a database, in both (files and database) or no storage using these parameters:
# Save data in the database. Since v2.38, the default value is 'off'.
audit.database = on / off
# Save data in the files. Since v2.38, the default value is 'on'.
audit.logger = on / off
Also in dhis.conf, you can configure the level of detail (scopes and types) to be saved. These are the default values:
audit.metadata= CREATE;UPDATE;DELETE
audit.tracker = CREATE;UPDATE;DELETE
audit.aggregate = CREATE;UPDATE;DELETE
You can find some audit documentation here: Audit - DHIS2 Documentation
Changelog
In changelog, each “change” (a row saved in a database table) has a type. The valid values for the typeare CREATED, UPDATED and DELETED (previous to version 41, the type READ could appear in the changelog. From version 42, the Flyway script will take care of removing the READ entries in the changelog tables).
In dhis.conf file, you can configure if you want to save the changelog for aggregate and tracker (you cannot select the types to be saved):
# Aggregate changelog, can be 'on', 'off'. Default: 'on'
changelog.aggregate = on
# Tracker changelog, can be 'on', 'off'. Default: 'on'
changelog.tracker = on
Note: At least in version 40.7, if the parameter “Enable tracked entity instance audit log” is NOT checked in the Tracked Entity Type, the changes are not saved in the database (table trackedentityattributevalueaudit).
You can find the changelog endpoints documentation here: API for audit (the fact that this page is still called audit doesn’t help to reduce the confusion) and here: Logging - DHIS2 Documentation (this link is in process of review).
Thanks to @enrico and @eirikhaugstulen for helping me in that way!