Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

snaplogx

NirbhayMeghpara5MIT1.0.1

A high-performance logging library with advanced filtering algorithms

logging, performance, kmp, aho-corasick, nodejs

readme

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.