@monitorantes

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

Instalar do GitHub Packages

npm install @monitorantes

Nota: Se o pacote for privado, você precisa configurar autenticação. Veja o guia completo em GITHUB_PACKAGES.md.

Configuração de Autenticação (para pacotes privados)

⚠️ Cada desenvolvedor deve usar seu próprio token do GitHub!

1. Crie um arquivo .npmrc no seu projeto:

@mirantes:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

2. Crie seu próprio token em: https://github.com/settings/tokens

   • Permissão: read:packages
   • Se pacote privado: precisa ter acesso ao repositório

3. Defina a variável de ambiente com seu token:

export GITHUB_TOKEN=seu_proprio_token_github

📖 Uso

NestJS

import { Module } from '@nestjs/common';
import { TracingModule } from '@monitorantes/nestjs';

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

O TracingModule automaticamente:

• Adiciona um middleware que inicia o contexto de tracing em cada requisição
• Adiciona um interceptor global que captura erros
• Todos os logs incluem automaticamente o transactionId e contexto da requisição

Elysia (Bun)

import { Elysia } from 'elysia';
import { elysiaTracing } from '@monitorantes/elysia';

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

Express (Node.js)

import express from 'express';
import { expressTracing } from '@monitorantes/express';

const app = express();

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

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

app.listen(3000);

O middleware Express automaticamente:

• Captura o início e fim de cada requisição
• Gerencia o contexto assíncrono via AsyncLocalStorage
• Captura erros automaticamente

O plugin Elysia automaticamente:

• Captura o início e fim de cada requisição
• Gerencia o contexto assíncrono via AsyncLocalStorage
• Captura erros automaticamente

Uso Manual do Core

Você também pode usar o core diretamente em qualquer lugar do seu código:

import { initTracing, trace, runWithContext } from '@monitorantes';

// Primeiro, configure o monitor
initTracing({
  serviceName: 'meu-servico',
  apiKey: 'sua-api-key', 
  endpoint: 'https://example-api.url', 
});

// Depois, use o contexto
runWithContext(
  {
    transactionId: 'abc123',
    userId: 'user-456',
    startTime: Date.now(),
  },
  () => {
    trace.info('Operação iniciada', { step: 'processamento' });
    
    // Qualquer código aqui terá acesso ao contexto
    trace.error(new Error('Algo deu errado'), { additional: 'data' });
  }
);

📊 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

🔧 Configuração

Opções do Transporter

interface TransporterConfig {
  endpoint: string;           // URL da API externa (obrigatório)
  serviceName: string;        // Nome do serviço (obrigatório)
  apiKey: string;             // Chave de API (obrigatória - deve ser passada na configuração)
}

Notas:

• O endpoint é obrigatório e deve ser passado na configuração.
• A apiKey é obrigatória e deve ser passada na configuração (não via variável de ambiente).
• O serviceName é obrigatório e identifica o serviço nos logs.

Formato dos Logs

Os logs são enviados para a API no seguinte formato, correspondente à estrutura da API externa:

{
  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 (contém transactionId, message, dados de contexto, etc.)
  level: 'debug' | 'info' | 'warn' | 'error' | 'alert';  // Níveis em minúsculas
  timestamp: string;       // Timestamp em formato ISO string (ex: "2025-11-19T15:51:01.332Z")
}

Nota: Os logs são enviados imediatamente quando detectados, em formato de array JSON para a API (mesmo que contenha apenas um log).

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
}

Autenticação

A API usa o header X-API-Key para autenticação. A apiKey é obrigatória e deve ser passada na configuração:

// ✅ Correto - apiKey na configuração
elysiaTracing({
  serviceName: 'meu-servico',
  apiKey: 'sua-api-key', 
});

// ❌ Errado - não há variável de ambiente para API key
// O pacote não lê API key de variáveis de ambiente

Configuração:

• O endpoint deve ser passado na configuração ao inicializar o monitor.
• A apiKey deve ser passada na configuração (não via variável de ambiente).
• Exemplo de endpoint: https://example-api.url

📝 Níveis de Log

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

🏗️ Arquitetura

O pacote é dividido em três camadas:

1. Core: Gerencia contexto assíncrono e formatação de logs
2. Transporter: Envia logs em lote para API externa
3. Adapters: Integrações específicas para cada framework

🧪 Testes

Para testar o pacote localmente, você pode usar npm link:

# No diretório do pacote
npm link

# No projeto de teste
npm link @monitorantes

Depois, configure o monitor conforme os exemplos acima e faça algumas requisições para verificar se os logs estão sendo enviados.

📦 Publicação

Este pacote é publicado no GitHub Packages.

Para Publicar

Veja o guia completo em GITHUB_PACKAGES.md que inclui:

• ✅ Como criar token de acesso
• ✅ Configuração do projeto
• ✅ Passo a passo de publicação
• ✅ Como usar o pacote em outros projetos
• ✅ Configuração para CI/CD
• ✅ Troubleshooting

Publicação Rápida

# 1. Configure o token
export GITHUB_TOKEN=seu_token_github

# 2. Crie o .npmrc (se ainda não tiver)
cp .npmrc.example .npmrc

# 3. Build e publicação
npm run build
npm publish

📄 Licença

MIT