@octaviaflow/logger

Production-ready, high-performance logger for Octaviaflow microservices. Built for Bun runtime with zero dependencies and optimized for structured logging, file rotation, and multi-service support.

Features

• 🚀 High Performance: <1ms per log, handles 10,000+ logs/second
• 📦 Zero Dependencies: Uses Bun's native APIs
• 🎯 Multi-Service Support: Presets for backend, engine, and UI services
• 📝 Structured Logging: JSON format with rich metadata
• 🔄 Log Rotation: Size-based and time-based with compression
• 🎨 Multiple Formats: JSON, Pretty, Compact, and ECS (Elastic Common Schema)
• 🔒 Security: Built-in sanitization for sensitive data
• 📊 Context Management: AsyncLocalStorage for request/workflow context
• 🎭 Specialized Logging: Audit, security, performance, and metrics
• 🧪 Fully Typed: Complete TypeScript support

Installation

bun add @octaviaflow/logger

Quick Start

Backend Service

import { createBackendLogger } from '@octaviaflow/logger/presets';

const logger = createBackendLogger({
  level: 'info',
  version: '1.0.0',
});

logger.info('Server started', { port: 3000 });

// Request logging
logger.startRequest({
  requestId: 'req_123',
  method: 'GET',
  path: '/api/workflows',
  ip: '127.0.0.1',
  protocol: 'http',
  hostname: 'localhost',
  url: 'http://localhost:3000/api/workflows',
});

// ... handle request ...

logger.endRequest(200, 145);

Engine Service

import { createEngineLogger } from '@octaviaflow/logger/presets';

const logger = createEngineLogger({
  level: 'info',
  version: '1.0.0',
  workerId: 'worker_1',
});

// Workflow logging
logger.startWorkflow({
  workflowId: 'wf_123',
  workflowName: 'Data Sync',
  executionId: 'exec_456',
});

logger.info('Processing workflow step');

logger.endWorkflow(true);

UI Service

import { createUILogger } from '@octaviaflow/logger/presets';

const logger = createUILogger({
  level: 'warn',
  version: '1.0.0',
  enableRemote: true,
  remoteUrl: 'https://api.example.com/logs',
});

logger.info('User action', {
  action: 'button_click',
  component: 'WorkflowBuilder',
});

API Reference

Basic Logging

logger.fatal('Fatal error');
logger.error('Error occurred');
logger.warn('Warning message');
logger.info('Info message');
logger.debug('Debug information');
logger.trace('Trace details');

Specialized Logging

// Audit logging
logger.audit('user.login', {
  actor: { id: 'user_123', type: 'user' },
  resource: { type: 'session', id: 'session_456' },
  result: 'success',
});

// Security logging
logger.security('auth_failure', {
  event: 'auth_failure',
  severity: 'high',
  action: 'blocked',
});

// Performance logging
logger.performance('api.request', 145, {
  metrics: { dbQueries: 3, cacheHits: 5 },
});

// Metrics
logger.metric('api.requests.total', 100);

Context Management

// Set context for current async scope
logger.setContext({
  user: { userId: 'user_123', organizationId: 'org_456' },
});

// Create child logger with additional context
const apiLogger = logger.child({
  component: 'api',
  endpoint: '/api/workflows',
});

// Clear context
logger.clearContext();

Utilities

// Profile operations
logger.profile('operation_1');
// ... do work ...
logger.profile('operation_1'); // Logs duration

// Start timer
const getElapsed = logger.startTimer();
// ... do work ...
const duration = getElapsed();
logger.info('Operation completed', { duration });

// Flush and close
await logger.flush();
await logger.close();

Configuration

Custom Logger

import { Logger } from '@octaviaflow/logger';

const logger = new Logger({
  service: 'backend',
  environment: 'production',
  version: '1.0.0',
  level: 'info',
  format: 'json',
  transports: [
    {
      type: 'console',
      enabled: true,
      level: 'info',
      format: 'pretty',
    },
    {
      type: 'file',
      enabled: true,
      level: 'info',
      file: {
        path: './logs/app.log',
        maxSize: '10m',
        maxFiles: 10,
        compress: true,
        datePattern: 'YYYY-MM-DD',
      },
    },
    {
      type: 'http',
      enabled: true,
      level: 'error',
      http: {
        url: 'https://api.example.com/logs',
        batchSize: 10,
        flushInterval: 5000,
        retry: { attempts: 3, delay: 1000 },
      },
    },
  ],
  sanitize: {
    enabled: true,
    fields: ['password', 'token', 'apiKey'],
  },
  handleExceptions: true,
  handleRejections: true,
});

Log Formats

JSON (Default for Production)

{
  "timestamp": "2024-11-21T10:30:45.123Z",
  "level": "info",
  "service": "backend",
  "message": "API request completed",
  "requestId": "req_abc123",
  "statusCode": 200,
  "duration": 145
}

Pretty (Default for Development)

2024-11-21T10:30:45.123Z INFO  [backend] API request completed {"requestId":"req_abc123","statusCode":200}

Compact

10:30:45 I [backend] API request completed

ECS (Elastic Common Schema)

{
  "@timestamp": "2024-11-21T10:30:45.123Z",
  "log.level": "info",
  "message": "API request completed",
  "service": { "name": "backend", "version": "1.0.0" },
  "host": { "hostname": "api-server-1" }
}

File Rotation

Logs are automatically rotated based on:

• Size: When file exceeds maxSize (default: 10MB)
• Date: Daily rotation with datePattern (default: YYYY-MM-DD)
• Compression: Old files are gzipped (optional)
• Retention: Keep last maxFiles (default: 10)

Development

# Install dependencies
bun install

# Run examples
bun run example:backend
bun run example:engine
bun run example:ui

# Run tests
bun test

# Run benchmarks
bun run benchmark

# Build package
bun run build

# Type check
bun run typecheck

Performance

Benchmarked on Apple M1:

• Simple log: ~0.05ms
• Log with metadata: ~0.08ms
• File write: ~0.15ms
• Throughput: >15,000 logs/second

License

MIT

Author

Octaviaflow Team