Logging Guidelines

Logging and system-log conventions for the library-management backend.

Overview

The project requires system maintenance/log support for key operation logs, data backup support, and exception tracing. MySQL should include a system log table, illustratively system_logs, for durable audit and troubleshooting records.

What to Log

Record key operations that affect security, data integrity, or inventory:

Login success/failure and logout for administrator, librarian, and reader roles when applicable.
Permission changes, role changes, and denied protected operations.
Book create, update, delete, category maintenance, and warehousing/intake.
Borrow, return, renew, overdue handling, and automatic inventory status updates.
Reader profile, eligibility, and contact information changes.
Data backup events and restore-related maintenance actions.
Unhandled exceptions and failed database operations with safe context.

System Log Fields

When the schema is introduced, system_logs should preserve enough information to trace actions without exposing sensitive data. Useful fields include an ID, operator ID, operator role, operation type, target entity/table, target ID, result status, message, timestamp, and request IP when available.

Sensitive Data

Do not log passwords, raw credentials, full request bodies, database connection strings, or unnecessary personal data. Prefer IDs and operation summaries over large before/after payloads.

Exception Tracing

Server logs may contain technical stack traces for developers. User-facing JSP pages should receive concise messages. Durable system logs should record the operation, actor, failure category, and correlation details needed to locate the server-side exception.

Scenario: Admin User Management Audit And System Log Viewer

1. Scope / Trigger

Trigger: administrator user/account management writes durable audit rows, and /admin/system-logs reads those rows through a Servlet -> Service -> DAO -> MySQL flow.
The viewer is read-only; mutation belongs to the business service that owns the operation being audited.

2. Signatures

DB signature: system_logs(id, operator_id, operator_role, operation_type, target_table, target_id, result_status, message, request_ip, created_at).
DAO signatures: SystemLogDao.search(criteria), SystemLogDao.findOperationTypes(), and SystemLogDao.create(connection, log).
Service signatures: SystemLogService.searchLogs(AuthenticatedUser actor, SystemLogSearchCriteria criteria) and user-management methods that accept requestIp for audit rows.
Routes: GET /admin/system-logs; user-management audit sources include POST /admin/users, POST /admin/users/update, and POST /admin/users/deactivate.

3. Contracts

/admin/system-logs requires VIEW_SYSTEM_LOGS; user-management write routes require MANAGE_USERS.
Search criteria fields are operationType, keyword, createdFrom, and createdTo; dates use YYYY-MM-DD.
System-log result rows are newest-first and may include missing joined user names. Entity display helpers must render an operator label as display name, username, User #<id>, or System in that order.
JSPs must use safe JavaBean helpers such as operatorLabel, operatorMetaText, resultStatusCode, and resultStatusName; do not put raw database status strings into CSS class names.
Audit messages must summarize actions with IDs/usernames/roles, never passwords, raw credentials, password hashes, or request bodies.

4. Validation & Error Matrix

Unauthenticated or unauthorized viewer -> You do not have permission to view system logs.
operationType longer than 64 characters -> field error on operationType.
keyword longer than 120 characters -> field error on keyword.
Invalid date text -> Start date must use YYYY-MM-DD. or End date must use YYYY-MM-DD.
createdFrom after createdTo -> field error on createdTo.
DAO failure while loading logs -> server-side Java logger entry plus System log service is temporarily unavailable. Please try again later.
Audit insert failure inside a user-management transaction -> rollback the mutating operation and return the user-management unavailable message.

5. Good/Base/Bad Cases

Good: user creation and its user.create audit row commit in the same transaction, including operator_id, operator_role, target_table=users, target_id, result_status=success, and request_ip.
Base: a system log with operator_id but no joined user displays as User #<id>, not as System.
Bad: a JSP renders class="status-${log.resultStatus}" from an arbitrary database value.

6. Tests Required

Service checks for permission denial, criteria validation, date-range validation, DAO failure fallback, newest-first/search DAO contract, and empty results.
User-management service checks for audit log creation on create/update/ deactivate and rollback when audit creation fails inside the transaction.
Entity/display checks for operator fallback labels and normalized result status CSS codes.
JSP scan confirming no scriptlet, SQL, JDBC, password, or password-hash rendering in admin/log pages.

7. Wrong vs Correct

Wrong

<span class="status-${log.resultStatus}">${log.resultStatus}</span>

Correct

<span class="status-${log.resultStatusCode}">
  <c:out value="${log.resultStatusName}" />
</span>

5.4 KiB Raw Blame History