@erickzao/api-stats-cli/README.md

CLI oficial para configuração automática do API Stats Logger

# 🚀 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
```

## ⚡ 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.**