epago-logger-js

Librería de logger para JavaScript vanilla con soporte para traceId, paymentToken y formato específico.

Características

• ✅ Formato específico: fecharealdelvento (icono)ttid:tokenpago
• ✅ Propagación de traceId
• ✅ Compatibilidad con JavaScript vanilla
• ✅ Soporte para múltiples niveles de log
• ✅ Colores en consola
• ✅ Contexto de trazabilidad global

Requisitos del Sistema

• Node.js: >= 14.0.0
• Navegadores: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
• TypeScript: >= 4.0 (opcional, para type definitions)

Instalación

NPM

npm install epago-logger-js

Yarn

yarn add epago-logger-js

PNPM

pnpm add epago-logger-js

CDN (Navegador)

<!-- UMD build -->
<script src="https://unpkg.com/epago-logger-js@latest/dist/index.js"></script>

<!-- ESM build -->
<script type="module">
  import { Logger } from 'https://unpkg.com/epago-logger-js@latest/dist/index.esm.js';
</script>

Verificar Instalación

# Verificar que se instaló correctamente
npm list epago-logger-js

# Ver información del paquete
npm info epago-logger-js

Instalación por Entorno

Desarrollo

# Instalación como dependencia de desarrollo
npm install --save-dev epago-logger-js

# O con yarn
yarn add -D epago-logger-js

Producción

# Instalación como dependencia de producción
npm install --save epago-logger-js

# O con yarn
yarn add epago-logger-js

Global

# Instalación global (para CLI tools)
npm install -g epago-logger-js

# O con yarn
yarn global add epago-logger-js

Instalación de Versiones Específicas

# Instalar versión específica
npm install [email protected]

# Instalar versión beta
npm install epago-logger-js@beta

# Instalar desde GitHub
npm install epago/epago-logger-js

Troubleshooting de Instalación

Error: "Cannot find module"

# Limpiar cache de npm
npm cache clean --force

# Reinstalar
rm -rf node_modules package-lock.json
npm install

Error: "Permission denied"

# Usar sudo (no recomendado)
sudo npm install epago-logger-js

# Mejor: cambiar directorio de npm
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Error: "Network timeout"

# Aumentar timeout
npm config set timeout 60000

# Usar registry diferente
npm config set registry https://registry.npmjs.org/

Verificar Instalación Correcta

# Verificar que el paquete está instalado
npm list epago-logger-js

# Verificar que los archivos están presentes
ls node_modules/epago-logger-js/dist/

# Probar importación
node -e "console.log(require('epago-logger-js'))"

Uso Básico

Importación

// ES6 Modules
import { Logger, createLogger, globalTraceContext } from 'epago-logger-js';

// CommonJS
const { Logger, createLogger, globalTraceContext } = require('epago-logger-js');

Crear Logger

import { Logger } from 'epago-logger-js';

// Logger básico
const logger = new Logger({
  serviceName: 'mi-servicio',
  level: 'info',
  paymentToken: 'token123',
  traceId: 'trace456'
});

// Logs básicos
logger.info('Usuario autenticado correctamente');
logger.warn('Memoria alta detectada', { usage: '85%' });
logger.error('Error de conexión a base de datos');

Formato de Log

Todos los logs siguen el formato específico:

2024-01-15 10:30:45.123 ℹ️ttid:trace456:token123 Usuario autenticado correctamente

Donde:

• 2024-01-15 10:30:45.123 - Fecha y hora real del evento
• ℹ️ - Icono según el nivel de log
• ttid:trace456:token123 - TraceId y PaymentToken
• Usuario autenticado correctamente - Mensaje del log

Niveles de Log

import { LOG_LEVELS } from 'epago-logger-js';

logger.debug('Información de debug');     // 🔍
logger.info('Información general');       // ℹ️
logger.warn('Advertencia');               // ⚠️
logger.error('Error');                     // ❌
logger.critical('Error crítico');         // 🚨
logger.alert('Alerta de seguridad');       // 🚨
logger.emergency('Emergencia del sistema'); // 🆘
logger.maskSensitiveObject('Enmascarar cardNumber y cvv en objetos');

Ejemplo Completo de Niveles

const logger = new Logger({
  serviceName: 'payment-service',
  level: 'debug'
});

// Diferentes niveles de log
logger.debug('Iniciando validación de datos');
logger.info('Pago procesado exitosamente', { 
  amount: 100.50, 
  currency: 'USD' 
});
logger.warn('Límite de intentos alcanzado', { attempts: 3 });
logger.error('Error de validación', { field: 'email' });
logger.critical('Sistema de pagos no disponible');
logger.alert('Intento de fraude detectado', { ip: '192.168.1.100' });
logger.emergency('Base de datos no disponible');

Trazabilidad

Contexto Global

import { globalTraceContext } from 'epago-logger-js';

// Establecer contexto global
globalTraceContext.setContext({
  traceId: 'trace-123',
  paymentToken: 'token-789',
  userId: 'user-123',
  sessionId: 'session-456'
});

// Los logs ahora incluyen automáticamente el contexto
logger.info('Operación iniciada');

Contexto Hijo

// Crear contexto hijo con información adicional
const childContext = globalTraceContext.createChild({
  operationId: 'op-001',
  amount: 100.50,
  currency: 'USD'
});

// Logger con contexto específico
const tracedLogger = new Logger({
  serviceName: 'payment-processor',
  traceId: childContext.getContext().traceId,
  paymentToken: childContext.getContext().paymentToken
});

tracedLogger.info('Procesando pago con contexto específico');

Propagación en HTTP

import { TracePropagation } from 'epago-logger-js';

// Extraer contexto de headers HTTP
const headers = {
  'X-Trace-Id': 'trace-from-request',
  'X-Payment-Token': 'token-from-request'
};

const context = TracePropagation.extractFromHeaders(headers);
globalTraceContext.setContext(context);

// Generar headers para respuesta
const responseHeaders = TracePropagation.generateHeaders(globalTraceContext.getContext());
// responseHeaders = { 'X-Trace-Id': 'trace-123', 'X-Payment-Token': 'token-789' }

Middleware para Express.js

Express.js

import express from 'express';
import { expressMiddleware, errorHandler } from 'epago-logger-js';

const app = express();

// Middleware de logging automático
app.use(expressMiddleware({
  serviceName: 'my-api',
  level: 'info'
}));

// Middleware de manejo de errores
app.use(errorHandler({
  serviceName: 'my-api'
}));

app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' });
});

Características del Middleware

• ✅ Logging automático de requests y responses
• ✅ Propagación automática de traceId y paymentToken
• ✅ Headers automáticos en responses
• ✅ Manejo de errores con contexto completo
• ✅ Contexto de trazabilidad automático

Configuraciones Avanzadas

Logger con Factory Function

import { createLogger } from 'epago-logger-js';

const logger = createLogger({
  serviceName: 'api-service',
  level: 'info',
  enableColors: true
});

Logger por Entorno

import { createLoggerForEnvironment } from 'epago-logger-js';

// Desarrollo
const devLogger = createLoggerForEnvironment('development', {
  serviceName: 'my-app-dev'
});

// Producción
const prodLogger = createLoggerForEnvironment('production', {
  serviceName: 'my-app-prod'
});

// Testing
const testLogger = createLoggerForEnvironment('test', {
  serviceName: 'my-app-test'
});

Logger con Trazabilidad

import { createTracedLogger } from 'epago-logger-js';

const logger = createTracedLogger(
  { serviceName: 'payment-service' },
  {
    traceId: 'trace-123',
    paymentToken: 'token-789'
  }
);

Child Logger

// Crear logger hijo con contexto adicional
const childLogger = logger.child({
  userId: 'user-123',
  sessionId: 'session-456',
  operation: 'payment'
});

childLogger.info('Operación completada'); // Incluye contexto del padre + hijo
childLogger.warn('Validación adicional requerida', { 
  riskLevel: 'medium' 
});

Configuración de Niveles

// Cambiar nivel dinámicamente
logger.setLevel('debug');  // Mostrar todos los logs
logger.setLevel('info');   // Solo info, warn, error, critical, alert, emergency
logger.setLevel('error');  // Solo errores y críticos

// Verificar si un nivel será loggeado
if (logger.shouldLog('debug')) {
  logger.debug('Información detallada');
}

Colores y Formato

// Logger con colores (por defecto en desarrollo)
const coloredLogger = new Logger({
  serviceName: 'colored-service',
  enableColors: true
});

// Logger sin colores (para producción)
const plainLogger = new Logger({
  serviceName: 'plain-service',
  enableColors: false
});

// Logger sin consola (para testing)
const silentLogger = new Logger({
  serviceName: 'silent-service',
  enableConsole: false
});

Eventos Personalizados

La librería emite eventos personalizados en el navegador:

// Escuchar eventos de log
window.addEventListener('logger:log', (event) => {
  const { level, message, context, traceId, paymentToken } = event.detail;
  
  // Enviar a servicio de monitoreo
  sendToMonitoring({
    level,
    message,
    context,
    traceId,
    paymentToken,
    timestamp: new Date().toISOString()
  });
});

Ejemplos de Uso Real

API REST

import { Logger, globalTraceContext } from 'epago-logger-js';

const logger = new Logger({
  serviceName: 'api-server',
  level: 'info'
});

// Middleware para establecer contexto
app.use((req, res, next) => {
  // Extraer contexto de headers
  const context = {
    traceId: req.headers['x-trace-id'],
    paymentToken: req.headers['x-payment-token'],
    userId: req.user?.id,
    ip: req.ip
  };
  
  globalTraceContext.setContext(context);
  next();
});

// Endpoint de pago
app.post('/api/payments', async (req, res) => {
  logger.info('Iniciando procesamiento de pago', {
    amount: req.body.amount,
    currency: req.body.currency
  });
  
  try {
    const result = await processPayment(req.body);
    logger.info('Pago procesado exitosamente', { 
      transactionId: result.id 
    });
    res.json(result);
  } catch (error) {
    logger.error('Error procesando pago', { 
      error: error.message,
      amount: req.body.amount 
    });
    res.status(500).json({ error: 'Payment failed' });
  }
});

Frontend JavaScript

import { Logger, globalTraceContext } from 'epago-logger-js';

// Logger para frontend
const logger = new Logger({
  serviceName: 'frontend-app',
  level: 'info',
  enableColors: false // Sin colores en navegador
});

// Establecer contexto de usuario
globalTraceContext.setContext({
  traceId: generateTraceId(),
  paymentToken: getPaymentToken(),
  userId: getCurrentUserId(),
  sessionId: getSessionId()
});

// Función de pago
async function processPayment(paymentData) {
  logger.info('Iniciando proceso de pago', {
    amount: paymentData.amount,
    method: paymentData.method
  });
  
  try {
    const response = await fetch('/api/payments', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Trace-Id': globalTraceContext.getContext().traceId,
        'X-Payment-Token': globalTraceContext.getContext().paymentToken
      },
      body: JSON.stringify(paymentData)
    });
    
    if (response.ok) {
      logger.info('Pago completado exitosamente');
      return await response.json();
    } else {
      logger.error('Error en pago', { 
        status: response.status,
        statusText: response.statusText 
      });
      throw new Error('Payment failed');
    }
  } catch (error) {
    logger.error('Error procesando pago', { 
      error: error.message 
    });
    throw error;
  }
}

Worker/Background Jobs

import { Logger, globalTraceContext } from 'epago-logger-js';

const logger = new Logger({
  serviceName: 'background-worker',
  level: 'info'
});

// Procesar cola de pagos
async function processPaymentQueue() {
  logger.info('Iniciando procesamiento de cola de pagos');
  
  while (true) {
    try {
      const payment = await getNextPayment();
      
      if (!payment) {
        logger.debug('No hay pagos pendientes');
        await sleep(5000);
        continue;
      }
      
      // Establecer contexto para este pago
      globalTraceContext.setContext({
        traceId: payment.traceId,
        paymentToken: payment.token,
        paymentId: payment.id
      });
      
      logger.info('Procesando pago', {
        paymentId: payment.id,
        amount: payment.amount
      });
      
      await processPayment(payment);
      logger.info('Pago procesado exitosamente');
      
    } catch (error) {
      logger.error('Error procesando pago', {
        error: error.message,
        paymentId: payment?.id
      });
    }
  }
}

API Reference

Logger

• new Logger(options) - Crear instancia de logger
• setLevel(level) - Establecer nivel mínimo de log
• setPaymentToken(token) - Establecer payment token
• setTraceId(traceId) - Establecer trace ID
• child(bindings) - Crear logger hijo

TraceContext

• setContext(context) - Establecer contexto de trazabilidad
• getContext() - Obtener contexto actual
• clearContext() - Limpiar contexto
• createChild(additionalContext) - Crear contexto hijo

TracePropagation

• extractFromHeaders(headers) - Extraer contexto de headers HTTP
• generateHeaders(context) - Generar headers para propagación

Factory Functions

• createLogger(options) - Crear logger con opciones
• createTracedLogger(loggerOptions, traceOptions) - Crear logger con trazabilidad
• createLoggerForEnvironment(environment, customOptions) - Crear logger por entorno

Configuraciones por Defecto

// Desarrollo
{
  level: 'debug',
  enableColors: true,
  enableConsole: true
}

// Producción
{
  level: 'info',
  enableColors: false,
  enableConsole: true
}

// Testing
{
  level: 'error',
  enableColors: false,
  enableConsole: false
}

Licencia

MIT

Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request