Minilog

Minilog es una librería JavaScript ligera y flexible para el registro de eventos y análisis en aplicaciones web y Node.js. Diseñada para ser fácil de usar pero potente, permite capturar y enviar de forma eficiente sin sobrecargar la aplicación, eventos a la nube.

Características principales

• 💪 Sencilla pero potente: API minimalista que no requiere configuración compleja
• 📦 Ligera: Sin dependencias externas, tamaño reducido
• ⚡ Rendimiento optimizado: Envío en lotes (batching) para reducir peticiones HTTP
• 🔄 Flexible: Altamente configurable para adaptarse a diferentes necesidades
• 🌐 Universal: Funciona tanto en navegadores como en Node.js
• 🔒 Segura: Autenticación mediante API key
• 🛠️ Tipada: Escrita completamente en TypeScript

Instalación

npm install @g3yuri/minilog

yarn add @g3yuri/minilog

Uso básico

Minilog te permite crear tu propia instancia de la clase Minilog.

import { Minilog } from '@g3yuri/minilog';

// Crear una nueva instancia
const logger = new Minilog('tu-api-key');

// Usar el logger
logger.log('evento.personalizado', { datos: 'adicionales' });

Cómo funciona

Arquitectura

Minilog está diseñada con una arquitectura simple pero efectiva:

1. Inicialización: Se configura con una API key y opciones personalizadas
2. Registro de eventos: Los eventos se capturan con un nombre y datos opcionales
3. Cola de procesamiento: Los eventos se almacenan en una cola interna
4. Envío por lotes: Los eventos se envían al servidor en lotes según la configuración
5. Manejo de errores: Los errores se capturan y procesan mediante callbacks personalizables

Procesamiento por lotes (Batching)

Por defecto, Minilog agrupa múltiples eventos y los envía en una sola petición HTTP para optimizar el rendimiento. Este comportamiento se puede configurar mediante las opciones batchInterval y batchSize:

• batchInterval: Intervalo de tiempo (en milisegundos) para enviar los eventos acumulados
• batchSize: Número máximo de eventos a acumular antes de enviarlos

Si batchInterval se establece en 0, los eventos se envían inmediatamente sin agrupar.

Contexto global

Minilog permite definir un contexto global que se incluirá automáticamente en todos los eventos registrados. Esto es útil para incluir información común como la versión de la aplicación, el entorno o el ID de usuario.

Manejo de cierre de aplicación

Minilog detecta automáticamente cuando la aplicación se cierra (tanto en navegadores como en Node.js) e intenta enviar todos los eventos pendientes antes de que esto ocurra.

API completa

Clase Minilog

Constructor

new Minilog(apiKey: string, options?: MinilogOptions)

Crea una nueva instancia de Minilog con un API key y opciones opcionales.

Parámetros:

• apiKey: Clave del proyecto para autenticar las peticiones
• options: Objeto de configuración opcional

Métodos

log(event: string, data?: Record<string, any>): void

Registra un evento con datos opcionales.

Parámetros:

• event: Nombre del evento a registrar (ej: 'usuario.login')
• data: Objeto con datos adicionales relacionados con el evento

setOptions(options: Partial<MinilogOptions>): void

Actualiza la configuración de la instancia.

Parámetros:

• options: Objeto con las opciones a actualizar

flush(): Promise<void>

Fuerza el envío inmediato de todos los eventos en cola.

Interfaz MinilogOptions

interface MinilogOptions {
  batchInterval?: number;  // Intervalo en ms para enviar logs en batch
  batchSize?: number;      // Tamaño máximo del batch
  context?: Record<string, any>; // Contexto global
  enabled?: boolean;       // Habilitar/deshabilitar logging
  onError?: (error: Error) => void; // Callback para errores
}

Valores por defecto

{
  batchInterval: 5000, // 5 segundos
  batchSize: 10,
  context: {},
  enabled: true,
  onError: (error) => console.error('[Minilog]', error)
}

Ejemplos de uso

Uso en aplicación web

import { Minilog } from '@g3yuri/minilog';

// Inicializar al cargar la aplicación
const minilog = new Minilog('tu-api-key', {
  context: {
    app: 'tienda-online',
    version: '1.0.0'
  }
});

// Registrar navegación entre páginas
function cambiarPagina(pagina) {
  minilog.log('navegacion.pagina', { pagina });
  // Lógica de navegación...
}

// Registrar interacciones de usuario
document.getElementById('boton-comprar').addEventListener('click', () => {
  minilog.log('ui.click', {
    elemento: 'boton-comprar',
    productoId: obtenerProductoActual().id
  });
});

// Registrar errores
try {
  // Alguna operación...
} catch (error) {
  minilog.log('error.operacion', {
    mensaje: error.message,
    stack: error.stack
  });
}

Uso en API de Node.js

import express from 'express';
import { Minilog } from '@g3yuri/minilog';

// Inicializar minilog
const minilog = new Minilog('tu-api-key', {
  batchInterval: 10000, // 10 segundos (más adecuado para backend)
  context: {
    servicio: 'api-usuarios',
    entorno: process.env.NODE_ENV
  }
});

const app = express();

// Middleware para logging de solicitudes
app.use((req, res, next) => {
  const inicio = Date.now();
  
  res.on('finish', () => {
    minilog.log('api.request', {
      metodo: req.method,
      ruta: req.path,
      estado: res.statusCode,
      duracion: Date.now() - inicio,
      ip: req.ip
    });
  });
  
  next();
});

// Rutas
app.post('/usuarios', (req, res) => {
  try {
    // Crear usuario...
    const usuario = { id: '123', nombre: 'Usuario Nuevo' };
    
    minilog.log('usuario.creado', {
      id: usuario.id,
      datos: req.body
    });
    
    res.json(usuario);
  } catch (error) {
    minilog.log('error.crear_usuario', {
      error: error.message,
      datos: req.body
    });
    
    res.status(500).json({ error: 'Error al crear usuario' });
  }
});

app.listen(3000);

Consideraciones avanzadas

Rendimiento

Minilog está diseñada para tener un impacto mínimo en el rendimiento de tu aplicación:

• El procesamiento por lotes reduce significativamente el número de peticiones HTTP
• Las operaciones de logging son asíncronas y no bloquean el hilo principal
• El tamaño de la librería es mínimo para no afectar los tiempos de carga

Seguridad

Los logs se envían a través de HTTPS y se autentican mediante una API key. Es importante mantener segura esta API key y no exponerla públicamente.

Manejo de errores

Minilog incluye un sistema robusto de manejo de errores. Puedes personalizar cómo se manejan los errores mediante la opción onError:

minilog.setOptions({
  onError: (error) => {
    // Registrar en tu sistema de monitoreo
    errorMonitoring.captureException(error);
    
    // Notificar al equipo de desarrollo
    notificarError(error);
    
    // Mostrar en consola
    console.error('[Minilog Error]', error);
  }
});

Licencia

Este proyecto está licenciado bajo la Licencia Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).