The Logfather

"We tail everything."

A powerful, Node.js Express plugin that provides a sophisticated log viewer interface with search and filtering capabilities. Inspired by tools like Seq, but designed to work with simple file-based logs without external dependencies.

⚠️ SECURITY WARNING: The Logfather provides read-only access to your log files, which may contain sensitive information. ALWAYS protect the routes with authentication in production environments.

Features

🎭 The Family's Capabilities

• Full-text search across all log entries
• Advanced filtering by log level, date range, and source file
• Pagination for handling large log volumes
• In-memory indexing for fast search performance
• Manual refresh to reload logs from files
• Godfather-themed UI that commands respect
• No external dependencies beyond Express
• Modern ES6 modules throughout the codebase
• Native Fetch API - No external HTTP client needed
• Security-focused - Designed for protected environments

📊 Log Format Support

• JSON log entries (primary format)
• Plain text fallback for non-structured logs
• Multiple log levels: debug, info, warning, error
• Timestamp parsing from various formats

🔍 Search & Filter Options

• Text search with highlighting
• Log level filtering
• Date range filtering
• Source file filtering
• Sortable columns
• Real-time result counts

Installation

npm install the-logfather

⚠️ IMPORTANT: Before using The Logfather in production, ensure you have proper authentication middleware in place to protect access to your log files.

Quick Start

import express from 'express';
import logfatherPlugin from 'the-logfather';

const app = express();

// ⚠️ SECURITY: ALWAYS protect The Logfather routes with authentication!
// The Logfather provides read-only access to your log files, which may contain sensitive data.

// Example with basic authentication middleware
app.use('/logs', (req, res, next) => {
    // Add your authentication logic here
    // Example: Check for valid session, API key, or JWT token
    if (!req.headers.authorization) {
        return res.status(401).json({ error: 'Authentication required' });
    }
    next();
}, logfatherPlugin({
    express: express,
    logPaths: ['/path/to/your/logs/']
}));

app.listen(3000, () => {
    console.log('The Logfather is ready: http://localhost:3000/logs');
});

Configuration Options

// 🔒 SECURITY: ALWAYS add authentication middleware before The Logfather
app.use('/logs', authenticateUser, logfatherPlugin({
  express: express,                 // Required: An instance of Express
  logPaths: ['/path/to/logs/'],     // Required: Array of log directory paths
  pageSize: 100,                   // Optional: Results per page (default: 100)
  logger: console                  // Optional: Logger instance (default: console)
}));

Logger Configuration

The Logfather accepts any logger that implements the standard console interface (log, warn, error). You can use:

• Console (default): logger: console
• Winston: logger: winston
• Pino: logger: pino
• Custom logger: Any object with log, warn, error methods

Example with Winston:

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'logfather.log' })
  ]
});

// 🔒 SECURITY: Remember to add authentication!
app.use('/logs', authenticateUser, logfatherPlugin({
  logPaths: ['/path/to/logs/'],
  logger: logger
}));

Log File Structure

The Logfather expects a specific file naming pattern:

• Debug logs: debug.log, debug1.log, debug2.log, etc.
• Error logs: error.log, error1.log, error2.log, etc.

Supported Log Formats

JSON Format (Recommended):

{"level":"info","message":"User logged in","timestamp":"2025-01-20T10:00:00.000Z"}
{"level":"error","message":"Database connection failed","timestamp":"2025-01-20T10:05:00.000Z"}

Plain Text (Fallback):

2025-01-20 10:00:00 INFO User logged in
2025-01-20 10:05:00 ERROR Database connection failed

API Endpoints

Once mounted, The Logfather provides these endpoints:

Web Interface

• GET /logs - Main log viewer interface

Search Query Examples

| Query | Description | |-------|-------------| | error database | Find entries containing "error" and "database" | | user login | Search for user login events | | timeout connection | Find connection timeout issues | | payment failed | Search payment-related failures |

UI Features

🎭 Godfather Theme

• Dark, cinematic interface
• High-contrast design for readability
• Serif fonts for headers, monospace for logs
• Deep red accents throughout
• Always-visible avatar from the family

⌨️ Keyboard Shortcuts

• Ctrl/Cmd + K - Focus search input
• Ctrl/Cmd + R - Refresh logs
• F5 - Refresh logs
• Enter - Execute search

🌐 Modern Web Standards

• Native Fetch API - No external HTTP client dependencies
• URLSearchParams - Modern query parameter handling
• ES6 Modules - Modern JavaScript throughout

📱 Responsive Design

• Mobile-optimized layout
• Collapsible columns on small screens
• Touch-friendly controls

Performance Considerations

• Memory Usage: Logs are indexed in memory for fast searching
• Scan Frequency: Manual refresh only - no automatic file watching
• Concurrent Users: Shared in-memory index supports multiple users

Requirements

• Node.js: 14.0.0 or higher (ES6 module support)
• Express: 4.x or higher
• ES6 Environment: Requires "type": "module" in package.json

License

MIT License