@frequencyads/frequency-logger

Professional logging library for FrequencyAds applications with Winston integration, performance tracking, CLI-friendly formatting, and configurable output options.

🚀 Features

• Professional Winston Integration - Built on the industry-standard Winston logging library
• CLI-Friendly Formatting - User-friendly console output with icons and colors
• Performance Tracking - Built-in timing utilities for operation benchmarking
• Flexible Configuration - Configurable log levels, outputs, and formatting
• TypeScript Support - Full type definitions and IntelliSense support
• Child Loggers - Context-aware logging with automatic metadata injection

📦 Installation

npm install @frequencyads/frequency-logger

🔧 Quick Start

import { log, initializeLogger } from '@frequencyads/frequency-logger';

// Initialize logger (optional - uses defaults if not called)
initializeLogger({
  level: 'debug',
  verbose: true,
  enableConsole: true,
  enableFile: true
});

// Basic logging
log.info('Application started');
log.warn('This is a warning');
log.error('Something went wrong', new Error('Database connection failed'));

// CLI-friendly logging
log.cli.success('File processed successfully');
log.cli.error('Failed to upload file', error);
log.cli.info('Processing 15 files...');

// Performance tracking
const timer = log.perf.start('database-query');
// ... perform operation
timer.end(); // Logs: "database-query completed in 245ms"

📚 API Reference

Basic Logging

log.debug(message: string, meta?: object)
log.info(message: string, meta?: object)  
log.warn(message: string, meta?: object)
log.error(message: string, error?: Error | object)

CLI Logging

log.cli.success(message: string, meta?: object)  // ✅ Green checkmark
log.cli.warning(message: string, meta?: object)  // ⚠️ Yellow warning
log.cli.error(message: string, error?: Error)    // ❌ Red X
log.cli.info(message: string, meta?: object)     // ℹ️ Blue info
log.cli.verbose(message: string, meta?: object)  // Debug level

Performance Tracking

const timer = log.perf.start('operation-name');
// ... perform operation
timer.end(); // Automatically logs duration

Configuration

import { initializeLogger, LoggerConfig } from '@frequencyads/frequency-logger';

const config: LoggerConfig = {
  level: 'info',              // 'error' | 'warn' | 'info' | 'debug'
  verbose: false,             // Include metadata in console output
  enableConsole: true,        // Enable console output
  enableFile: true,           // Enable file logging
  errorFilename: 'errors.log', // Custom error log filename
  exceptionFilename: 'exceptions.log', // Custom exception log filename
  colorize: true              // Enable colored console output
};

const logger = initializeLogger(config);

Child Loggers

Create child loggers with automatic context metadata:

import { createChildLogger } from '@frequencyads/frequency-logger';

const requestLogger = createChildLogger({
  requestId: 'req-123',
  userId: 'user-456'
});

requestLogger.info('Processing started'); 
// Automatically includes requestId and userId in all log entries

🎯 Use Cases

CLI Applications

import { log } from '@frequencyads/frequency-logger';

// User-friendly CLI feedback
log.cli.info('Starting file processing...');
log.cli.success('3 files processed successfully');
log.cli.warning('Skipped 1 corrupted file');
log.cli.error('Failed to process file.pdf', error);

Performance Monitoring

// Time any operation
const dbTimer = log.perf.start('database-connection');
await connectToDatabase();
dbTimer.end(); // Logs: "⏱️ database-connection completed in 1.2s"

const apiTimer = log.perf.start('api-request');
const response = await fetch('/api/data');
apiTimer.end(); // Logs: "⏱️ api-request completed in 245ms"

Structured Logging

// Rich metadata logging
log.info('User login attempt', {
  userId: '12345',
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0...',
  timestamp: Date.now()
});

// Error logging with context
log.error('Payment processing failed', {
  orderId: 'order-789',
  amount: 99.99,
  paymentMethod: 'credit-card',
  error: error.message
});

🏗️ Architecture

The library is organized into focused modules:

• logger-manager - Singleton instance management
• logger-factory - Winston logger creation and configuration
• cli-logger - CLI-specific formatting and icons
• performance-logger - Timing and benchmarking utilities
• types - TypeScript definitions and interfaces

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

This is a private FrequencyAds library. For issues or feature requests, please contact the FrequencyAds Development Team.