How Modly's Logger Archives Sessions and Captures Information for Debugging Runtime Issues

Modly uses a custom logger in electron/main/logger.ts that writes three separate log files and automatically archives past sessions into timestamped folders while pruning older archives to limit disk usage.

The Modly application handles logging through a purpose-built system designed for Electron environments where both main process activity and Python bridge output need reliable capture. This article examines how the modly repository implements session archiving and runtime debugging based on the source code in lightningpixel/modly.

Three Specialized Log Files

Modly's logger maintains distinct files for different information types, all written via appendFileSync to prevent UI blocking.

File	Purpose
modly.log	General informational, warning, and error messages from logger.info, logger.warn, and logger.error
errors.log	Consolidated error output from the main process and flagged Python runtime messages
runtime.log	Raw, unfiltered output from the Python bridge

The writeTo helper at lines 15-17 of electron/main/logger.ts handles all file appends synchronously.

Session Archiving Mechanism

When Modly shuts down—or when explicitly triggered—the archiveCurrentSession() function preserves the current session's logs. This function is imported in electron/main/index.ts at line 6.

Detection and Early Exit

The archiver first checks if any log files exist using LOG_FILES.some (lines 26-27). If the logs directory is empty, the function returns immediately without creating unnecessary directories.

Timestamped Directory Creation

A session folder is generated using ISO-8601 formatting with colons replaced by hyphens (lines 29-33):

logs/sessions/2024-01-15T09-30-00-000Z/

File Movement and Cleanup

Each existing log file is renamed into the new session folder via renameSync (lines 34-38). This leaves the main logs directory empty for the next run.

Pruning Old Sessions

The function reads the sessions directory, sorts folder names chronologically, and removes any sessions exceeding MAX_SESSIONS (default: 10) as shown at lines 41-49. This bounds disk usage automatically.

All filesystem operations use try…catch blocks to prevent application crashes from I/O errors.

Capturing Runtime Issues from Python

The Python bridge in electron/main/python-bridge.ts forwards every line of Python process output to logger.python(msg) at line 74. This method implements a dual-write strategy:

• Raw output → written to runtime.log (lines 64-65)
• Error-flagged output → also written to errors.log when matching /error|exception|traceback|critical/i (lines 66-67)

This gives developers both complete logs and a filtered error view without manual searching.

Safe Console Handling

Console output in Modly uses a safeConsole wrapper (lines 55-57) that silently handles EPIPE errors. This prevents crashes when the parent process's stdout/stderr pipe disappears—common in packaged Electron applications.

Usage Examples

// Standard logging methods
logger.info('Extension loaded successfully')
logger.warn('Deprecated API detected')
logger.error('Failed to download update')

// Python bridge integration
logger.python('[stderr] Traceback (most recent call last): ...')

// Manual session archival, typically called on app quit
import { archiveCurrentSession } from './logger'
archiveCurrentSession()

Key Implementation Files

File	Role
electron/main/logger.ts	Core logging, archiving logic, safe console handling
electron/main/index.ts	Global error handlers, imports archiveCurrentSession
electron/main/python-bridge.ts	Forwards Python output to logger.python
electron/main/updater.ts	Update diagnostics via logger
electron/main/ipc-handlers.ts	Propagates renderer errors through logger

Summary

• Three log files separate general messages, errors, and raw Python output for organized debugging
• Synchronous file appends via appendFileSync keep logging non-blocking for the UI
• Timestamped session folders preserve historical context with ISO-8601 naming
• Automatic pruning maintains only the 10 most recent sessions to control disk usage
• Pattern-matching integration flags Python errors without losing complete runtime context
• Defensive error handling throughout prevents logging failures from destabilizing the application

Frequently Asked Questions

How does Modly prevent log files from growing indefinitely?

The archiveCurrentSession() function enforces a MAX_SESSIONS limit (default 10). After moving current logs to a new timestamped folder, it sorts all session directories chronologically and deletes the oldest entries. This is implemented in electron/main/logger.ts at lines 41-49.

What happens to Python error messages in Modly's logging system?

The logger.python() method inspects each line against a case-insensitive regex pattern matching "error", "exception", "traceback", or "critical". Matching lines are written to both runtime.log (full output) and errors.log (filtered view) as defined at lines 64-67 of the logger implementation.

Why does Modly use synchronous file operations for logging?

Synchronous writes via appendFileSync (see the writeTo helper at lines 15-17) ensure log entries are committed immediately without callback complexity. Because these writes are small and local, they complete quickly enough that UI blocking is negligible while guaranteeing durability.

Can the session archive be triggered outside of application shutdown?

Yes. While electron/main/index.ts imports archiveCurrentSession for quit-time archiving, any module can import and call the function directly. The implementation safely handles cases where no log files exist by returning early at lines 26-27.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}