npm package: @infosel-sdk/logger
Description: Logger SDK for Infosel financial services platform. Provides structured logging with Pino integration, optimized for Grafana/Loki visualization with service, context, and metadata support.
Author: Infosel Team
Latest version: 0.1.0

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

```bash
npm install @infosel-sdk/logger
```

Or install from a local .tgz file:

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

## Usage

### Production Usage (with Pino - For Grafana)

```typescript
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:

```typescript
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: 'user@example.com',
    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

```typescript
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](./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](./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](./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](https://jestjs.io).

## Creating a Package

To create a .tgz file for distribution:

```bash
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](./README.md)** - This file
- **[LOG_OUTPUT_EXAMPLES.md](./examples/LOG_OUTPUT_EXAMPLES.md)** - Log output examples
- **[nextjs-integration.ts](./examples/nextjs-integration.ts)** - Next.js integration examples
- **[GRAFANA_INTEGRATION.md](./examples/GRAFANA_INTEGRATION.md)** - Grafana setup guide
- **[INSTALLATION.md](./INSTALLATION.md)** - Installation and deployment guide
- **[CHANGELOG.md](./CHANGELOG.md)** - Version history

## License

MIT