@infosel-sdk/logger

Logger SDK for Infosel financial services platform. Provides structured logging functionality powered by Pino for production-grade logging with Grafana integration.

Features

• Multiple Log Levels: debug, info, warn, error
• Structured Logging: Service, context, and metadata support
• Pino Integration: High-performance JSON logging
• Grafana Ready: Optimized for Loki/Grafana visualization
• Context Tracking: Track events like login, reconnection, retransmission
• TypeScript Support: Full type definitions included
• Dual Output: Pretty print for development, JSON for production
• Production Ready: Battle-tested logging for production environments

Installation

npm install @infosel-sdk/logger

Or install from a local .tgz file:

npm install ./infosel-sdk-logger-0.0.1.tgz

Usage

Production Usage (with Pino - For Grafana)

import InfoselLogger from '@infosel-sdk/logger';
import { LogLevel } from '@infosel-sdk/logger';

// Initialize logger with Pino for production
const logger = InfoselLogger.createLogger({
  usePino: true,
  prettyPrint: false,  // JSON output for Grafana/Loki
  minLevel: LogLevel.INFO,
  service: 'my-nextjs-app',
});

// Log with structured data
logger.log(LogLevel.INFO, 'User successfully logged in', {
  service: 'auth-service',
  context: 'login',
  metadata: {
    userId: '123',
    method: 'oauth',
    ip: '192.168.1.1'
  }
});

// Output (JSON for Grafana):
// {
//   "level": "INFO",
//   "time": "2024-11-27T10:30:45.123Z",
//   "service": "auth-service",
//   "context": "login",
//   "userId": "123",
//   "method": "oauth",
//   "ip": "192.168.1.1",
//   "msg": "User successfully logged in"
// }

Métodos Convenientes por Nivel

Cada nivel tiene su propio método para facilitar el uso:

const logger = InfoselLogger.createLogger({
  usePino: true,
  prettyPrint: true,  // Pretty print para desarrollo
  minLevel: LogLevel.DEBUG,
  service: 'my-app',
});

// ✅ logger.info() - Información general (más usado)
logger.info('User logged in', { 
  service: 'auth-service',
  context: 'login',
  metadata: { 
    userId: '123',
    email: '[email protected]',
    method: 'oauth'
  }
});

// ✅ logger.warn() - Advertencias (reconexiones, retransmisiones)
logger.warn('WebSocket reconnecting', { 
  service: 'websocket-service',
  context: 'reconnection',
  metadata: { 
    attempt: 1,
    maxAttempts: 5,
    reason: 'network_timeout'
  }
});

// ✅ logger.error() - Errores críticos
logger.error('Database connection failed', { 
  service: 'database-service',
  context: 'connection',
  metadata: { 
    errorMessage: 'Connection timeout',
    errorStack: error.stack,
    host: 'db.prod.com',
    retries: 3
  }
});

// ✅ logger.debug() - Debugging detallado (solo desarrollo)
logger.debug('Cache lookup performed', { 
  service: 'cache-service',
  context: 'cache-lookup',
  metadata: { 
    key: 'user:123',
    hit: true,
    ttl: 3600
  }
});

Configuration Options

interface LoggerConfig {
  minLevel?: LogLevel;          // Minimum log level: 'debug' | 'info' | 'warn' | 'error'
  enableTimestamps?: boolean;   // Include timestamps in logs
  enableColors?: boolean;       // Enable colored console output
  prefix?: string;              // Custom prefix for all log messages
  service?: string;             // Service or module name (e.g., 'auth-service')
  usePino?: boolean;            // Use Pino for logging (recommended for production)
  prettyPrint?: boolean;        // Pretty print output (for development)
  outputFn?: (msg: string) => void; // Custom output function
}

interface LogOptions {
  service?: string;             // Override service name
  context?: string;             // Event context (login, reconnection, etc.)
  metadata?: Record<string, unknown>; // Additional structured data
}

Log Levels

• DEBUG: Detailed information for debugging
• INFO: General informational messages
• WARN: Warning messages for potentially harmful situations
• ERROR: Error messages for serious problems

Log Structure

Each log includes:

• Timestamp: ISO 8601 format
• Level: Log level (INFO, WARN, ERROR, DEBUG)
• Service: Service or module name
• Context: Event context (login, reconnection, retransmission, etc.)
• Message: Clear, descriptive message
• Metadata: Additional structured data

Common Contexts

• login: User authentication events
• logout: User logout events
• reconnection: WebSocket/connection reconnection attempts
• retransmission: Message queue retransmission events
• http-request: API request/response
• connection: Database/service connections
• data-fetch: Data fetching operations

Examples

Next.js Integration

See examples/nextjs-integration.ts for complete Next.js examples including:

• API Routes logging
• WebSocket reconnection tracking
• Message queue retransmission
• Error boundary logging

Log Output Examples

See examples/LOG_OUTPUT_EXAMPLES.md for:

• JSON output examples (for Grafana)
• Pretty print examples (for development)
• Real-world use cases

Grafana Integration

See examples/GRAFANA_INTEGRATION.md for:

• Docker Compose configuration
• Loki setup
• Grafana dashboards
• LogQL queries
• Alerts configuration

Building

Run nx build logger to build the library.

Running unit tests

Run nx test logger to execute the unit tests via Jest.

Creating a Package

To create a .tgz file for distribution:

nx build logger
cd dist/packages/logger
npm pack

This will create infosel-sdk-logger-0.0.1.tgz that you can install in other projects.

Documentation

• README.md - This file
• LOG_OUTPUT_EXAMPLES.md - Log output examples
• nextjs-integration.ts - Next.js integration examples
• GRAFANA_INTEGRATION.md - Grafana setup guide
• INSTALLATION.md - Installation and deployment guide
• CHANGELOG.md - Version history

License

MIT