@erickzao/api-stats-cli NPM

🚀 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: support@api-stats.com

📄 Licença

MIT License - veja LICENSE para detalhes.

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

logging monitoring observability sdk api-stats auto-setup cli

axios express performance-now api-stats-logger

1.0.1

7 months ago

1.0.0

7 months ago