LogManager

LogManager

Overview

LogManager is a singleton class responsible for centralized audit logging of entity changes across the entire system. It serves as the primary audit trail mechanism, capturing detailed information about state modifications, actor identities, and field-level updates.

General Purpose:

Audit Trail: Creates comprehensive logs for all entity state changes
Compliance: Supports regulatory requirements with detailed change tracking
Integration: Works with StateManager to automatically log state modifications
Centralized Storage: Uses MongoDB for log storage and querying
Architectural Pattern: Singleton class with 'default' instanceId for system-wide logging

Data Structure

State Schema

interface LogManagerState {
  private: {}
  public: {}
}

The LogManager uses minimal state as it operates as a stateless logging service, storing all data in MongoDB.

Log Entry Structure

interface Log {
  id: string
  classId: ClassKey
  entityId: string
  entityType: string
  timeStamp: Date
  isLargeLog: boolean
  fieldUpdates: LogFieldUpdate[]
  actor: StateManagerActor
  additionalData?: Record<string, any>
}

interface LogFieldUpdate {
  key: string
  operation: LogFieldUpdateOperation
  oldValue: string  // JSON encoded
  newValue: string  // JSON encoded
  isLarge?: boolean // Indicates if field data is stored in external file
}

interface LogInDatabase {
  _id: string
  classId: ClassKey
  entityId: string
  entityType: string
  timeStamp: Date
  fieldUpdates: LogFieldUpdate[]
  actor: StateManagerActor
  largeLogPath?: string  // Path to RDK file containing large field values
  additionalData?: Record<string, any>
}

Enums and Types

enum LogFieldUpdateOperation {
  ADD = 'add',
  REMOVE = 'remove',
  REPLACE = 'replace',
  OTHER = 'other'
}

Core Functionality

Audit Trail Management

Change Tracking: Records detailed information about entity modifications
Actor Attribution: Captures who performed each action with full context
Timestamp Recording: Maintains precise timing of all changes
Field-Level Granularity: Tracks individual field modifications with before/after values

Large Log Support

Size Management: Automatically handles field values exceeding the size limit (1KB per field)
Field-Level Storage: Each log field value has a size limit; values exceeding this are marked as large logs
External Storage: Stores large field values in RDK file storage (separate from MongoDB)
Transparent Retrieval: getLog method automatically reconstructs complete logs by fetching large field data
Performance Optimization: List operations exclude large fields for faster pagination
File Naming: Uses pattern LARGE_LOG_${entityType}_${entityId}_${logId}.json for large log files

Field Masking Support

Sensitive Data Protection: Masks sensitive fields (passwords, PII) in logs
Configurable Masking: Supports custom field masking configuration per implementation
Privacy Compliance: Ensures audit logs don't expose sensitive information

JSON Patch Integration

StateManager Integration: Automatically processes JSON Patch operations from state changes
Operation Mapping: Converts JSON Patch operations to structured log entries
Comprehensive Coverage: Captures add, remove, replace, and custom operations

API Methods

Log Management

addLogEntry (STATIC) - Creates a new log entry for entity changes
- Automatically detects and handles large field values exceeding the size limit
- Stores large fields in RDK file storage with metadata in MongoDB
- Validates log data structure using Zod schema
- Supports additional metadata for enhanced context
- Authorization: All class identities allowed
getLogEntries (STATIC) - Retrieves paginated log entries for specific entities
- Supports filtering by classId and entityId
- Includes pagination with configurable limits (1-100 per page)
- Returns sorted results with total count and page information
- Large field values are truncated in list view for performance
- Authorization: All class identities allowed
getLog (STATIC) - Retrieves complete log details including large field values
- Fetches full log entry with all field values reconstructed
- Automatically retrieves and merges large field data from RDK storage
- Returns complete field updates with original values
- Authorization: program_management_user only

Method Types:

STATIC - Stateless utility methods that don't require instance state

Key Features

Architecture Pattern: Singleton class with 'default' instanceId
Integration Points: StateManager integration via LogManagerLogger
Authorization: All class identities for internal operations, program_management_user for getLog method
Data Storage: MongoDB for metadata and regular field values, RDK file storage for large field values
Log Retrieval: LogFetcher service centralizes database and file access
Performance: List queries exclude large field contents, fetched on-demand via getLog
Developer Integration: LogManagerLogger class for StateManager, LogFetcher service for log retrieval
Error Handling: Specific error responses for save failures, fetch failures, and file parsing errors

Service Architecture

LogFetcher Service

classes/LogManager/services/log.fetcher.ts centralizes log retrieval:

getLogFromDatabase(logId): Fetches log from MongoDB
getLargeLogFile(filename): Retrieves large field values from RDK storage
getCompleteLog(logId): Reconstructs log with large fields
getLogs(filter, pagination): Fetches paginated logs with filtering

Used by LogManager methods and entity history endpoints in Company, Member, ProgramManagementUser classes.

Class Relations

The following diagram illustrates how LogManager integrates with other system components:

LogManager Relations

Keyboard shortcuts

Platinum