@orion/logging

Sistema de logging estructurado, flexible y extensible para aplicaciones enterprise. 100% agnóstico de infraestructura.

🎯 Filosofía

Base totalmente flexible - No impone ningún transport. Tú decides:

• ✅ CloudWatch
• ✅ Kafka
• ✅ Winston
• ✅ Elasticsearch
• ✅ Console
• ✅ Tu propio transport personalizado

🚀 Instalación

npm install @orion/logging

Transports Opcionales

# Solo si vas a usar CloudWatch
npm install @aws-sdk/client-cloudwatch-logs

# Solo si vas a usar Kafka
npm install kafkajs

# Solo si vas a usar Winston
npm install winston

📖 Uso Básico

Console (Sin dependencias adicionales)

import { OrionLogger, ConsoleTransport } from '@orion/logging';

const logger = new OrionLogger({
  service: 'my-service',
  environment: 'production',
  transport: new ConsoleTransport({ format: 'json' }),
});

logger.info('Usuario autenticado', { userId: '123' });

CloudWatch (Requiere AWS SDK)

Nota: CloudWatch es opcional. Solo instala @aws-sdk/client-cloudwatch-logs si lo vas a usar. El SDK solo se carga cuando realmente usas CloudWatchTransport.

import { OrionLogger, CloudWatchTransport } from '@orion/logging';

const logger = new OrionLogger({
  service: 'my-service',
  environment: 'production',
  transport: new CloudWatchTransport({
    region: 'us-east-1',
    logGroup: '/aws/lambda/my-service',
    logStream: '2024/12/15'
  }),
});

Transport Personalizado (Kafka, Winston, etc.)

import { LogTransport, LogEntry } from '@orion/logging';
import { Kafka } from 'kafkajs';

// 1. Crear tu transport personalizado
class KafkaTransport extends LogTransport {
  private kafka: Kafka;
  private producer: any;

  constructor(options: { brokers: string[], topic: string }) {
    super();
    this.kafka = new Kafka({ brokers: options.brokers });
    this.producer = this.kafka.producer();
    this.producer.connect();
  }

  send(entry: LogEntry): void {
    this.producer.send({
      topic: 'logs',
      messages: [{ value: JSON.stringify(entry) }]
    });
  }
}

// 2. Usar tu transport
const logger = new OrionLogger({
  service: 'my-service',
  transport: new KafkaTransport({
    brokers: ['localhost:9092'],
    topic: 'application-logs'
  })
});

✨ Características

Logs Estructurados

logger.info('Order created', {
  orderId: 'order-123',
  amount: 99.99,
  currency: 'USD'
});

Sanitización Configurable

const logger = new OrionLogger({
  service: 'my-service',
  transport: new ConsoleTransport(),
  maskSensitiveData: true,
  redactedText: '[PROTEGIDO]',  // Personalizable
  customSensitiveKeys: ['dni', 'nif', 'ssn']  // Campos custom
});

logger.info('Login', {
  email: '[email protected]',
  password: 'secret'  // Se muestra como [PROTEGIDO]
});

Request Tracking Automático

import { loggerContext } from '@orion/logging';

// En tu middleware
app.use((req, res, next) => {
  loggerContext.run({
    requestId: req.headers['x-request-id'],
    correlationId: req.headers['x-correlation-id'],
    startTime: Date.now()
  }, () => next());
});

// Los logs automáticamente incluyen requestId
logger.info('Processing request');  // Incluye requestId automático

Child Loggers

const userLogger = logger.child({ userId: 'user-123' });

userLogger.info('Action performed');  // Incluye userId automático

🔧 API

Niveles de Log

• trace() - Debug muy detallado
• debug() - Debug general
• info() - Información importante
• warn() - Advertencias
• error() - Errores
• fatal() - Errores críticos
• audit() - Auditoría

Configuración

interface LoggerOptions {
  service: string;
  environment: 'development' | 'staging' | 'production' | 'test';
  transport: LogTransport;
  maskSensitiveData?: boolean;
  minLevel?: LogLevel;
  redactedText?: string;
  customSensitiveKeys?: string[];
}

🏗️ Crear Tu Propio Transport

import { LogTransport, LogEntry } from '@orion/logging';

export class MyCustomTransport extends LogTransport {
  send(entry: LogEntry): void | Promise<void> {
    // Tu lógica aquí
    // Ejemplo: enviar a Elasticsearch, Datadog, etc.
  }
}

📊 Formato de Log

{
  "timestamp": "2024-12-15T10:30:00.000Z",
  "level": "info",
  "message": "Usuario autenticado",
  "service": "my-service",
  "environment": "production",
  "requestId": "req-12345",
  "correlationId": "corr-67890",
  "context": {},
  "data": {
    "userId": "user-123"
  }
}

🔒 Seguridad

Sanitización automática de:

• Passwords
• Tokens
• API Keys
• Credit Cards
• SSN
• Y más...

100% Configurable - Agrega tus propios campos sensibles.

📦 Zero Dependencies

El core del logger no tiene dependencias obligatorias. Solo instalas lo que necesitas:

• CloudWatch SDK: solo si usas CloudWatch (se carga dinámicamente solo cuando lo usas)
• Kafka: solo si usas Kafka
• Winston: solo si usas Winston

Importante: CloudWatch usa importación dinámica, por lo que el SDK de AWS solo se carga cuando realmente instancias CloudWatchTransport. Puedes importar CloudWatchTransport desde @orion/logging sin problema, pero solo instala @aws-sdk/client-cloudwatch-logs si lo vas a usar.

🎓 Arquitectura

• ✅ Transport agnóstico - Usa cualquier backend
• ✅ Extensible - Crea tus propios transports
• ✅ Type-safe - TypeScript completo
• ✅ AsyncLocalStorage - Request tracking automático
• ✅ W3C Trace Context - Distributed tracing

📝 Licencia

MIT

🤝 Contribuir

Las contribuciones son bienvenidas. Este es un paquete base diseñado para máxima flexibilidad.