@breadstone/ziegel-platform-logging

Enterprise logging and diagnostics infrastructure for the ziegel platform. Provides structured logging, multiple appenders, log levels, correlation tracking, and centralized log management for distributed applications.

Logging: Enterprise-grade logging with structured output, correlation tracking, and centralized management.

🚀 Overview

@breadstone/ziegel-platform-logging provides:

• Structured Logging: JSON-formatted logs with metadata
• Multiple Appenders: Console, file, database, and remote logging
• Log Levels: Configurable logging levels and filtering
• Correlation Tracking: Request correlation and distributed tracing
• Performance Logging: Method execution and performance tracking
• Log Aggregation: Centralized log collection and analysis
• Security Logging: Audit trails and security event logging

📦 Installation

npm install @breadstone/ziegel-platform-logging
# or
yarn add @breadstone/ziegel-platform-logging

🧩 Features & Usage Examples

Basic Logging

import { Logger, LoggerFactory } from '@breadstone/ziegel-platform-logging';

const logger = LoggerFactory.getLogger('MyService');

// Different log levels
logger.debug('Debug information', { userId: '123' });
logger.info('User logged in', { userId: '123', ip: '192.168.1.1' });
logger.warn('Rate limit exceeded', { userId: '123', attempts: 5 });
logger.error('Database connection failed', { error: 'Connection timeout' });

Structured Logging

import { StructuredLogger, LogContext } from '@breadstone/ziegel-platform-logging';

const logger = new StructuredLogger('OrderService');

// Log with structured data
logger.info('Order created', {
  orderId: 'ORD-123',
  customerId: 'CUST-456',
  amount: 99.99,
  items: [
    { sku: 'ITEM-1', quantity: 2 },
    { sku: 'ITEM-2', quantity: 1 }
  ]
});

Log Configuration

import { LoggerConfiguration, ConsoleAppender, FileAppender } from '@breadstone/ziegel-platform-logging';

const config = new LoggerConfiguration()
  .setLevel('info')
  .addAppender(new ConsoleAppender({
    format: 'json',
    colorize: true
  }))
  .addAppender(new FileAppender({
    filename: 'logs/app.log',
    maxSize: '10MB',
    maxFiles: 5,
    compress: true
  }));

LoggerFactory.configure(config);

Correlation Tracking

import { CorrelationContext, CorrelationMiddleware } from '@breadstone/ziegel-platform-logging';

// Express middleware for correlation tracking
app.use(CorrelationMiddleware());

// Use correlation in services
class UserService {
  private logger = LoggerFactory.getLogger('UserService');
  
  async getUser(id: string) {
    const correlationId = CorrelationContext.getId();
    this.logger.info('Fetching user', { 
      userId: id, 
      correlationId 
    });
    
    // All logs in this request will have the same correlationId
    return await this.userRepository.findById(id);
  }
}

Performance Logging

import { PerformanceLogger, LogPerformance } from '@breadstone/ziegel-platform-logging';

class DatabaseService {
  private logger = LoggerFactory.getLogger('DatabaseService');
  
  @LogPerformance()
  async executeQuery(sql: string): Promise<any[]> {
    // Method execution time will be automatically logged
    return await this.database.query(sql);
  }
  
  async manualTiming() {
    const timer = this.logger.startTimer();
    
    // Perform operation
    await this.heavyOperation();
    
    timer.done('Heavy operation completed');
  }
}

Custom Appenders

import { LogAppender, LogEntry } from '@breadstone/ziegel-platform-logging';

class ElasticsearchAppender implements LogAppender {
  constructor(private client: ElasticsearchClient) {}
  
  async write(entry: LogEntry): Promise<void> {
    await this.client.index({
      index: 'application-logs',
      body: {
        timestamp: entry.timestamp,
        level: entry.level,
        message: entry.message,
        data: entry.data,
        source: entry.source
      }
    });
  }
}

// Register custom appender
config.addAppender(new ElasticsearchAppender(esClient));

Security Logging

import { SecurityLogger, AuditLogger } from '@breadstone/ziegel-platform-logging';

const securityLogger = new SecurityLogger();
const auditLogger = new AuditLogger();

// Security events
securityLogger.logLoginAttempt({
  userId: '123',
  success: true,
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0...'
});

securityLogger.logPermissionDenied({
  userId: '123',
  resource: '/admin/users',
  action: 'DELETE'
});

// Audit trail
auditLogger.logDataAccess({
  userId: '123',
  table: 'users',
  action: 'SELECT',
  recordCount: 150
});

Log Filtering and Sampling

import { LogFilter, SamplingFilter, RegexFilter } from '@breadstone/ziegel-platform-logging';

// Sample only 10% of debug logs
const samplingFilter = new SamplingFilter({
  level: 'debug',
  rate: 0.1
});

// Filter out sensitive data
const sensitiveFilter = new RegexFilter({
  pattern: /password|secret|token/i,
  replacement: '[REDACTED]'
});

config.addFilter(samplingFilter);
config.addFilter(sensitiveFilter);

📚 Package import points

import {
    // Core Logging
    Logger,
    LoggerFactory,
    StructuredLogger,
    LogLevel,
    
    // Configuration
    LoggerConfiguration,
    LogEntry,
    
    // Appenders
    ConsoleAppender,
    FileAppender,
    DatabaseAppender,
    RemoteAppender,
    
    // Correlation
    CorrelationContext,
    CorrelationMiddleware,
    
    // Performance
    PerformanceLogger,
    LogPerformance,
    
    // Security
    SecurityLogger,
    AuditLogger,
    
    // Filtering
    LogFilter,
    SamplingFilter,
    RegexFilter
} from '@breadstone/ziegel-platform-logging';

📚 API Documentation

For detailed API documentation, visit: API Docs

Related Packages

• @breadstone/ziegel-platform: Core platform services
• @breadstone/ziegel-platform-configuration: Configuration management
• @breadstone/ziegel-core: Foundation utilities

License

MIT

Issues

Please report bugs and feature requests in the Issue Tracker

Part of the ziegel Enterprise TypeScript Framework