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

> Discover how Modly's custom logger archives sessions and captures essential information in timestamped folders to effectively debug runtime issues while managing disk space.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Modly uses a custom logger in [`electron/main/logger.ts`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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

```typescript
// 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): ...')

```

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

```

## Key Implementation Files

| File | Role |
|------|------|
| [`electron/main/logger.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/logger.ts) | Core logging, archiving logic, safe console handling |
| [`electron/main/index.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/index.ts) | Global error handlers, imports `archiveCurrentSession` |
| [`electron/main/python-bridge.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/python-bridge.ts) | Forwards Python output to `logger.python` |
| [`electron/main/updater.ts`](https://github.com/lightningpixel/modly/blob/main/electron/main/updater.ts) | Update diagnostics via logger |
| [`electron/main/ipc-handlers.ts`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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`](https://github.com/lightningpixel/modly/blob/main/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.