SnapLog

A high-performance logging library for Node.js with advanced pattern-matching filters.

Motivation

SnapLog is built for speed and precision in logging, targeting applications that demand real-time, high-volume log processing. It uses optimized Knuth-Morris-Pratt (KMP) for single-pattern filtering and Aho-Corasick for multi-pattern filtering, offering a lightweight alternative to traditional loggers like Winston. With a focus on performance and flexibility, SnapLog supports file-based logging with customizable filters and processors, making it extensible for diverse use cases.

Quick Start

Install SnapLog and start logging with a simple setup:

npm install snaplogx

import { createLogger } from 'snaplogx';

const logger = createLogger({
  fileOptions: {
    filename: 'app.log',
    format: 'json',
    logDir: './logs'
  }
});

logger.info('App started');

See more examples in ./perf/ for performance demos or contribute your own!

Usage

Create a logger instance with createLogger to leverage SnapLog’s features:

import { createLogger } from 'snaplogx';

const logger = createLogger({
  fileOptions: {
    filename: 'app.log',
    format: 'text',
    logDir: './logs'
  }
});

// Basic logging
logger.info('Server running');
logger.error('Connection issue');

// Single-pattern filter with KMP
logger.addPatternFilter('no-errors', 'error', false);
logger.info('Database online');     // Logged
logger.error('Query error');        // Filtered

// Multi-pattern filter with Aho-Corasick
logger.addMultiPatternFilter('errors-only', ['timeout', 'failed'], true);
logger.info('Task completed');      // Filtered
logger.error('Request timeout');    // Logged

// Add a processor
logger.addProcessor('timestamp', (info) => {
  info.timestamp = new Date().toISOString();
});

// Switch file
logger.setFile({ filename: 'errors.log' });
logger.error('Task failed');        // Logged to errors.log

Features

• High Performance: Buffered file output for minimal overhead.
• KMP Filtering: Fast single-pattern matching with cached LPS arrays.
• Aho-Corasick Filtering: Efficient multi-pattern matching in one pass.
• Customizable Output: JSON or text format, configurable file locations.
• Processors: Transform logs before writing with custom functions.
• Chainable API: Fluent method calls for easy setup.

API

Create a logger with createLogger:

const logger = createLogger({
  fileOptions: { filename: 'logs.log', format: 'json', logDir: './logs' }
});

| Method | Description | Parameters | |-------------------------------------|--------------------------------------------|------------| | logger.log(level, message, [meta]) | Logs a message with optional metadata. | level: string, message: string, meta: object (optional) | | logger.<level>(message, [meta]) | Shorthand for levels (e.g., info, error). | message: string, meta: object (optional) | | logger.addPatternFilter(name, pattern, allow) | Adds a KMP filter. | name: string, pattern: string, allow: boolean (default: true) | | logger.addMultiPatternFilter(name, patterns, allow) | Adds an Aho-Corasick filter. | name: string, patterns: string[], allow: boolean (default: true) | | logger.removeFilter(name) | Removes a filter by name. | name: string | | logger.setFile(options) | Updates the output file configuration. | options: { filename?, format?, logDir? } | | logger.addProcessor(name, fn) | Adds a processor to transform logs. | name: string, fn: (info) => void | | logger.removeProcessor(name) | Removes a processor by name. | name: string |

Configuration Options for createLogger:

| Option | Default | Description | |----------------------|-------------|--------------------------------------------| | fileOptions.filename | 'app.log' | Name of the output log file. | | fileOptions.format | 'json' | Log format ('json' or 'text'). | | fileOptions.logDir | './logs' | Directory for log files (created if missing). |

Logging Levels

SnapLog uses a simple level system (customizable via constants.js):

const levels = {
  error: 0,
  warn: 1,
  info: 2,
  debug: 3
};

Level-specific methods (e.g., logger.info, logger.error) are auto-generated.

Prerequisites

• Node.js: v16+ (v18+ recommended)
• npm: For installation

Development Setup

Clone the repo:

git clone https://github.com/NirbhayMeghpara/SnapLog.git
cd snaplog

Install dependencies:

npm install

Run tests:

npm run test

Explore performance demos:

npm run perf:generate  # Generate test logs
npm run perf:benchmark # Run benchmarks

Contributing

SnapLog is open-source and welcomes contributions! Whether you’ve spotted a bug, have a feature idea, or want to make improvements, we’d love to hear from you.

Here’s how you can contribute:

1. Report an Issue
   Found a bug or have a feature suggestion? Create a new issue with a clear description. Feel free to label it appropriately (bug, enhancement, etc.).

2. Discuss a Feature
   If you have an idea and would like to collaborate or need clarification, don’t hesitate to connect with me directly or open a discussion/issue. I’m happy to brainstorm and build great features together.

3. Contribute Code

   • Fork the repository
   • Create your feature branch:

     git checkout -b feature/your-feature-name

   • Commit your changes:

     git commit -m "Add: your message"

   • Push to the branch:

     git push origin feature/your-feature-name

   • Submit a pull request on GitHub

4. Guidelines

   • Include relevant unit tests for any new features or fixes.
   • Follow the existing coding style and structure.
   • Keep pull requests focused and well-documented.
   • Update documentation if your changes affect usage or behavior.

Looking forward to your contributions! 🚀

Why SnapLog?

SnapLog prioritizes performance with optimized algorithms, offering faster filtering and logging than traditional tools, perfect for real-time, high-throughput applications.

License

This project is licensed under the MIT License - see the LICENSE file for details.