@oxog/hyperlog

@oxog/hyperlog

Ultra-fast, zero-dependency Node.js logger with advanced features for production use.

Features

• Blazing Fast: 1M+ logs/second with minimal overhead
• Zero Dependencies: Everything implemented from scratch
• Multiple Transports: Console, file, HTTP, streams, syslog
• Structured Logging: First-class JSON support
• File Rotation: Size-based and time-based with compression
• Child Loggers: Hierarchical logging with inherited context
• Async-Safe: Non-blocking I/O for all operations
• TypeScript Support: Full type definitions included
• Production Ready: Battle-tested performance optimizations
• Framework Integration: Express & Fastify middleware included
• CLI Tools: Log analysis, conversion, and manipulation utilities
• Syslog Support: RFC3164 and RFC5424 compliant
• Log Sampling: Reduce log volume with configurable sampling
• Rate Limiting: Prevent log flooding with token bucket algorithm
• Metrics & Analytics: Built-in metrics aggregation and reporting
• Adaptive Sampling: Automatically adjust sampling based on throughput

Installation

npm install @oxog/hyperlog

Quick Start

import hyperlog from '@oxog/hyperlog';

const logger = hyperlog.create({
  level: 'info',
  pretty: true
});

logger.info('Hello World');
logger.error({ err: new Error('Oops!') }, 'Something went wrong');

API

Creating a Logger

const logger = hyperlog.create({
  level: 'info',           // minimum log level
  pretty: true,            // pretty print for development
  timestamp: true,         // include timestamps
  hostname: true,          // include hostname
  pid: true,              // include process ID
  transports: [],         // custom transports
  redact: ['password'],   // fields to redact
  filter: (entry) => true // custom filter function
});

Log Levels

• trace
• debug
• info
• warn
• error
• fatal

Basic Logging

// Simple messages
logger.info('User logged in');

// With metadata
logger.info({ userId: 123 }, 'User logged in');

// Error logging
logger.error({ err: error }, 'Failed to process');

Child Loggers

const requestLogger = logger.child({ requestId: 'abc-123' });
requestLogger.info('Processing request');
// Output includes requestId in all logs

Context Management

logger.withContext({ userId: 123 }, () => {
  logger.info('User action');
  // All logs in this scope include userId
});

Performance Timing

const timer = logger.startTimer();
// ... do work ...
timer.done({ operation: 'database-query' }, 'Query completed');
// Logs include duration automatically

Transports

Console Transport

new ConsoleTransport({
  level: 'debug',
  pretty: true,
  colors: true,
  timestamp: 'ISO8601'
})

File Transport

new FileTransport({
  filename: 'app.log',
  maxSize: '100MB',
  maxFiles: 10,
  compress: true,
  datePattern: 'YYYY-MM-DD'
})

HTTP Transport

new HTTPTransport({
  url: 'https://logs.example.com',
  batchSize: 100,
  flushInterval: 5000,
  retry: { attempts: 3, delay: 1000 }
})

Stream Transport

new StreamTransport({
  stream: process.stdout,
  format: 'json'
})

Multiple Transports

const logger = hyperlog.create({
  transports: [
    new ConsoleTransport({ level: 'debug' }),
    new FileTransport({ level: 'info', filename: 'app.log' }),
    new FileTransport({ level: 'error', filename: 'error.log' }),
    new HTTPTransport({ level: 'warn', url: 'https://logs.example.com' })
  ]
});

Syslog Transport

new SyslogTransport({
  host: 'localhost',
  port: 514,
  protocol: 'udp4',
  facility: SYSLOG_FACILITY.LOCAL0,
  tag: 'myapp',
  rfc3164: true
})

Framework Integration

Express Middleware

app.use(hyperlog.expressLogger({
  logger,
  excludePaths: ['/health'],
  includeBody: true,
  includeQuery: true,
  includeHeaders: ['user-agent'],
  customProps: (req, res) => ({
    userId: req.user?.id
  })
}));

Fastify Plugin

fastify.register(hyperlog.fastifyLogger({
  logger,
  excludePaths: ['/metrics'],
  includeBody: true
}));

CLI Tools

# Pretty print logs
hyperlog pretty app.log

# Tail logs with filtering
hyperlog tail -f app.log --level error --grep "database"

# Analyze log patterns
hyperlog analyze app.log

# Convert formats
hyperlog convert app.log --from json --to csv

# Extract time range
hyperlog extract app.log --from "2024-01-01" --to "2024-01-31"

# Performance analysis
hyperlog perf app.log --slow 1000

Advanced Features

Log Sampling

Reduce log volume in high-throughput scenarios:

const logger = hyperlog.create({
  sampling: {
    enabled: true,
    rate: 0.1, // Sample 10% of logs
    adaptive: true // Automatically adjust rate
  }
});

Rate Limiting

Prevent log flooding:

const logger = hyperlog.create({
  rateLimit: {
    enabled: true,
    maxPerSecond: 1000,
    maxBurst: 2000
  }
});

Metrics & Analytics

Built-in metrics collection:

const logger = hyperlog.create({
  metrics: {
    enabled: true,
    interval: 10000 // Report every 10 seconds
  }
});

// Get metrics snapshot
const metrics = logger.getMetrics();
console.log(metrics.counts.total); // Total logs
console.log(metrics.throughput.current); // Current logs/sec
console.log(metrics.topErrors); // Most common errors

Performance

Benchmarks on a typical development machine:

• Simple string logging: 1,000,000+ ops/sec
• Object logging: 700,000+ ops/sec
• Child logger: 750,000+ ops/sec
• Memory usage: < 6MB for 1M logs
• With sampling (10%): 10,000,000+ ops/sec

Production Best Practices

• Use sampling in high-throughput services: Enable adaptive sampling to automatically adjust based on load
• Configure rate limiting: Prevent runaway logging from impacting performance
• Use appropriate transports: Console for development, file/HTTP for production
• Enable metrics: Monitor logging performance and errors
• Set up log rotation: Prevent disk space issues with automatic rotation and compression

License

MIT © Ersin Koç