@mirantes-micro/watchtower

Biblioteca de tracing e logging para backends Node/NestJS e Bun/Elysia com suporte a contexto assíncrono e envio imediato para API externa.

🚀 Instalação

npm install @mirantes-micro/watchtower
# ou
pnpm add @mirantes-micro/watchtower
# ou
yarn add @mirantes-micro/watchtower

📖 Uso

NestJS

import { Module } from '@nestjs/common';
import { TracingModule } from '@mirantes-micro/watchtower/nestjs';

@Module({
  imports: [
    TracingModule.forRoot({
      serviceName: 'meu-servico',
      apiKey: 'sua-api-key',
      endpoint: 'https://api.exemplo.com/logs',
    }),
  ],
})
export class AppModule {}

O TracingModule automaticamente:

• ✅ Aplica middleware global que inicia o contexto de tracing em cada requisição
• ✅ Adiciona interceptor global que captura erros
• ✅ Todos os logs incluem automaticamente o transactionId e contexto da requisição
• ✅ Envia logs imediatamente para o endpoint configurado

Elysia (Bun)

import { Elysia } from 'elysia';
import { elysiaTracing } from '@mirantes-micro/watchtower/elysia';

const app = new Elysia()
  .use(
    elysiaTracing({
      serviceName: 'meu-servico',
      apiKey: 'sua-api-key',
      endpoint: 'https://api.exemplo.com/logs',
    })
  )
  .get('/', () => 'Hello World')
  .listen(3000);

Express (Node.js)

import express from 'express';
import { expressTracing } from '@mirantes-micro/watchtower/express';

const app = express();

app.use(
  expressTracing({
    serviceName: 'meu-servico',
    apiKey: 'sua-api-key',
    endpoint: 'https://api.exemplo.com/logs',
  })
);

app.get('/', (req, res) => {
  res.json({ message: 'Hello World' });
});

app.listen(3000);

Uso Manual do Core

Você também pode usar o core diretamente:

import { initTracing, trace, runWithContext } from '@mirantes-micro/watchtower';

// Configure o monitor
initTracing({
  serviceName: 'meu-servico',
  apiKey: 'sua-api-key',
  endpoint: 'https://api.exemplo.com/logs',
});

// Use o contexto
runWithContext(
  {
    transactionId: 'abc123',
    userId: 'user-456',
    startTime: Date.now(),
  },
  () => {
    trace.info('Operação iniciada', { step: 'processamento' });
    trace.error(new Error('Algo deu errado'), { additional: 'data' });
  }
);

🔧 Configuração

Opções

interface TransporterConfig {
  endpoint: string;      // URL da API externa (obrigatório)
  serviceName: string;  // Nome do serviço (obrigatório)
  apiKey: string;       // Chave de API (obrigatório)
}

Formato dos Logs

Os logs são enviados para a API no seguinte formato:

{
  service_name: string;    // Nome do serviço configurado
  path: string;            // Caminho da requisição
  status_code: number;     // Código de status HTTP
  trace: string;           // Payload completo em formato JSON string
  level: 'debug' | 'info' | 'warn' | 'error' | 'alert';
  timestamp: string;       // Timestamp em formato ISO
}

O campo trace contém um JSON stringificado com todos os dados do contexto:

{
  "transactionId": "abc123",
  "message": "Request started",
  "method": "GET",
  "path": "/api/users",
  "url": "/api/users",
  "startTime": 1234567890,
  ...outros dados de contexto
}

Nota: Os logs são enviados imediatamente quando detectados, em formato de array JSON para a API.

Autenticação

A API usa o header X-API-Key para autenticação. A apiKey deve ser passada na configuração.

📝 Níveis de Log

• trace.debug() - Logs de debug
• trace.info() - Informações gerais
• trace.warn() - Avisos
• trace.error() - Erros (aceita Error ou string)

📊 Funcionalidades

• ✅ Contexto Assíncrono: Usa AsyncLocalStorage para manter contexto através de operações assíncronas
• ✅ Envio Imediato: Logs são enviados imediatamente quando detectados, sem esperar a requisição terminar
• ✅ Cross-Runtime: Funciona em Node.js e Bun
• ✅ TypeScript: Totalmente tipado
• ✅ Dual Publishing: Suporta ESM e CommonJS

🏗️ Arquitetura

O pacote é dividido em três camadas:

1. Core: Gerencia contexto assíncrono e formatação de logs
2. Transporter: Envia logs imediatamente para API externa
3. Adapters: Integrações específicas para cada framework (NestJS, Express, Elysia)

📄 Licença

MIT