@push.rocks/smartlog 🚀

The ultimate TypeScript logging solution for modern applications

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. 🎯

🌟 Why smartlog?

• 🎨 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

# Using pnpm (recommended)
pnpm add @push.rocks/smartlog

# Using npm
npm install @push.rocks/smartlog

# Using yarn
yarn add @push.rocks/smartlog

🚀 Quick Start

Your First Logger

import { Smartlog } 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'
  }
});

// Enable beautiful console output
logger.enableConsole();

// Start logging!
logger.log('info', '🎉 Application started successfully');
logger.log('error', '💥 Database connection failed', { 
  errorCode: 'DB_TIMEOUT',
  attemptCount: 3 
});

Using the Default Logger

For quick prototyping and simple applications:

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:

// Lifecycle events
logger.log('lifecycle', '🔄 Container starting up...');

// 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:

// 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

🎯 Log Destinations

Built-in Destinations

🖥️ Local Console (Enhanced)

Beautiful, colored output for local development:

import { DestinationLocal } from '@push.rocks/smartlog/destination-local';

const localDestination = new DestinationLocal({
  logLevel: 'debug'  // Optional: filter by minimum log level
});

logger.addLogDestination(localDestination);

📁 File Logging

Persist logs to files with automatic rotation support:

import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';

const fileDestination = new SmartlogDestinationFile('./logs/app.log');
logger.addLogDestination(fileDestination);

🌐 Browser DevTools

Optimized for browser environments with styled console output:

import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';

const devtools = new SmartlogDestinationDevtools();
logger.addLogDestination(devtools);

📊 ClickHouse Analytics

Store logs in ClickHouse for powerful analytics:

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
});

logger.addLogDestination(clickhouse);

// Query your logs with SQL!
// SELECT * FROM logs WHERE level = 'error' AND timestamp > now() - INTERVAL 1 HOUR

🔗 Remote Receiver

Send logs to a centralized logging service:

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
});

logger.addLogDestination(receiver);

🛠️ Custom Destinations

Build your own destination for any logging backend:

import { ILogDestination, ILogPackage } from '@push.rocks/smartlog/interfaces';

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
      }
    });
  }
}

// Use your custom destination
logger.addLogDestination(new ElasticsearchDestination({
  node: 'https://elasticsearch.example.com'
}));

🎨 Interactive Console Features

Spinners

Create beautiful loading animations that degrade gracefully in CI/CD:

import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';

const spinner = new SmartlogSourceInteractive();

// 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:

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:

// 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' }

Scoped Logging

Create scoped loggers for different components:

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:

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:

// 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:

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

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: process.env.CLICKHOUSE_HOST,
  database: 'microservices_logs'
});
logger.addLogDestination(clickhouse);

// Enable local console for development
if (process.env.NODE_ENV === 'development') {
  logger.enableConsole();
}

// 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();
});

CLI Tool with Progress Tracking

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!');
}

Production Logging with Multiple Destinations

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';

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
});

// Console for container logs (structured for log aggregators)
logger.addLogDestination(new DestinationLocal());

// File for audit trail
logger.addLogDestination(new SmartlogDestinationFile('/var/log/app/audit.log'));

// Central logging service
logger.addLogDestination(new SmartlogDestinationReceiver({
  endpoint: 'https://logs.enterprise.com/ingest',
  apiKey: process.env.LOG_API_KEY,
  batchSize: 100,
  flushInterval: 5000
}));

// 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
      });
    }
  }
});

🔌 Integration with Other Tools

PM2 Integration

// 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
    }
  }]
};

Docker Integration

FROM node:18-alpine
WORKDIR /app
COPY . .
RUN pnpm install --production

# smartlog handles structured logging
# No need for special log drivers
CMD ["node", "dist/index.js"]

# 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"

🏆 Best Practices

1. Use Semantic Log Levels

// ✅ 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');

2. Include Structured Data

// ✅ 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`);

3. Use Log Groups for Correlation

// ✅ 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}`);
}

4. Environment-Specific Configuration

// ✅ 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();
}

📖 API Reference

Smartlog Class

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 Levels

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

interface ILogPackage {
  timestamp: number;
  level: TLogLevel;
  message: string;
  data?: any;
  context: ILogContext;
  correlation?: ILogCorrelation;
}

For complete API documentation, see API.md.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 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 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.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.