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

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