seelogs

🧠 SeeLogs

• SeeLogs é uma biblioteca leve e extensível para captura, estruturação e envio de logs de aplicações
• Node.js e frontend.
• Oferece suporte a:
• Envio imediato ou em lotes;
• Detecção automática de métricas do sistema (CPU, memória, uptime, etc.);
• Logs críticos, informativos, debug e erros;
• Integração fácil com bancos de dados ou sistemas de monitoramento para análise de desempenho;
• Geolocalização e IPs de origem para rastreio;
• Detecção opcional de infraestrutura (sistema, host, arquitetura, etc.).

🚀 Instalação

npm install seelogs

ou

yarn add seelogs

🧩 Uso Básico

import SeeLogs from "seelogs";

const logger = new SeeLogs({
  token: "seu_token_aqui",
  service: "api-gateway"
});

// Log informativo
logger.info("Usuário autenticado com sucesso");

// Log de erro
logger.error("Falha ao conectar no banco de dados");

// Log crítico
logger.critical("Erro fatal: falha de segurança detectada");

// CommonJS (require)

Compatível com projetos Node.js antigos, scripts simples ou ambientes que não usam type: module.

const { SeeLogs } = require("seelogs");
// ou:
// const SeeLogs = require("seelogs").default;

const logger = new SeeLogs({
  token: "seu_token_aqui",
  service: "api-gateway"
});

logger.info("Aplicação iniciada");
logger.error("Erro ao conectar no banco");
// Log crítico

logger.critical("Falha crítica detectada");

🧾 Resultado esperado (no servidor de logs):

{
  "service": "api-gateway",
  "level": "info",
  "message": "Usuário autenticado com sucesso"
}

⚙️ Uso Avançado

🔹 Envio em Lotes (Batch Mode)

Para aplicações com alto volume de logs, é possível acumular eventos e enviá-los em intervalos regulares:

const logger = new SeeLogs({
  token: "seu_token_aqui", // token configurado em nossa plataforma
  service: "auth-api",
});

logger.info("Usuário logou");
logger.error("Timeout de API externa");
logger.warn("Uso de memória alto detectado");

✅ O envio é automático, garantindo desempenho e economia de rede.

🔧 Configuração Avançada com Variáveis de Ambiente

Para projetos mais robustos, recomenda-se criar uma classe wrapper para gerenciar as configurações:

import { config } from 'dotenv';
config();
import SeeLogs from 'seelogs';

const logsEnabled = process.env.LOGS_ENABLED === 'true';
const appName = process.env.APP_NAME;
const logsToken = process.env.LOGS_TOKEN;

class Logger {
  constructor() {
    if (logsEnabled) {
      this.logger = new SeeLogs({
        token: logsToken,
        service: appName
      });
    } else {
      this.logger = null;
    }
  }

  info(m, extra = null) { 
    if (this.logger) {
      this.logger.info(m, extra);
    } else {
      console.log(`[INFO] ${JSON.stringify(m)}`, extra ? JSON.stringify(extra) : '');
    }
  }
  
  warn(m, extra = null) { 
    if (this.logger) {
      this.logger.warn(m, extra);
    } else {
      console.warn(`[WARN] ${JSON.stringify(m)}`, extra ? JSON.stringify(extra) : '');
    }
  }
  
  error(m, extra = null) { 
    if (this.logger) {
      this.logger.error(m, extra);
    } else {
      console.error(`[ERROR] ${JSON.stringify(m)}`, extra ? JSON.stringify(extra) : '');
    }
  }
  
  debug(m, extra = null) { 
    if (this.logger) {
      this.logger.debug(m, extra);
    } else {
      console.debug(`[DEBUG] ${JSON.stringify(m)}`, extra ? JSON.stringify(extra) : '');
    }
  }
  
  critical(m, extra = null) { 
    if (this.logger) {
      this.logger.critical(m, extra);
    } else {
      console.error(`[CRITICAL] ${JSON.stringify(m)}`, extra ? JSON.stringify(extra) : '');
    }
  }
}

export default Logger;

💡 Variáveis de ambiente recomendadas:

• LOGS_TOKEN - Token de autenticação do See Logs
• APP_NAME ou LOGS_APP_NAME - Nome do serviço/aplicação

🧠 Captura de Métricas do Sistema

É possível anexar informações do sistema (CPU, memória, uptime, etc.) ao log com o parâmetro getInfo.

logger.info("Status do servidor", { getInfo: true });

🔍 Exemplo de saída no servidor:

{
  "level": "info",
  "message": "Status do servidor",
  "service": "backend",
  "systemInfo": {
    "cpu_usage_percent": 18.3,
    "memory_total_mb": 4096,
    "memory_used_mb": 2438,
    "memory_used_percent": 59.5,
    "load_average": [0.12, 0.09, 0.05],
    "uptime_seconds": 10523,
    "hostname": "server01",
    "platform": "linux",
    "arch": "x64",
    "cpus_total": 8,
    "timestamp": "2025-11-13T13:31:00.123Z"
  }
}

🌍 Geolocalização e IP

O servidor pode identificar o IP público e a localização aproximada do host que enviou o log.

"geo": {
  "ip": "187.15.102.33",
  "country": "BR",
  "city": "São Paulo",
  "provider": "Claro"
}

💡 Em ambientes de produção, recomenda-se combinar essas informações com autenticação de token para evitar spoofing.

🛑 Logs Críticos e Eventos Específicos

🚨 Eventos Críticos para Alertas

Os eventos do tipo critical são especialmente projetados para disparar alertas automáticos através de múltiplos canais:

logger.critical("Erro no envio da mensagem");

🧾 Saída no servidor:

{
  "level": "critical",
  "service": "api",
  "message": "Erro no envio da mensagem",
  "critical": true
}

⚡ Alertas automáticos na versão PRO:

• 🖥️ Alertas na Tela - Notificações em tempo real no dashboard
• 📧 Alertas por Email - Envio imediato para responsáveis técnicos
• 🔗 Alertas por Webhook - Integração com sistemas externos
• 📱 Alertas por Telegram - Mensagens individuais ou em grupos

🎯 Códigos de Evento Personalizados

É possível enviar códigos de evento (event_code) para rastreamento específico e alertas customizados:

logger.info("Falha de conexao", { event_code: "fail_connect_to_rabbit" });

⚡ Personalização de alertas na versão PRO:

• 🎨 Alertas customizados por level debug, info, warn, error, critical // opcional
• 🎨 Alertas customizados por event_code // opcional
• 🖥️ Notificações segmentadas na tela
• 📧 Templates de email personalizados
• 🔗 Webhooks específicos por tipo de evento
• 📱 Grupos do Telegram direcionados por categoria

🧾 Saída no servidor:

{
  "level": "info",
  "service": "api",
  "message": "Erro no banco de dados",
  "event_code": "fail_connect_to_rabbit"
}

🧹 Finalização Segura

O See Logs garante que nenhum log seja perdido ao encerrar a aplicação:

• Envia automaticamente logs pendentes em SIGINT, SIGTERM, ou beforeExit;
• Em navegadores, usa beforeunload para flush síncrono.

process.on("SIGINT", () => {
  logger.destroy();
  process.exit(0);
});

❤️ Licença

MIT © 2025 - See Logs Project