nexuslog: Módulo de Log de Serviços em Tempo Real

Este módulo NPM "full-stack" foi projetado para capturar, armazenar e exibir logs de serviços de sistemas em tempo real. Ele consiste em duas partes principais: um serviço de backend Node.js e um componente de frontend React.

Funcionalidades

• Backend Node.js:

  • Captura logs de serviços com uma estrutura de dados definida (LogEntry).
  • Armazena logs de forma eficiente em formato NDJSON (system-logs.json).
  • Retransmite logs em tempo real para clientes frontend via WebSockets.

• Frontend React (<LogViewer />):

  • Conecta-se ao servidor WebSocket para receber e exibir logs em tempo real.
  • Permite filtrar logs por serviço.
  • Interface de usuário responsiva e redimensionável.
  • Exibe logs formatados, incluindo mensagens, códigos e detalhes de erro (stack traces).

Instalação

Para instalar o módulo em seu projeto:

npm install @marcospaulop/nexuslog
# ou
yarn add @marcospaulop/nexuslog

Uso do Backend (Node.js)

1. Inicializar o Servidor WebSocket

A função init() pode ser usada de duas maneiras:

a) Anexar a um Servidor HTTP Existente

Se você já possui um servidor HTTP (por exemplo, de um aplicativo Express ou Fastify), importe a função init e passe seu servidor HTTP existente para ela. Isso anexará o servidor WebSocket ao seu servidor HTTP.

// server.ts
import { init, logger } from '@marcospaulop/nexuslog/backend'

const app = express()
const server = http.createServer(app)

// Inicializa o servidor WebSocket para o módulo de log, anexando-o ao servidor existente
init(server)

// ... suas rotas e lógica de aplicativo ...

const PORT = process.env.PORT || 3000
server.listen(PORT, () => {
  console.log(`Servidor rodando na porta ${PORT}`)
})

b) Iniciar um Servidor WebSocket Autônomo

Se você não tem um servidor HTTP existente ou prefere que o módulo de log execute seu próprio servidor WebSocket, chame init() sem argumentos. Ele iniciará um servidor HTTP interno na porta 3001 (por padrão) para hospedar o WebSocket.

// server.ts (ou um arquivo dedicado para o log)
import { init, logger } from '@marcospaulop/nexuslog/backend'

// Inicia um servidor WebSocket autônomo na porta 3001
init()

// Agora você pode usar o logger em qualquer lugar do seu aplicativo
// ...

2. Registrar Logs

Use a função logger.log() para enviar logs. Os logs serão armazenados no arquivo system-logs.json (no formato NDJSON) e transmitidos para todos os clientes WebSocket conectados.

// Em qualquer parte do seu código Node.js onde você deseja registrar um log
import { logger } from '@marcospaulop/nexuslog/backend'

// Exemplo de log de sucesso
logger.log('API-Auth', 'Usuário autenticado com sucesso.', 200, 'chamada')

// Exemplo de log sem código de status
logger.log('Serviço-Interno', 'Processamento de dados iniciado.', null, 'etapa')

// Exemplo de log de erro
try {
  // ... alguma operação que pode falhar ...
  throw new Error('Falha na conexão com o banco de dados')
} catch (e: any) {
  logger.log(
    'Worker-Pagamentos',
    'Erro ao processar pagamento.',
    500,
    'resultado',
    { name: e.name, message: e.message, stack: e.stack }
  )
}

Uso do Frontend (React)

1. Integrar o Componente <LogViewer />

No seu aplicativo React, importe o componente LogViewer e renderize-o onde desejar exibir os logs. Certifique-se de que o websocketUrl aponte para o endereço do seu servidor WebSocket. Se você usou a opção de servidor autônomo, a URL padrão será ws://localhost:3001.

// App.tsx (ou qualquer outro componente React)
import React from 'react'
import { LogViewer } from '@marcospaulop/nexuslog'

function App() {
  return (
    <div className='App'>
      <h1>Meu Aplicativo</h1>
      {/* Outros componentes do seu aplicativo */}

      {/* Se o backend estiver anexado ao seu servidor HTTP principal (ex: na porta 3000) */}
      <LogViewer websocketUrl='ws://localhost:3000' />

      {/* Se o backend estiver rodando em modo autônomo (porta 3001 por padrão) */}
      {/* <LogViewer websocketUrl="ws://localhost:3001" /> */}
    </div>
  )
}

export default App

2. Limpar Logs

O componente <LogViewer /> inclui um botão "🧹 Limpar Logs" na barra de cabeçalho. Ao clicar neste botão, os logs exibidos no frontend serão limpos e uma mensagem será enviada ao backend para truncar o arquivo system-logs.json.

Estrutura de Dados do Log (LogEntry)

O objeto de log aceito pela função logger.log() deve seguir a interface LogEntry:

interface LogEntry {
  servico: string // Nome do serviço que gerou o log (ex: "API-Auth", "Worker-Pagamentos")
  mensagem: string // A mensagem principal do log.
  codigo?: 100 | 200 | 400 | 404 | number | null // Código de status (100, 200, 400, 404, ou outros códigos HTTP/customizados), pode ser nulo.
  erro?: any // O objeto de erro (stack trace, etc.), se houver.
  tipo: 'chamada' | 'etapa' | 'resultado' // Tipo de log
  timestamp?: string // Adicionado automaticamente pelo logger, mas pode ser fornecido.
}

Desenvolvimento

Para desenvolver ou contribuir com este módulo:

1. Clonar o repositório:

   git clone <URL_DO_REPOSITORIO>
   cd nexuslog

2. Instalar dependências:

   npm install

3. Compilar o código:

   npm run build

   Isso compilará os arquivos TypeScript (.ts e .tsx) para JavaScript na pasta dist/.

Licença

ISC