An attempt to Audit Log

How do product managers define Audit Log requirements for their product? How technical or descriptive should they be?

Developer:

How long should we show the Audit log for?

Do we want to surface the audit log on the UI or will a report do?

What will be the report format?

How long do we archive the audit log for?

What if there are large amounts of data? Downloading a report might take time

Do we want a common audit log or one for each module?

These are some of the common questions that product teams face during the preliminary discussions for Audit log with the Engineering team. Structuring the requirements is very important for product teams to cohesively communicate their expectations from this feature.

To do this, we need to start(as always) with the why?

Why do we need Audit Logging and how will it help?

An audit log(or audit trail) is a chronological sequence of activities that reflect a security event or occurrence. Audit Logs are mainly used by clients and stakeholders to track activities across the product to ensure adherence to system security and access.

(Attempt at) Structuring Audit Log Requirements

The requirements document can be split into the following parts:

Part A: The format the Audit Logs will be recorded in

This section will consist of a list of fields representing the format the events will be logged in. The most common list of fields that are used to record logs are:

• Actor — The username, uuid, API token name of the account taking the action
• Event Date & Time — The server date and time for when the event was triggered
• Event Description — A human readable description of the action taken
• Target Identifier — the identifier(ID or name) of the object or field that is being changed
• Action — the way in which the object was changed (the verb).
• Action Type — the corresponding C``R``U``D category.
• Value before the Event — The field or object value before the user performed an action
• Value after the Event — the field or object value after the user performed the action

Ofcourse, based on the product and usecases there might be additions/deletions here

Part B: Audit Log on the UI or via Report?

Now that we know what goes on in an Audit log, the next step would be to decide how this information will be consumed by the user.

There are many ways in which the Audit Log can be structured. For the purpose of this article, let us use the example of a school attendance system. A couple of approaches to audit log the School Attendance system are:

1. The “one log fits all” Audit Log: In this type of audit log, any change that has happened anywhere in the system will be displayed in one prime location and the user can view all the information there.

In the case of the school attendance, the administrator or principal can view the changes made to the system by accessing the “Audit Log” section in the website

2. The “customized” Audit Log: In this type, each module/each object will have changes listed under them.

In case of the school system, each student or teacher object may have changes made to them and the audit log will rest under a separate section inside the object. The hierarchy will be Student List → Student → Information and Audit Log

3. Audit Log reports: In this type, the user will either be able to download reports from the portal or have scheduled reports sent to them via email. Audit logs in report format are very helpful in systems where there are frequent changes made on a daily basis. These reports might take time to surface on the UI. Hence downloading them and receiving them via email will help admins process the reports faster.

PART C : Functional Requirements

1. Filters on the audit log: Irrespective of whether the audit log is displayed on the UI or downloaded in report format, the user should be able to apply filters to sift through millions of entries and retrieve relevant information. The user should be able to apply multiple filters on the log table at a given point of time.
2. Archiving Audit Logs: Since audit logs constitute any changes made to the system, some systems could generate millions of entries on a weekly basis. This will make the system very slow. Hence, archiving of an audit log is necessary to maintain system performance and improve speed. After a defined period(starting from 5 years) the entries should be archived by the system
3. Capping number of audit log entries: For systems that generate large amounts of data, retrieving that data may be a time consuming process. Therefore, while displaying audit log on the UI, the number of entries displayed or the time period should be capped. For eg: Upto 2000 entries can be displayed on the UI and if more information is required, the user can download it OR information upto 1 month or 2 months can be displayed and the remaining can be made available via report downloads to the user
4. Additional information: Apart from columns listed for Audit logs above, multiple columns can be added to the table depending on the system
5. Alerts or highlights: Critical information that is added, modified or removed can be highlighted to the user through alerts or flags. These alerts can be sent via email or can be flagged on the UI through icons or indications. This will help the user take necessary action

All this information will help provide clarity to the engineering team and will help build a robust audit logging system.