From 04a991ef7ee289b71009480e135a0f82870b557c Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 26 Feb 2026 09:19:56 -0500 Subject: [PATCH] docs(logging): Update documentation for session-based logging and management --- Readme.md | 9 +++++++ log_pruner.py | 5 ++++ log_registry.py | 67 ++++++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 75 insertions(+), 6 deletions(-) diff --git a/Readme.md b/Readme.md index f894ced..7a950ae 100644 --- a/Readme.md +++ b/Readme.md @@ -21,6 +21,15 @@ Features: * Popup text viewers for large script/output inspection. * Color theming and UI scaling. +## Session-Based Logging and Management + +Manual Slop organizes all communications and tool interactions into session-based directories under `logs/`. This ensures a clean history and easy debugging. + +* **Organized Storage:** Each session is assigned a unique ID and its own sub-directory containing communication logs (`comms.log`) and metadata. +* **Log Management Panel:** The GUI includes a dedicated 'Log Management' panel where you can view session history, inspect metadata (message counts, errors, size), and protect important sessions. +* **Automated Pruning:** To keep the workspace clean, the application automatically prunes insignificant logs. Sessions older than 24 hours that are not "whitelisted" and are smaller than 2KB are automatically deleted. +* **Whitelisting:** Sessions containing errors, high activity, or significant changes are automatically whitelisted. Users can also manually whitelist sessions via the GUI to prevent them from being pruned. + ## Documentation * [docs/Readme.md](docs/Readme.md) for the interface and usage guide diff --git a/log_pruner.py b/log_pruner.py index 003d8b7..def5bc0 100644 --- a/log_pruner.py +++ b/log_pruner.py @@ -4,6 +4,11 @@ from datetime import datetime, timedelta from log_registry import LogRegistry class LogPruner: + """ + Handles the automated deletion of old and insignificant session logs. + Ensures that only whitelisted or significant sessions (based on size/content) + are preserved long-term. + """ def __init__(self, log_registry: LogRegistry, logs_dir: str): """ Initializes the LogPruner. diff --git a/log_registry.py b/log_registry.py index ae78be4..c66a724 100644 --- a/log_registry.py +++ b/log_registry.py @@ -4,13 +4,26 @@ from datetime import datetime import os class LogRegistry: + """ + Manages a persistent registry of session logs using a TOML file. + Tracks session paths, start times, whitelisting status, and metadata. + """ def __init__(self, registry_path): + """ + Initializes the LogRegistry with a path to the registry file. + + Args: + registry_path (str): The file path to the TOML registry. + """ self.registry_path = registry_path self.data = {} self.load_registry() def load_registry(self): - """Loads the registry data from the TOML file.""" + """ + Loads the registry data from the TOML file into memory. + Handles date/time conversions from TOML-native formats to strings for consistency. + """ if os.path.exists(self.registry_path): try: with open(self.registry_path, 'rb') as f: @@ -35,7 +48,10 @@ class LogRegistry: self.data = {} def save_registry(self): - """Saves the current registry data to the TOML file.""" + """ + Serializes and saves the current registry data to the TOML file. + Converts internal datetime objects to ISO format strings for compatibility. + """ try: # Convert datetime objects to ISO format strings for TOML serialization data_to_save = {} @@ -66,7 +82,14 @@ class LogRegistry: print(f"Error saving registry to {self.registry_path}: {e}") def register_session(self, session_id, path, start_time): - """Registers a new session.""" + """ + Registers a new session in the registry. + + Args: + session_id (str): Unique identifier for the session. + path (str): File path to the session's log directory. + start_time (datetime|str): The timestamp when the session started. + """ if session_id in self.data: print(f"Warning: Session ID '{session_id}' already exists. Overwriting.") @@ -85,7 +108,17 @@ class LogRegistry: self.save_registry() def update_session_metadata(self, session_id, message_count, errors, size_kb, whitelisted, reason): - """Updates metadata for an existing session.""" + """ + Updates metadata fields for an existing session. + + Args: + session_id (str): Unique identifier for the session. + message_count (int): Total number of messages in the session. + errors (int): Number of errors identified in logs. + size_kb (int): Total size of the session logs in kilobytes. + whitelisted (bool): Whether the session should be protected from pruning. + reason (str): Explanation for the current whitelisting status. + """ if session_id not in self.data: print(f"Error: Session ID '{session_id}' not found for metadata update.") return @@ -109,7 +142,15 @@ class LogRegistry: self.save_registry() # Save after update def is_session_whitelisted(self, session_id): - """Checks if a session is whitelisted.""" + """ + Checks if a specific session is marked as whitelisted. + + Args: + session_id (str): Unique identifier for the session. + + Returns: + bool: True if whitelisted, False otherwise. + """ session_data = self.data.get(session_id) if session_data is None: return False # Non-existent sessions are not whitelisted @@ -120,6 +161,11 @@ class LogRegistry: def update_auto_whitelist_status(self, session_id: str): """ Analyzes session logs and updates whitelisting status based on heuristics. + Sessions are automatically whitelisted if they contain error keywords, + have a high message count, or exceed a size threshold. + + Args: + session_id (str): Unique identifier for the session to analyze. """ if session_id not in self.data: return @@ -178,7 +224,16 @@ class LogRegistry: ) def get_old_non_whitelisted_sessions(self, cutoff_datetime): - """Gets sessions older than cutoff_datetime and not whitelisted.""" + """ + Retrieves a list of sessions that are older than a specific cutoff time + and are not marked as whitelisted. + + Args: + cutoff_datetime (datetime): The threshold time for identifying old sessions. + + Returns: + list: A list of dictionaries containing session details (id, path, start_time). + """ old_sessions = [] for session_id, session_data in self.data.items(): # Check if session is older than cutoff and not whitelisted