🚀 API Stats Logger - SDK de Monitoramento

📋 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

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

⚡ Quick Start (REALMENTE 30 segundos!)

1. Setup 100% automático com CLI

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

// 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!

# 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

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

// 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

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

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

Koa

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

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:

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

Setup Manual (sem CLI)

// 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

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

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

// 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

// 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

# 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

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

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

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

🔧 Troubleshooting

Verificar Conectividade

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

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

Health Check

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

// 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

// Antes
const bunyan = require('bunyan');
const log = bunyan.createLogger({name: 'app'});

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

📚 Exemplos Completos

E-commerce API

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

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
• 🐛 Issues: GitHub Issues
• 💬 Discord: Comunidade
• 📧 Email: [email protected]

📄 Licença

MIT License - veja LICENSE para detalhes.

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