Package Exports

api-stats-logger
api-stats-logger/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (api-stats-logger) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🚀 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

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

# 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

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

🔐 Novo! Autenticação Google OAuth (Recomendado)

npx api-stats-init
# Selecione "1. 🔐 Login com Google (recomendado)"
# Navegador será aberto automaticamente
# Faça login com sua conta Google
# Pronto! Projeto configurado automaticamente

Vantagens do Google OAuth:

🚀 Mais rápido: Sem necessidade de criar contas
🛡️ Mais seguro: Sem senhas para gerenciar
🔄 Mais conveniente: Um clique para autenticar
🎯 Integrado: Funciona com contas @grupoloyalty.com.br e @eway.dev

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'
});

🔧 Configuração Google OAuth (Avançado)

Se você quiser usar suas próprias credenciais Google OAuth:

Configurar no Google Cloud Console:

1. Acesse https://console.cloud.google.com/
2. Crie um projeto ou selecione um existente
3. Vá para "APIs & Services" > "Credentials"
4. Clique em "Create Credentials" > "OAuth 2.0 Client ID"
5. Selecione "Desktop Application"
6. Configure as URIs de redirecionamento:
   - http://localhost:8080/auth/callback
   - http://127.0.0.1:8080/auth/callback

Configurar variáveis de ambiente:

# Copie o arquivo de exemplo
cp .env.google-oauth.example .env.google-oauth

# Edite com suas credenciais
export GOOGLE_OAUTH_CLIENT_ID="seu-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="seu-client-secret"

Testar a configuração:

# Carregar variáveis e testar
source .env.google-oauth
npm run test:google-auth

Usar na CLI:

# Carregar variáveis e executar CLI
source .env.google-oauth
npx api-stats-init

📊 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 com Google OAuth
npx api-stats-init

# Verificar conectividade
npx api-stats-test

# Ver estatísticas
npm run logs:stats

# Testar Google OAuth
npm run test:google-auth

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

✨ 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)

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

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

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

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:

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

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:

Atualizar para v1.1.1+ (recomendado):

npm install api-stats-logger@latest

Usar flags do npm:

npm install api-stats-logger --legacy-peer-deps

Configurar .npmrc:

echo "legacy-peer-deps=true" >> .npmrc
npm install api-stats-logger

Problemas com TypeScript

Se estiver usando TypeScript, instale os tipos:

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

# 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)

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

api-stats-logger

Package Exports

Readme

🚀 API Stats Logger - SDK de Monitoramento

📋 Visão Geral

🚀 Instalação

⚡ Quick Start (REALMENTE 30 segundos!)

1. Setup 100% automático com CLI

🔐 Novo! Autenticação Google OAuth (Recomendado)

2. Uso mais simples possível

3. Suas variáveis já estão prontas!

🎯 Integração por Framework

Express.js

NestJS

Fastify

Koa

🔧 Configuração Avançada

Configuração Completa

Setup para Projetos Existentes

Setup Manual (sem CLI)

🔧 Configuração Google OAuth (Avançado)

📊 Exemplos de Uso

Logging Manual

Logging de Operações

Instrumentação de Banco de Dados

📈 Métricas Automáticas

HTTP Requests

Erros

Performance

Banco de Dados

🔔 Alertas Inteligentes

📊 Dashboard e Visualização

Features do Dashboard:

🛠️ CLI Úteis

🔒 Segurança

Headers Sensíveis (Automaticamente Removidos)

Configuração de Segurança

🚀 Performance

Configurações de Performance

Estatísticas

🔧 Troubleshooting

Verificar Conectividade

Debug Mode

Health Check

🔄 Migração de Outros Sistemas

Do Winston

Do Bunyan

📚 Exemplos Completos

E-commerce API

Microserviço

🤝 Suporte

📄 Licença

✨ Novidades v1.1.1

📦 Uso por Framework

Express (4.x e 5.x)

NestJS

Fastify

Koa

🔧 Configuração Avançada

Variáveis de Ambiente

Opções do Middleware

🔍 Compatibilidade de Versões

🚨 Resolvendo Conflitos de Dependências

Problema: ERESOLVE com Express 5.x

Problemas com TypeScript

📊 Recursos

🏃‍♂️ Início Rápido Completo

📚 Documentação Completa

🆘 Suporte

📄 Licença