@push.rocks/smartlog 3.1.8 → 3.1.9

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartlog',
-    version: '3.1.8',
+    version: '3.1.9',
     description: 'A minimalistic, distributed, and extensible logging tool supporting centralized log management.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxzQkFBc0I7SUFDNUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLGlHQUFpRztDQUMvRyxDQUFBIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartlog",
-  "version": "3.1.8",
+  "version": "3.1.9",
   "private": false,
   "description": "A minimalistic, distributed, and extensible logging tool supporting centralized log management.",
   "keywords": [

package/readme.md

@@ -1,288 +1,736 @@
-# @push.rocks/smartlog
+# @push.rocks/smartlog 🚀
+*The ultimate TypeScript logging solution for modern applications*
 
-Minimalistic distributed and extensible logging tool for TypeScript and JavaScript applications.
+[![npm version](https://img.shields.io/npm/v/@push.rocks/smartlog.svg)](https://www.npmjs.com/package/@push.rocks/smartlog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+> **smartlog** is a powerful, distributed, and extensible logging system designed for the cloud-native era. Whether you're debugging locally, monitoring production systems, or building complex microservices, smartlog adapts to your needs with style. 🎯
 
-Install `@push.rocks/smartlog` using pnpm (recommended), npm, or yarn:
+## 🌟 Why smartlog?
 
-```sh
+- **🎨 Beautiful Console Output**: Color-coded, formatted logs that are actually readable
+- **🔌 Extensible Architecture**: Plug in any destination - databases, files, remote servers
+- **🌍 Distributed by Design**: Built for microservices with correlation and context tracking
+- **⚡ Zero-Config Start**: Works out of the box, scales when you need it
+- **🎭 Interactive CLI Tools**: Spinners and progress bars that handle non-TTY environments gracefully
+- **📊 Structured Logging**: JSON-based for easy parsing and analysis
+- **🔍 Smart Filtering**: Log levels and context-based filtering
+
+## 📦 Installation
+
+```bash
 # Using pnpm (recommended)
 pnpm add @push.rocks/smartlog
 
 # Using npm
-npm install @push.rocks/smartlog --save
+npm install @push.rocks/smartlog
 
 # Using yarn
 yarn add @push.rocks/smartlog
 ```
 
-Ensure you have TypeScript and Node.js installed for TypeScript projects.
+## 🚀 Quick Start
 
-## Package Exports
+### Your First Logger
 
-The package provides the following exports:
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
 
-```javascript
-// Main module
-import { Smartlog, LogGroup, ConsoleLog } from '@push.rocks/smartlog';
+// Create a logger with context
+const logger = new Smartlog({
+  logContext: {
+    company: 'MyStartup',
+    companyunit: 'Backend Team',
+    containerName: 'api-gateway',
+    environment: 'production',
+    runtime: 'node',
+    zone: 'eu-central'
+  }
+});
 
-// Type definitions and interfaces
-import { ILogPackage, ILogDestination, TLogLevel } from '@push.rocks/smartlog/interfaces';
+// Enable beautiful console output
+logger.enableConsole();
 
-// Interactive console features (spinners, progress bars)
-import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
+// Start logging!
+logger.log('info', '🎉 Application started successfully');
+logger.log('error', '💥 Database connection failed', { 
+  errorCode: 'DB_TIMEOUT',
+  attemptCount: 3 
+});
+```
 
-// Context management
-import { ... } from '@push.rocks/smartlog/context';
+### Using the Default Logger
 
-// Log destinations
-import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
-import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
-import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
-import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
-import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
+For quick prototyping and simple applications:
+
+```typescript
+import { defaultLogger } from '@push.rocks/smartlog';
+
+defaultLogger.log('info', 'This is so easy!');
+```
+
+## 📚 Core Concepts
+
+### Log Levels
+
+smartlog supports semantic log levels for different scenarios:
+
+```typescript
+// Lifecycle events
+logger.log('lifecycle', '🔄 Container starting up...');
 
-// Receiver functionality
-import { SmartlogReceiver } from '@push.rocks/smartlog/receiver';
+// Success states
+logger.log('success', '✅ Payment processed');
+logger.log('ok', '👍 Health check passed');
+
+// Information and debugging
+logger.log('info', '📋 User profile updated');
+logger.log('note', '📌 Cache invalidated');
+logger.log('debug', '🔍 Query execution plan', { sql: 'SELECT * FROM users' });
+
+// Warnings and errors
+logger.log('warn', '⚠️  Memory usage above 80%');
+logger.log('error', '❌ Failed to send email');
+
+// Verbose output
+logger.log('silly', '🔬 Entering function processPayment()');
+```
+
+### Log Groups for Correlation
+
+Perfect for tracking request flows through your system:
+
+```typescript
+// Track a user request through multiple operations
+const requestGroup = logger.createLogGroup('req-7f3a2b');
+
+requestGroup.log('info', 'Received POST /api/users');
+requestGroup.log('debug', 'Validating request body');
+requestGroup.log('info', 'Creating user in database');
+requestGroup.log('success', 'User created successfully', { userId: 'usr_123' });
+
+// All logs in the group share the same correlation ID
 ```
 
-## Usage
+## 🎯 Log Destinations
 
-`@push.rocks/smartlog` is a flexible, extensible logging tool designed for distributed systems. It provides a consistent logging interface across different environments while being lightweight and customizable.
+### Built-in Destinations
 
-### Creating a Logger Instance
+#### 🖥️ Local Console (Enhanced)
 
-Start by importing `Smartlog` and create a logger instance:
+Beautiful, colored output for local development:
 
 ```typescript
-import { Smartlog } from '@push.rocks/smartlog';
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
 
-const logger = new Smartlog({
-  logContext: {
-    company: 'My Company',
-    companyunit: 'Cloud Team',
-    containerName: 'api-service',
-    environment: 'production', // 'local', 'test', 'staging', 'production'
-    runtime: 'node',           // 'node', 'chrome', 'rust', 'deno', 'cloudflare_workers'
-    zone: 'us-west',
-  },
-  minimumLogLevel: 'info',     // Optional, defaults to 'silly'
+const localDestination = new DestinationLocal({
+  logLevel: 'debug'  // Optional: filter by minimum log level
 });
 
-// Enable console output
-logger.enableConsole();
+logger.addLogDestination(localDestination);
 ```
 
-The context enriches logs with valuable information for filtering and analysis across distributed systems.
+#### 📁 File Logging
 
-### Logging Messages
+Persist logs to files with automatic rotation support:
 
 ```typescript
-// Basic logging
-logger.log('info', 'User authenticated successfully');
-logger.log('error', 'Database connection failed', { errorCode: 'DB_CONN_ERR', retryCount: 3 });
-logger.log('warn', 'Rate limit approaching', { currentRate: 95, limit: 100 });
+import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
 
-// Log levels: 'silly', 'info', 'debug', 'note', 'ok', 'success', 'warn', 'error', 'lifecycle'
+const fileDestination = new SmartlogDestinationFile('./logs/app.log');
+logger.addLogDestination(fileDestination);
 ```
 
-The third parameter accepts any additional data to attach to the log entry.
+#### 🌐 Browser DevTools
 
-### Default Logger
+Optimized for browser environments with styled console output:
 
-For simple cases, use the built-in default logger:
+```typescript
+import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
+
+const devtools = new SmartlogDestinationDevtools();
+logger.addLogDestination(devtools);
+```
+
+#### 📊 ClickHouse Analytics
+
+Store logs in ClickHouse for powerful analytics:
 
 ```typescript
-import { defaultLogger } from '@push.rocks/smartlog';
+import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
+
+const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
+  host: 'analytics.example.com',
+  port: 8123,
+  database: 'logs',
+  user: 'logger',
+  password: process.env.CLICKHOUSE_PASSWORD
+});
 
-defaultLogger.log('info', 'Application started');
+logger.addLogDestination(clickhouse);
+
+// Query your logs with SQL!
+// SELECT * FROM logs WHERE level = 'error' AND timestamp > now() - INTERVAL 1 HOUR
 ```
 
-### Log Groups
+#### 🔗 Remote Receiver
 
-Group related logs for better traceability:
+Send logs to a centralized logging service:
 
 ```typescript
-// Create a log group with optional transaction ID
-const requestGroup = logger.createLogGroup('tx-123456');
+import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
+
+const receiver = new SmartlogDestinationReceiver({
+  endpoint: 'https://logs.mycompany.com/ingest',
+  apiKey: process.env.LOG_API_KEY,
+  batchSize: 100,  // Send logs in batches
+  flushInterval: 5000  // Flush every 5 seconds
+});
 
-// Logs within this group will be correlated
-requestGroup.log('info', 'Processing payment request');
-requestGroup.log('debug', 'Validating payment details');
-requestGroup.log('success', 'Payment processed successfully');
+logger.addLogDestination(receiver);
 ```
 
-### Custom Log Destinations
+### 🛠️ Custom Destinations
 
-Extend logging capabilities by adding custom destinations:
+Build your own destination for any logging backend:
 
 ```typescript
-import { Smartlog, ILogDestination } from '@push.rocks/smartlog';
+import { ILogDestination, ILogPackage } from '@push.rocks/smartlog/interfaces';
 
-class DatabaseLogDestination implements ILogDestination {
-  async handleLog(logPackage) {
-    // Store log in database
-    await db.logs.insert({
-      timestamp: new Date(logPackage.timestamp),
-      level: logPackage.level,
-      message: logPackage.message,
-      data: logPackage.data,
-      context: logPackage.context
+class ElasticsearchDestination implements ILogDestination {
+  private client: ElasticsearchClient;
+
+  constructor(config: ElasticsearchConfig) {
+    this.client = new ElasticsearchClient(config);
+  }
+
+  async handleLog(logPackage: ILogPackage): Promise<void> {
+    await this.client.index({
+      index: `logs-${new Date().toISOString().split('T')[0]}`,
+      body: {
+        '@timestamp': logPackage.timestamp,
+        level: logPackage.level,
+        message: logPackage.message,
+        context: logPackage.context,
+        data: logPackage.data,
+        correlation: logPackage.correlation
+      }
     });
   }
 }
 
-// Add the custom destination to your logger
-logger.addLogDestination(new DatabaseLogDestination());
+// Use your custom destination
+logger.addLogDestination(new ElasticsearchDestination({
+  node: 'https://elasticsearch.example.com'
+}));
 ```
 
-### Built-in Destinations
+## 🎨 Interactive Console Features
 
-SmartLog comes with several built-in destinations for various logging needs:
+### Spinners
+
+Create beautiful loading animations that degrade gracefully in CI/CD:
 
 ```typescript
-// Log to a file
-import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
-logger.addLogDestination(new SmartlogDestinationFile('/path/to/logfile.log'));
+import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';
 
-// Colorful local console logging
-import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
-logger.addLogDestination(new DestinationLocal());
+const spinner = new SmartlogSourceInteractive();
 
-// Browser DevTools with colored formatting
-import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
-logger.addLogDestination(new SmartlogDestinationDevtools());
+// Basic usage
+spinner.text('🔄 Fetching data from API...');
+// ... perform async operation
+spinner.finishSuccess('✅ Data fetched successfully!');
+
+// Chained operations
+spinner
+  .text('📡 Connecting to database')
+  .successAndNext('🔍 Running migrations')
+  .successAndNext('🌱 Seeding data')
+  .finishSuccess('🎉 Database ready!');
+
+// Customize appearance
+spinner
+  .setSpinnerStyle('dots')  // dots, line, star, simple
+  .setColor('cyan')         // any terminal color
+  .setSpeed(80)            // animation speed in ms
+  .text('🚀 Deploying application...');
+
+// Handle failures
+try {
+  await deployApp();
+  spinner.finishSuccess('✅ Deployed!');
+} catch (error) {
+  spinner.finishFail('❌ Deployment failed');
+}
+```
+
+### Progress Bars
+
+Track long-running operations with style:
+
+```typescript
+import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
+
+// Create a progress bar
+const progress = new SmartlogProgressBar({
+  total: 100,
+  width: 40,
+  complete: '█',
+  incomplete: '░',
+  showEta: true,
+  showPercent: true,
+  showCount: true
+});
+
+// Update progress
+for (let i = 0; i <= 100; i++) {
+  progress.update(i);
+  await someAsyncWork();
+}
+
+progress.complete();
+
+// Real-world example: Processing files
+const files = await getFiles();
+const progress = new SmartlogProgressBar({
+  total: files.length,
+  width: 50
+});
+
+for (const [index, file] of files.entries()) {
+  await processFile(file);
+  progress.increment();  // or progress.update(index + 1)
+}
+```
+
+### Non-Interactive Fallback
+
+Both spinners and progress bars automatically detect non-interactive environments (CI/CD, Docker logs, piped output) and fallback to simple text output:
+
+```
+[Loading] Connecting to database
+[Success] Connected to database
+[Loading] Running migrations
+Progress: 25% (25/100)
+Progress: 50% (50/100)
+Progress: 100% (100/100)
+[Success] Migrations complete
+```
+
+## 🔧 Advanced Features
+
+### Context Management
+
+Add context that flows through your entire application:
+
+```typescript
+// Set global context
+logger.addLogContext({
+  requestId: 'req-123',
+  userId: 'user-456',
+  feature: 'payment-processing'
+});
+
+// All subsequent logs include this context
+logger.log('info', 'Processing payment');
+// Output includes: { ...context, message: 'Processing payment' }
+```
 
-// ClickHouse database logging
+### Scoped Logging
+
+Create scoped loggers for different components:
+
+```typescript
+const dbLogger = logger.createScope('database');
+const apiLogger = logger.createScope('api');
+
+dbLogger.log('info', 'Executing query');
+apiLogger.log('info', 'Handling request');
+// Logs include scope information for filtering
+```
+
+### Minimum Log Levels
+
+Control log verbosity per environment:
+
+```typescript
+const logger = new Smartlog({
+  logContext: { environment: 'production' },
+  minimumLogLevel: 'warn'  // Only warn and above in production
+});
+
+// These won't be logged in production
+logger.log('debug', 'Detailed debug info');
+logger.log('info', 'Regular info');
+
+// These will be logged
+logger.log('warn', 'Warning message');
+logger.log('error', 'Error message');
+```
+
+### Increment Logging
+
+Perfect for metrics and counters:
+
+```typescript
+// Track API calls
+logger.increment('info', 'api.requests', { endpoint: '/users', method: 'GET' });
+logger.increment('info', 'api.requests', { endpoint: '/users', method: 'POST' });
+
+// Track errors by type
+logger.increment('error', 'payment.failed', { reason: 'insufficient_funds' });
+logger.increment('error', 'payment.failed', { reason: 'card_declined' });
+```
+
+### Capture All Console Output
+
+Redirect all console.log and console.error through smartlog:
+
+```typescript
+logger.enableConsole({ 
+  captureAll: true  // Capture all console.* methods
+});
+
+console.log('This goes through smartlog!');
+console.error('This too!');
+// All console output is now structured and routed through your destinations
+```
+
+## 🏗️ Real-World Examples
+
+### Microservice with Distributed Tracing
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
 import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
+
+// Initialize logger with service context
+const logger = new Smartlog({
+  logContext: {
+    company: 'TechCorp',
+    companyunit: 'Platform',
+    containerName: 'user-service',
+    environment: process.env.NODE_ENV,
+    runtime: 'node',
+    zone: process.env.CLOUD_ZONE
+  }
+});
+
+// Add ClickHouse for analytics
 const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
-  host: 'clickhouse.example.com',
-  port: 8123,
-  user: 'username',
-  password: 'password',
-  database: 'logs_db'
+  host: process.env.CLICKHOUSE_HOST,
+  database: 'microservices_logs'
 });
 logger.addLogDestination(clickhouse);
 
-// Remote receiver logging
-import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
-logger.addLogDestination(new SmartlogDestinationReceiver({
-  endpoint: 'https://logs.example.com/api/logs'
-}));
-```
+// Enable local console for development
+if (process.env.NODE_ENV === 'development') {
+  logger.enableConsole();
+}
 
-### Interactive Console Features
+// Express middleware for request tracking
+app.use((req, res, next) => {
+  const requestId = generateRequestId();
+  const logGroup = logger.createLogGroup(requestId);
+  
+  // Attach logger to request
+  req.logger = logGroup;
+  
+  // Log request
+  logGroup.log('info', 'Incoming request', {
+    method: req.method,
+    path: req.path,
+    ip: req.ip
+  });
+  
+  // Track response
+  res.on('finish', () => {
+    logGroup.log('info', 'Request completed', {
+      statusCode: res.statusCode,
+      duration: Date.now() - req.startTime
+    });
+  });
+  
+  next();
+});
+```
 
-For CLI applications, use the interactive console features:
+### CLI Tool with Progress Tracking
 
 ```typescript
+import { Smartlog } from '@push.rocks/smartlog';
 import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
+
+const logger = new Smartlog({
+  logContext: {
+    containerName: 'migration-tool',
+    environment: 'cli'
+  }
+});
+
+logger.enableConsole();
+
+async function migrateDatabase() {
+  const spinner = new SmartlogSourceInteractive();
+  
+  // Connect to database
+  spinner.text('🔌 Connecting to database...');
+  await connectDB();
+  spinner.finishSuccess('✅ Connected to database');
+  
+  // Get migrations
+  spinner.text('📋 Loading migrations...');
+  const migrations = await getMigrations();
+  spinner.finishSuccess(`✅ Found ${migrations.length} migrations`);
+  
+  // Run migrations with progress bar
+  const progress = new SmartlogProgressBar({
+    total: migrations.length,
+    width: 40,
+    showEta: true
+  });
+  
+  for (const [index, migration] of migrations.entries()) {
+    logger.log('info', `Running migration: ${migration.name}`);
+    await runMigration(migration);
+    progress.update(index + 1);
+  }
+  
+  progress.complete();
+  logger.log('success', '🎉 All migrations completed successfully!');
+}
 ```
 
-#### Spinners
+### Production Logging with Multiple Destinations
 
 ```typescript
-const spinner = new SmartlogSourceInteractive();
+import { Smartlog } from '@push.rocks/smartlog';
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
+import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
+import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
 
-// Start a spinner with text
-spinner.text('Loading data...');
+const logger = new Smartlog({
+  logContext: {
+    company: 'Enterprise Corp',
+    containerName: 'payment-processor',
+    environment: 'production',
+    runtime: 'node',
+    zone: 'us-east-1'
+  },
+  minimumLogLevel: 'info'  // No debug logs in production
+});
 
-// Customize appearance
-spinner.setSpinnerStyle('dots');  // 'dots', 'line', 'star', 'simple'
-spinner.setColor('blue');         // 'red', 'green', 'yellow', 'blue', etc.
-spinner.setSpeed(80);             // Animation speed in milliseconds
+// Console for container logs (structured for log aggregators)
+logger.addLogDestination(new DestinationLocal());
 
-// Update spinner status
-spinner.text('Processing records...');
+// File for audit trail
+logger.addLogDestination(new SmartlogDestinationFile('/var/log/app/audit.log'));
 
-// Complete with success or failure
-spinner.finishSuccess('Data loaded successfully!');
-spinner.finishFail('Failed to load data!');
+// Central logging service
+logger.addLogDestination(new SmartlogDestinationReceiver({
+  endpoint: 'https://logs.enterprise.com/ingest',
+  apiKey: process.env.LOG_API_KEY,
+  batchSize: 100,
+  flushInterval: 5000
+}));
 
-// Chain operations
-spinner.text('Connecting to server')
-  .successAndNext('Fetching records')
-  .successAndNext('Processing data')
-  .finishSuccess('All done!');
+// Critical error alerts
+logger.addLogDestination({
+  async handleLog(logPackage) {
+    if (logPackage.level === 'error' && logPackage.data?.critical) {
+      await sendAlert({
+        channel: 'ops-team',
+        message: `🚨 Critical error: ${logPackage.message}`,
+        data: logPackage
+      });
+    }
+  }
+});
 ```
 
-#### Progress Bars
+## 🔌 Integration with Other Tools
+
+### PM2 Integration
 
 ```typescript
-const progressBar = new SmartlogProgressBar({
-  total: 100,                // Total number of items
-  width: 40,                 // Width of the progress bar
-  complete: '█',             // Character for completed section
-  incomplete: '░',           // Character for incomplete section
-  showEta: true,             // Show estimated time remaining
-  showPercent: true,         // Show percentage
-  showCount: true            // Show count (e.g., "50/100")
-});
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'api',
+    script: './dist/index.js',
+    error_file: '/dev/null',  // Disable PM2 error log
+    out_file: '/dev/null',    // Disable PM2 out log
+    merge_logs: true,
+    env: {
+      NODE_ENV: 'production',
+      // smartlog handles all logging
+    }
+  }]
+};
+```
 
-// Update progress
-progressBar.update(25);      // Set to 25% progress
+### Docker Integration
 
-// Increment progress
-progressBar.increment(5);    // Increase by 5 units
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY . .
+RUN pnpm install --production
 
-// Change color
-progressBar.setColor('blue');
+# smartlog handles structured logging
+# No need for special log drivers
+CMD ["node", "dist/index.js"]
+```
 
-// Complete the progress bar
-progressBar.complete();
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build: .
+    environment:
+      - NODE_ENV=production
+    # Logs are structured JSON, perfect for log aggregators
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
 ```
 
-#### Non-Interactive Environments
+## 🏆 Best Practices
 
-Both spinners and progress bars automatically detect non-interactive environments (CI/CD, piped output) and fallback to plain text logging:
+### 1. Use Semantic Log Levels
 
+```typescript
+// ✅ Good - semantic and meaningful
+logger.log('lifecycle', 'Server starting on port 3000');
+logger.log('success', 'Database connection established');
+logger.log('error', 'Failed to process payment', { orderId, error });
+
+// ❌ Bad - everything is 'info'
+logger.log('info', 'Server starting');
+logger.log('info', 'Database connected');
+logger.log('info', 'Error: payment failed');
 ```
-[Loading] Connecting to server
-[Success] Connected to server
-[Loading] Fetching records
-Progress: 50% (50/100)
-Progress: 100% (100/100)
-[Success] Fetching complete
+
+### 2. Include Structured Data
+
+```typescript
+// ✅ Good - structured data for analysis
+logger.log('error', 'API request failed', {
+  endpoint: '/api/users',
+  statusCode: 500,
+  duration: 1234,
+  userId: 'usr_123',
+  errorCode: 'INTERNAL_ERROR'
+});
+
+// ❌ Bad - data embedded in message
+logger.log('error', `API request to /api/users failed with 500 in 1234ms for user usr_123`);
 ```
 
-## Advanced Usage
+### 3. Use Log Groups for Correlation
 
-### Capturing All Console Output
+```typescript
+// ✅ Good - correlated logs
+async function processOrder(orderId: string) {
+  const logGroup = logger.createLogGroup(orderId);
+  
+  logGroup.log('info', 'Processing order');
+  logGroup.log('debug', 'Validating items');
+  logGroup.log('info', 'Charging payment');
+  logGroup.log('success', 'Order processed');
+}
+
+// ❌ Bad - no correlation
+async function processOrder(orderId: string) {
+  logger.log('info', `Processing order ${orderId}`);
+  logger.log('debug', `Validating items for ${orderId}`);
+  logger.log('info', `Charging payment for ${orderId}`);
+}
+```
 
-Capture all `console.log` and `console.error` output through Smartlog:
+### 4. Environment-Specific Configuration
 
 ```typescript
-logger.enableConsole({ captureAll: true });
+// ✅ Good - different configs per environment
+const logger = new Smartlog({
+  logContext: {
+    environment: process.env.NODE_ENV,
+    // ... other context
+  },
+  minimumLogLevel: process.env.NODE_ENV === 'production' ? 'info' : 'silly'
+});
+
+// Add destinations based on environment
+if (process.env.NODE_ENV === 'production') {
+  logger.addLogDestination(clickhouseDestination);
+  logger.addLogDestination(alertingDestination);
+} else {
+  logger.enableConsole();
+}
 ```
 
-### Increment Logging
+## 📖 API Reference
 
-For metrics and counters:
+### Smartlog Class
 
 ```typescript
-logger.increment('info', 'api_requests', { endpoint: '/users' });
+class Smartlog {
+  constructor(options?: ISmartlogOptions)
+  
+  // Logging methods
+  log(level: TLogLevel, message: string, data?: any, correlation?: ILogCorrelation): void
+  increment(level: TLogLevel, key: string, data?: any): void
+  
+  // Configuration
+  enableConsole(options?: IConsoleOptions): void
+  addLogDestination(destination: ILogDestination): void
+  addLogContext(context: Partial<ILogContext>): void
+  
+  // Log groups
+  createLogGroup(transactionId?: string): LogGroup
+  createScope(scopeName: string): Smartlog
+}
 ```
 
-### Log Correlation
+### Log Levels
 
-Correlate logs across services with correlation IDs:
+```typescript
+type TLogLevel = 
+  | 'silly'      // Very verbose debugging
+  | 'debug'      // Debug information
+  | 'info'       // Informational messages
+  | 'note'       // Notable events
+  | 'ok'         // Success confirmation
+  | 'success'    // Major success
+  | 'warn'       // Warning messages
+  | 'error'      // Error messages
+  | 'lifecycle'  // Application lifecycle events
+```
+
+### Log Package Structure
 
 ```typescript
-logger.log('info', 'Request received', { userId: 'user-123' }, {
-  id: 'req-abc-123',
-  type: 'service',
-  transaction: 'tx-payment-456'
-});
+interface ILogPackage {
+  timestamp: number;
+  level: TLogLevel;
+  message: string;
+  data?: any;
+  context: ILogContext;
+  correlation?: ILogCorrelation;
+}
 ```
 
-## API Documentation
+For complete API documentation, see [API.md](API.md).
+
+## 🤝 Contributing
 
-For detailed API documentation, see the [API.md](API.md) file.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
-## License and Legal Information
+## 📄 License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartlog',
-  version: '3.1.8',
+  version: '3.1.9',
   description: 'A minimalistic, distributed, and extensible logging tool supporting centralized log management.'
 }