@bernierllc/logging-utils

Utility functions for log analysis, performance monitoring, and format conversion. This package provides advanced utilities for working with logs beyond basic logging functionality.

Features

- Performance Monitoring: Timer tracking, metrics collection, and memory usage monitoring
- Log Analysis: Error frequency analysis, performance statistics, and user activity tracking
- Log Aggregation: Batching, deduplication, and rate limiting utilities
- Format Conversion: Convert between JSON, text, CSV, syslog, and logfmt formats
- Type Safety: Full TypeScript support with comprehensive type definitions
- Zero Dependencies: Only depends on @bernierllc/logging-core

Installation

``bash
npm install @bernierllc/logging-utils @bernierllc/logging-core
`

Usage

$3

`typescript
import { PerformanceLogger, MemoryTracker } from '@bernierllc/logging-utils';

// Performance tracking
const perfLogger = new PerformanceLogger();

perfLogger.startTimer('database-query');
// ... perform database query
const duration = perfLogger.endTimer('database-query');

// Increment counters
perfLogger.incrementCounter('api-requests');
perfLogger.incrementCounter('errors', 1);

// Get metrics
const metrics = perfLogger.getMetrics('database-query');
console.log(Average duration: ${metrics?.duration}ms);

// Memory tracking
const memoryTracker = new MemoryTracker();
memoryTracker.takeSnapshot('before-operation');
// ... perform operation
memoryTracker.takeSnapshot('after-operation');

const diff = memoryTracker.compareSnapshots('before-operation', 'after-operation');
console.log(Memory increase: ${diff.heapUsedDiff} bytes);
`

$3

`typescript
import { LogAnalyzer, AuditLogAnalyzer } from '@bernierllc/logging-utils';
import { LogEntry, AuditLogEntry } from '@bernierllc/logging-core';

// System log analysis
const analyzer = new LogAnalyzer();

// Add logs
analyzer.addLogs(logEntries);

// Get error analysis
const errorAnalysis = analyzer.getErrorAnalysis();
console.log('Most common errors:', errorAnalysis);

// Get performance stats
const stats = analyzer.getPerformanceStats();
console.log(Total logs: ${stats.totalLogs}, Errors: ${stats.errors});

// Get logs by time range
const recentLogs = analyzer.getLogsByTimeRange(
'2025-01-01T00:00:00Z',
'2025-01-01T23:59:59Z'
);

// Audit log analysis
const auditAnalyzer = new AuditLogAnalyzer();
auditAnalyzer.addAuditLogs(auditLogEntries);

// Get suspicious activity
const suspicious = auditAnalyzer.getSuspiciousActivity(10);
console.log('Suspicious activity:', suspicious);

// Get user activity summary
const userActivity = auditAnalyzer.getUserActivitySummary();
console.log('User activity:', userActivity);
`

$3

`typescript
import { LogAggregator, LogDeduplicator, LogRateLimiter } from '@bernierllc/logging-utils';

// Batch processing
const aggregator = new LogAggregator(100, 5000); // 100 logs, 5 second flush

aggregator.setFlushCallback((logs) => {
// Process batch of logs
console.log(Processing ${logs.length} logs);
});

aggregator.addLog(logEntry);

// Deduplication
const deduplicator = new LogDeduplicator(60000); // 1 minute window

if (!deduplicator.isDuplicate(logEntry)) {
// Process unique log
console.log('Processing unique log');
}

// Rate limiting
const rateLimiter = new LogRateLimiter(1000); // 1000 logs per minute

if (rateLimiter.shouldAllowLog('error')) {
// Log allowed
console.log('Logging error');
} else {
console.log('Rate limit exceeded');
}
`

$3

`typescript
import { LogFormatter, LogParser } from '@bernierllc/logging-utils';
import { LogEntry } from '@bernierllc/logging-core';

// Convert to different formats
const logEntry: LogEntry = {
level: 'info',
message: 'Application started',
timestamp: new Date().toISOString(),
metadata: { userId: 'user123' }
};

// Convert to different formats
const json = LogFormatter.toJSON(logEntry);
const text = LogFormatter.toText(logEntry);
const csv = LogFormatter.toCSV(logEntry);
const syslog = LogFormatter.toSyslog(logEntry);
const logfmt = LogFormatter.toLogfmt(logEntry);

// Parse from different formats
const parsedFromJson = LogParser.fromJSON(json);
const parsedFromText = LogParser.fromText(text);
const parsedFromCsv = LogParser.fromCSV(csv);

// Convert multiple logs
const logs: LogEntry[] = [logEntry1, logEntry2, logEntry3];
const jsonArray = LogFormatter.formatMultiple(logs, 'json');
const csvTable = LogFormatter.formatMultiple(logs, 'csv');
`

API Reference

$3

#### PerformanceLogger
- startTimer(name: string): void
- endTimer(name: string, metadata?: Record): number
- incrementCounter(name: string, value?: number): void
- getMetrics(name: string): PerformanceMetrics | undefined
- getAllMetrics(): Map
- reset(): void

#### MemoryTracker
- takeSnapshot(name: string): NodeJS.MemoryUsage
- getSnapshot(name: string): NodeJS.MemoryUsage | undefined
- compareSnapshots(name1: string, name2: string): Record
- getMemoryUsagePercentage(): number

$3

#### LogAnalyzer
- addLog(log: LogEntry): void
- addLogs(logs: LogEntry[]): void
- getLogsByLevel(level: LogLevel): LogEntry[]
- getLogsByTimeRange(startTime: string, endTime: string): LogEntry[]
- getLogsByText(searchText: string): LogEntry[]
- getErrorAnalysis(): Record
- getPerformanceStats(): PerformanceStats
- getUniqueUsers(): string[]
- getUniqueRequestIds(): string[]

#### AuditLogAnalyzer
- addAuditLog(log: AuditLogEntry): void
- getAuditLogsByActor(actorId: string): AuditLogEntry[]
- getAuditLogsByAction(action: string): AuditLogEntry[]
- getAuditLogsByTarget(target: string): AuditLogEntry[]
- getSuspiciousActivity(threshold?: number): Record
- getUserActivitySummary(): Record

$3

#### LogAggregator
- addLog(log: LogEntry): void
- addLogs(logs: LogEntry[]): void
- flush(): LogEntry[]
- setFlushCallback(callback: (logs: LogEntry[]) => void): void
- stop(): void
- getBatchSize(): number

#### LogDeduplicator
- isDuplicate(log: LogEntry): boolean
- clear(): void

#### LogRateLimiter
- shouldAllowLog(level: LogLevel): boolean
- getLogCounts(): Record

$3

#### LogFormatter
- toJSON(log: LogEntry): string
- toText(log: LogEntry): string
- toCSV(log: LogEntry): string
- toSyslog(log: LogEntry): string
- toLogfmt(log: LogEntry): string
- formatMultiple(logs: LogEntry[], format: Format): string

#### LogParser
- fromJSON(json: string): LogEntry
- fromText(text: string): LogEntry
- fromCSV(csv: string): LogEntry
- parseMultiple(content: string, format: Format): LogEntry[]

Architecture

This package extends the logging ecosystem:

`
@bernierllc/logging-core (core package)
├── Types and interfaces
└── Environment detection

@bernierllc/logging (service package)
├── Winston integration
└── File logging with rotation

@bernierllc/logging-utils (this package)
├── Performance monitoring
├── Log analysis tools
├── Aggregation utilities
└── Format converters
``

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.