api-stats-logger/README.md

SDK completo de logging e monitoramento de APIs com auto-instrumentação, dashboard em tempo real e CLI para configuração automática

# 🚀 API Stats Logger - SDK de Monitoramento

[![npm version](https://badge.fury.io/js/api-stats-logger.svg)](https://www.npmjs.com/package/api-stats-logger)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📋 Visão Geral

O **API Stats Logger** é um SDK de logging e monitoramento completo, inspirado no New Relic, que oferece:

- 🔍 **Auto-instrumentação** de frameworks (Express, NestJS, Fastify, Koa)
- 📊 **Métricas automáticas** de performance e erros
- 🔄 **Logs em tempo real** via WebSocket
- 🎯 **Sistema de alertas** inteligente
- 🛡️ **Retry automático** e tolerância a falhas
- 🔧 **Setup ultra-rápido** com criação automática de projeto
- 🤖 **Auto-criação** de API keys

## 🚀 Instalação

```bash
npm install api-stats-logger
# ou
yarn add api-stats-logger
```

**Problemas com versões?** Use uma dessas opções:

```bash
# Opção 1: Instalar com --legacy-peer-deps
npm install api-stats-logger --legacy-peer-deps

# Opção 2: Instalar com --force (não recomendado para produção)
npm install api-stats-logger --force

# Opção 3: Configurar npm para aceitar dependências peer opcionais
npm config set legacy-peer-deps true
npm install api-stats-logger
```

## ⚡ Quick Start (REALMENTE 30 segundos!)

### 1. Setup 100% automático com CLI
```bash
npx api-stats-init
```

**O CLI agora automaticamente:**
- ✅ Cria um projeto para você
- ✅ Gera uma API key 
- ✅ Configura todas as variáveis de ambiente
- ✅ Gera exemplos prontos para seu framework

### 2. Uso mais simples possível
```javascript
// Apenas isso! 🔥
require('api-stats-logger').init();

// Resto da sua aplicação...
const express = require('express');
const app = express();
// Logs automáticos para tudo!
```

### 3. Suas variáveis já estão prontas!
```env
# Gerado automaticamente pelo CLI
API_STATS_API_KEY=abc123def456...
API_STATS_SERVICE=minha-api
API_STATS_ENVIRONMENT=production
API_STATS_PROJECT_ID=507f1f77bcf86cd799439011
```

## 🎯 Integração por Framework

### Express.js
```javascript
const ApiStatsLogger = require('api-stats-logger');
const express = require('express');

// Opção 1: Auto-instrumentação (Recomendado)
const logger = ApiStatsLogger.init({
  autoDetect: true
});

// Opção 2: Middleware manual
const app = express();
app.use(ApiStatsLogger.expressMiddleware({
  logger: new ApiStatsLogger(),
  captureBody: false,
  skipPaths: ['/health']
}));
```

### NestJS
```typescript
// main.ts
import { ApiStatsLogger } from 'api-stats-logger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  app.use(ApiStatsLogger.nestMiddleware({
    logger: new ApiStatsLogger(),
    captureBody: false
  }));
  
  await app.listen(3000);
}
```

### Fastify
```javascript
const fastify = require('fastify');
const ApiStatsLogger = require('api-stats-logger');

// Auto-instrumentação automática detecta Fastify!
const logger = ApiStatsLogger.init();
```

### Koa
```javascript
const Koa = require('koa');
const ApiStatsLogger = require('api-stats-logger');

const app = new Koa();

// Auto-instrumentação automática detecta Koa!
const logger = ApiStatsLogger.init();
```

## 🔧 Configuração Avançada

### Configuração Completa
```javascript
const logger = new ApiStatsLogger({
  // Basic (auto-preenchidos pelo CLI)
  apiKey: process.env.API_STATS_API_KEY,
  url: process.env.API_STATS_URL,
  service: process.env.API_STATS_SERVICE,
  environment: process.env.API_STATS_ENVIRONMENT,
  
  // Performance
  batchSize: 50,
  flushInterval: 5000,
  maxRetries: 3,
  
  // Features
  captureErrors: true,
  capturePerformance: true,
  
  // Security
  captureBody: false,
  captureHeaders: false
});
```

### Setup para Projetos Existentes
Se você já tem um projeto e API key:

```bash
npx api-stats-init
# Escolha "Sim" quando perguntado se já tem projeto
# Cole sua API key existente
```

### Setup Manual (sem CLI)
```javascript
// Apenas se não quiser usar o CLI automático
const logger = new ApiStatsLogger({
  apiKey: 'sua-api-key-existente',
  service: 'minha-api',
  environment: 'production'
});
```

## 📊 Exemplos de Uso

### Logging Manual
```javascript
const logger = new ApiStatsLogger();

// Métodos de conveniência
logger.info('Usuário logado', { userId: 123, ip: '1.2.3.4' });
logger.error('Erro no banco', { error: 'timeout', table: 'users' });
logger.warn('Cache miss', { key: 'user:123' });
logger.debug('Debug info', { step: 'validation' });

// Logging avançado
logger.log({
  level: 'info',
  message: 'Operação concluída',
  metadata: {
    operation: 'payment',
    duration: 450,
    success: true,
    paymentId: 'pay_123'
  }
});
```

### Logging de Operações
```javascript
async function processPayment(paymentData) {
  const startTime = Date.now();
  const operationId = `pay_${Date.now()}`;
  
  logger.info('Processamento iniciado', { 
    operationId, 
    amount: paymentData.amount 
  });
  
  try {
    // Sua lógica aqui
    const result = await paymentGateway.process(paymentData);
    
    logger.info('Pagamento processado', {
      operationId,
      paymentId: result.id,
      duration: Date.now() - startTime,
      status: 'success'
    });
    
    return result;
  } catch (error) {
    logger.error('Erro no pagamento', {
      operationId,
      error: error.message,
      duration: Date.now() - startTime,
      paymentData: { ...paymentData, cardNumber: '[REDACTED]' }
    });
    
    throw error;
  }
}
```

### Instrumentação de Banco de Dados
```javascript
// MongoDB/Mongoose
const mongoose = require('mongoose');
const { database } = require('api-stats-logger/middleware');

const dbLogger = database({ 
  logger: new ApiStatsLogger(),
  captureQueries: true 
});

dbLogger.mongoose(); // Instrumenta automaticamente

// PostgreSQL
const { Client } = require('pg');
// Instrumentação automática já ativa!
```

## 📈 Métricas Automáticas

O SDK captura automaticamente:

### HTTP Requests
- Response time médio
- Status codes
- Throughput (req/min)
- Endpoints mais lentos
- Error rate

### Erros
- Tipos de erro
- Stack traces
- Frequência por serviço
- Padrões de erro

### Performance
- Uso de memória
- CPU usage
- Uptime
- GC metrics

### Banco de Dados
- Query time médio
- Queries mais lentas
- Tipos de operação
- Connection pool

## 🔔 Alertas Inteligentes

```javascript
// Alertas automáticos para:
// - Error rate > 5%
// - Response time > 2s
// - Memory usage > 80%
// - 5xx errors
// - Database timeouts

// Configurar alertas customizados
logger.alert({
  name: 'high_error_rate',
  condition: 'error_rate > 0.05',
  channels: ['email', 'slack'],
  cooldown: '5m'
});
```

## 📊 Dashboard e Visualização

Acesse o dashboard em: `http://localhost:3000`

### Features do Dashboard:
- 📊 Gráficos em tempo real
- 🔍 Busca avançada de logs
- 📈 Métricas de performance
- 🚨 Central de alertas
- 🔄 Logs ao vivo (WebSocket)

## 🛠️ CLI Úteis

```bash
# Setup inicial
npx api-stats-init

# Verificar conectividade
npx api-stats-test

# Ver estatísticas
npm run logs:stats

# Gerar relatório
npx api-stats-report --period=1d
```

## 🔒 Segurança

### Headers Sensíveis (Automaticamente Removidos)
- `authorization`
- `cookie`
- `x-api-key`
- `x-auth-token`

### Configuração de Segurança
```javascript
const logger = new ApiStatsLogger({
  captureBody: false,           // Não capturar payloads
  captureHeaders: false,        // Não capturar headers
  maxBodySize: 1024 * 5,       // Limite de 5KB
  skipPaths: ['/admin'],       // Pular rotas sensíveis
  sensitiveKeys: ['password', 'token'] // Keys para redact
});
```

## 🚀 Performance

### Configurações de Performance
```javascript
const logger = new ApiStatsLogger({
  batchSize: 100,              // Logs por batch
  flushInterval: 10000,        // Flush a cada 10s
  maxRetries: 5,               // Tentativas de reenvio
  enabled: process.env.NODE_ENV !== 'test' // Desabilitar em testes
});
```

### Estatísticas
```javascript
const stats = logger.getStats();
console.log(stats);
// {
//   sent: 1250,
//   failed: 5,
//   retries: 12,
//   bufferSize: 0,
//   avgFlushTime: 45.2
// }
```

## 🔧 Troubleshooting

### Verificar Conectividade
```javascript
const logger = new ApiStatsLogger({ apiKey: 'test' });

logger.info('Test log');
setTimeout(() => {
  const stats = logger.getStats();
  if (stats.failed > 0) {
    console.log('❌ Problemas de conectividade');
  } else {
    console.log('✅ Tudo funcionando!');
  }
}, 5000);
```

### Debug Mode
```javascript
const logger = new ApiStatsLogger({
  debug: true, // Logs detalhados no console
  logLevel: 'debug'
});
```

### Health Check
```javascript
app.get('/health', (req, res) => {
  const stats = logger.getStats();
  const healthy = stats.failed < stats.sent * 0.1; // < 10% falhas
  
  res.status(healthy ? 200 : 503).json({
    status: healthy ? 'ok' : 'degraded',
    logger: stats
  });
});
```

## 🔄 Migração de Outros Sistemas

### Do Winston
```javascript
// Antes
const winston = require('winston');
const logger = winston.createLogger({...});

// Depois
const ApiStatsLogger = require('api-stats-logger');
const logger = new ApiStatsLogger();

// API compatível!
logger.info('message', { metadata });
logger.error('error', { error: err });
```

### Do Bunyan
```javascript
// Antes
const bunyan = require('bunyan');
const log = bunyan.createLogger({name: 'app'});

// Depois
const logger = new ApiStatsLogger({ service: 'app' });
```

## 📚 Exemplos Completos

### E-commerce API
```javascript
const ApiStatsLogger = require('api-stats-logger');
const express = require('express');

const logger = ApiStatsLogger.init({
  service: 'ecommerce-api',
  captureBody: false, // PCI compliance
  skipPaths: ['/health', '/metrics']
});

const app = express();

app.post('/orders', async (req, res) => {
  const { userId, items, total } = req.body;
  
  logger.info('Novo pedido', { 
    userId, 
    itemCount: items.length, 
    total,
    channel: 'web'
  });
  
  try {
    const order = await createOrder({ userId, items, total });
    
    logger.info('Pedido criado', {
      orderId: order.id,
      userId,
      total,
      processingTime: order.processingTime
    });
    
    res.json(order);
  } catch (error) {
    logger.error('Erro ao criar pedido', {
      userId,
      error: error.message,
      stack: error.stack,
      items: items.length
    });
    
    res.status(500).json({ error: 'Erro interno' });
  }
});
```

### Microserviço
```javascript
const ApiStatsLogger = require('api-stats-logger');

const logger = new ApiStatsLogger({
  service: 'user-service',
  environment: process.env.NODE_ENV,
  tags: {
    version: process.env.SERVICE_VERSION,
    region: process.env.AWS_REGION
  }
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  logger.info('Recebido SIGTERM, finalizando...');
  await logger.close();
  process.exit(0);
});
```

## 🤝 Suporte

- 📖 **Documentação**: [docs.api-stats.com](https://docs.api-stats.com)
- 🐛 **Issues**: [GitHub Issues](https://github.com/api-stats/logger/issues)
- 💬 **Discord**: [Comunidade](https://discord.gg/api-stats)
- 📧 **Email**: support@api-stats.com

## 📄 Licença

MIT License - veja [LICENSE](LICENSE) para detalhes.

---

**Feito com ❤️ para desenvolvedores que querem observabilidade simples e poderosa.** 

## ✨ Novidades v1.1.1

🚀 **Suporte Completo a Múltiplos Frameworks!**
- ✅ Express 4.x e 5.x
- ✅ NestJS 8.x, 9.x e 10.x  
- ✅ Fastify 3.x, 4.x e 5.x
- ✅ Koa 2.x+
- 🔧 Resolvidos problemas de dependências peer

## 📦 Uso por Framework

### Express (4.x e 5.x)

```javascript
const ApiStatsLogger = require('api-stats-logger');

const logger = new ApiStatsLogger({
  apiKey: 'sua-api-key',
  service: 'meu-servico'
});

const app = express();

// Middleware automático
app.use(ApiStatsLogger.expressMiddleware({ logger }));

// Ou use a auto-instrumentação
const logger = ApiStatsLogger.init({
  apiKey: 'sua-api-key',
  service: 'meu-servico',
  autoDetect: true // Detecta Express automaticamente
});
```

### NestJS

```typescript
// main.ts
import { ApiStatsLogger } from 'api-stats-logger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const logger = new ApiStatsLogger({
    apiKey: process.env.API_STATS_API_KEY,
    service: 'meu-servico-nest'
  });

  app.use(ApiStatsLogger.nestMiddleware({ logger }));
  
  await app.listen(3000);
}
```

### Fastify

```javascript
const fastify = require('fastify')({ logger: true });
const ApiStatsLogger = require('api-stats-logger');

const logger = new ApiStatsLogger({
  apiKey: 'sua-api-key',
  service: 'meu-servico-fastify'
});

// Registrar como plugin
fastify.register(async function (fastify) {
  fastify.addHook('preHandler', ApiStatsLogger.fastifyMiddleware({ logger }));
});

// Ou usar auto-instrumentação
const logger = ApiStatsLogger.init({
  apiKey: 'sua-api-key',
  autoDetect: true
});
```

### Koa

```javascript
const Koa = require('koa');
const ApiStatsLogger = require('api-stats-logger');

const app = new Koa();

const logger = new ApiStatsLogger({
  apiKey: 'sua-api-key',
  service: 'meu-servico-koa'
});

// Adicionar middleware
app.use(ApiStatsLogger.koaMiddleware({ logger }));

// Ou usar auto-instrumentação
const logger = ApiStatsLogger.init({
  apiKey: 'sua-api-key',
  autoDetect: true
});
```

## 🔧 Configuração Avançada

### Variáveis de Ambiente

Crie um arquivo `.env`:

```env
API_STATS_API_KEY=sua-api-key-aqui
API_STATS_URL=https://api.apistats.dev/logs
API_STATS_SERVICE=meu-servico
API_STATS_ENVIRONMENT=production
API_STATS_BATCH_SIZE=20
API_STATS_FLUSH_INTERVAL=5000
API_STATS_ENABLED=true
```

### Opções do Middleware

```javascript
const middlewareOptions = {
  logger,
  captureBody: true,        // Capturar corpo das requisições
  captureHeaders: false,    // Capturar headers (dados sensíveis)
  captureQuery: true,       // Capturar query parameters
  captureParams: true,      // Capturar route parameters
  skipPaths: ['/health', '/metrics'], // Pular rotas específicas
  skipMethods: ['OPTIONS'], // Pular métodos específicos
  maxBodySize: 1024 * 10   // Tamanho máximo do corpo (10KB)
};

app.use(ApiStatsLogger.expressMiddleware(middlewareOptions));
```

## 🔍 Compatibilidade de Versões

| Framework | Versões Suportadas | Status |
|-----------|-------------------|---------|
| Express   | 4.18.0+ e 5.x     | ✅ Pleno |
| NestJS    | 8.x, 9.x, 10.x   | ✅ Pleno |
| Fastify   | 3.x, 4.x, 5.x    | ✅ Pleno |
| Koa       | 2.x+              | ✅ Pleno |
| Node.js   | 14.0.0+           | ✅ Pleno |

## 🚨 Resolvendo Conflitos de Dependências

### Problema: ERESOLVE com Express 5.x

**Erro:**
```
npm error ERESOLVE could not resolve
npm error Could not resolve dependency:
npm error peerOptional express@"^4.18.0" from api-stats-logger@1.1.0
```

**Soluções:**

1. **Atualizar para v1.1.1+** (recomendado):
```bash
npm install api-stats-logger@latest
```

2. **Usar flags do npm**:
```bash
npm install api-stats-logger --legacy-peer-deps
```

3. **Configurar .npmrc**:
```bash
echo "legacy-peer-deps=true" >> .npmrc
npm install api-stats-logger
```

### Problemas com TypeScript

Se estiver usando TypeScript, instale os tipos:

```bash
npm install --save-dev @types/express @types/koa
```

## 📊 Recursos

- ✅ **Auto-instrumentação** - Detecta seu framework automaticamente
- ✅ **Múltiplos Frameworks** - Express, NestJS, Fastify, Koa
- ✅ **Captura de Requests/Responses** - Dados completos de HTTP
- ✅ **Métricas de Performance** - Tempo de resposta, CPU, memória
- ✅ **Detecção de Erros** - Captura automática de exceções
- ✅ **Instrumentação de Banco** - MongoDB, PostgreSQL, MySQL
- ✅ **Dashboard em Tempo Real** - Visualização ao vivo
- ✅ **Batching Inteligente** - Envio otimizado de logs
- ✅ **Retry Automático** - Reenvio em caso de falha

## 🏃‍♂️ Início Rápido Completo

```bash
# 1. Instalar
npm install api-stats-logger

# 2. Configurar automaticamente
npx api-stats-init

# 3. Definir variáveis de ambiente
export API_STATS_API_KEY="sua-api-key"

# 4. Usar no código (detecção automática)
```

```javascript
const ApiStatsLogger = require('api-stats-logger');

// Inicialização com auto-detecção
const logger = ApiStatsLogger.init({
  apiKey: process.env.API_STATS_API_KEY,
  service: 'meu-servico',
  autoDetect: true  // Detecta e instrumenta automaticamente
});

// Pronto! Seu framework será detectado e instrumentado automaticamente
```

## 📚 Documentação Completa

- [Guia de Setup](./API-STATS-SETUP.md)
- [Changelog](./CHANGELOG.md)
- [Release Notes](./RELEASE-NOTES.md)

## 🆘 Suporte

- 📧 Email: dev@grupoloyalty.com.br
- 🐛 Issues: [GitHub Issues](https://github.com/grupo-loyalty/api-stats-logger/issues)
- 📖 Docs: [Documentation](https://github.com/grupo-loyalty/api-stats-logger#readme)

## 📄 Licença

MIT License - veja [LICENSE](LICENSE) para detalhes.