Audit Logs & Traceability
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Audit Logs & Traceability system provides a comprehensive, read-only historical record of all database mutations (INSERT, UPDATE, DELETE) across the IT Management System. Its primary purpose is to ensure compliance, accountability, and debugging capabilities by capturing who changed what data, at what time, and the specific differences between old and new states.
The system is designed with multi-tenancy at its core, ensuring that audit records are strictly scoped to the active company_id. Access is restricted to authorized IT staff and can be globally enabled or disabled via the system's UI configuration settings.
Sources: modules/audit_logs/index.php:5-15, modules/audit_logs/AGENT_NOTES.md:4-6
Architecture and Data Flow
The traceability system utilizes a dual-layer approach for capturing data changes: MySQL triggers for automated logging and PHP helper functions for manual or complex logging scenarios.
Logic Flow
- Mutation Event: A user or system process performs a database operation (e.g., updating an equipment record).
- Trigger Execution: Database-level triggers (
trg_{table}_audit_*) automatically capture the transition of data. - JSON Serialization: The "Old" and "New" values of the affected row are converted into JSON strings.
- Storage: A new record is inserted into the
audit_logstable containing the metadata, action type, and payload.
Key Components and Data Model
The audit_logs Table
This is the central repository for all system-generated history. It stores the context of the change (user, company, time) and the content of the change (table name, record ID, and values).
| Field | Description |
|---|---|
company_id | Scopes the log to a specific tenant. |
user_id | Links the action to a specific user; "System" if null. |
table_name | The database table affected by the change. |
record_id | The primary key ID of the row that was mutated. |
action | The type of operation: INSERT, UPDATE, or DELETE. |
old_values | JSON string of the record state before the mutation. |
new_values | JSON string of the record state after the mutation. |
changed_at | Timestamp of the event. |
Sources: modules/audit_logs/index.php:111-125, modules/audit_logs/AGENT_NOTES.md:10-12
Audit Capture Methods
The system verifies coverage through several patterns to ensure no data mutations go unrecorded:
- Database Triggers: The primary method. Defined in
database.sqlastrg_{table}_audit_insert,trg_{table}_audit_update, andtrg_{table}_audit_delete. - PHP Helpers: Functions like
itm_run_query(),itm_log_audit(), and various bulk helpers provide application-level logging when triggers are not applicable. - Traceability Logic: Standard CRUD modules utilize
cr_collect_audit_rows_for_where()to identify records before they are modified or removed.
Sources: scripts/check_audit_logs_coverage.php:150-165, scripts/check_audit_logs_coverage.php:210-225
Module Features and UI Configuration
Administrative Interface
The Audit Logs module (modules/audit_logs/index.php) is a read-only interface. It includes high-level Key Performance Indicators (KPIs) showing counts for different event types and a detailed search interface.
Multi-Tenant Policies
- Isolation: Users can only view logs where
audit_logs.company_idmatches their session. - Enablement: Audit logs can be entirely hidden if
enable_audit_logsis set to0in the system settings. - Pagination: Due to the high volume of audit data, page sizes are capped at 1000 rows even if "ALL" is selected.
Sources: modules/audit_logs/index.php:25-35, modules/audit_logs/index.php:57-65
Static Analysis and Maintenance
The project includes specialized scripts to ensure the integrity and coverage of the audit system.
- Coverage Analysis:
scripts/check_audit_logs_coverage.phpscans the codebase and schema to identify any tables or PHP modules that perform mutations without a corresponding audit trigger or hook. - Unique-Key Audit:
scripts/check_database_sql_company_name_uniques.phpensures that thecompany_idis properly scoped in unique indexes, which is critical for accurate record identification in logs. - System Diagnostics:
scripts/scripts.phpprovides a central index for running these maintenance tools in both Browser and CLI modes.
Sources: scripts/check_audit_logs_coverage.php:1-15, scripts/scripts.php:390-400, scripts/check_database_sql_company_name_uniques.php:5-15
Summary
The Audit Logs & Traceability system is a fundamental security component of the IT Management System. By combining database-level triggers with application-level hooks, it provides an immutable trail of system activity. This multi-layered approach ensures data isolation across tenants while providing administrators with the tools necessary for thorough forensic analysis and compliance auditing.
Sources: modules/audit_logs/AGENT_NOTES.md:50-52, AGENT_NOTES.md:8-12