api-stats-logger/BACKEND-INTEGRATION.md

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

# 🔧 Integração Back-end - API Stats Logger

## 📋 Para Desenvolvedores Back-end

Esta documentação é destinada a desenvolvedores back-end que precisam integrar o **API Stats Logger** em aplicações existentes ou novas. Aqui você encontrará tudo o que precisa para uma integração perfeita.

---

## 🚀 Início Rápido (5 minutos)

### 1. Instalar e Configurar

```bash
# Instalar o pacote
npm install api-stats-logger

# Configurar automaticamente
npx api-stats-init
```

### 2. Integrar no Código

```javascript
// No topo do seu app principal (ANTES de outros requires)
require('api-stats-logger').init();

// Resto da sua aplicação continua IGUAL
const express = require('express');
// ... resto do código
```

### 3. Verificar Logs

Acesse: [https://apistats.squareweb.app](https://apistats.squareweb.app)

**Pronto!** Logs automáticos para todas as requisições. 🎉

---

## 📊 Especificação do Endpoint de Logs

### URL e Método

```
POST https://apistats.squareweb.app/logs
```

### Headers Obrigatórios

```
Content-Type: application/json
x-api-key: sua-api-key-aqui
```

### Formato do Payload

```javascript
// Array de objetos de log
[
  {
    "timestamp": "2024-05-29T10:30:00.000Z",  // ISO 8601 (obrigatório)
    "level": "info",                          // debug|info|warn|error (obrigatório)
    "message": "Descrição do log",            // string (obrigatório)
    "service": "nome-do-servico",             // string (opcional)
    "environment": "production",              // string (opcional)
    "metadata": {                             // object (opcional)
      "requestId": "req_123",
      "userId": 456,
      "duration": 150,
      // ... qualquer dado adicional
    }
  }
]
```

### ✅ Endpoint Validado

**Status**: ✅ 100% Funcional  
**Bloqueios**: ❌ Nenhum (apenas validação de API key)  
**Performance**: 🚀 < 400ms (média)  
**Rate Limit**: ❌ Nenhum  
**CORS**: ✅ Habilitado  

### Respostas

#### Sucesso (201)
```json
{
  "success": true
}
```

#### Erro de Autenticação (401)
```json
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

#### Erro de Validação (400)
```json
{
  "statusCode": 400,
  "message": "Invalid payload format"
}
```

#### Erro Interno (500)
```json
{
  "statusCode": 500,
  "message": "Internal server error"
}
```

---

## 🔧 Métodos de Integração

### Método 1: Auto-instrumentação (RECOMENDADO)

```javascript
// app.js ou server.js
require('api-stats-logger').init();

// Express, NestJS, Fastify, Koa são detectados automaticamente
const express = require('express');
const app = express();

// Suas rotas funcionam normalmente
app.get('/users', (req, res) => {
  res.json({ users: [] });
  // Log automático: GET /users 200 [45ms]
});
```

### Método 2: Middleware Manual

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

const app = express();
const logger = new ApiStatsLogger();

// Middleware ANTES das rotas
app.use(ApiStatsLogger.expressMiddleware({
  logger,
  captureBody: false,
  captureHeaders: true,
  skipPaths: ['/health', '/metrics']
}));

// Suas rotas
app.get('/users', (req, res) => {
  res.json({ users: [] });
});
```

### Método 3: Logs Manuais

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

app.post('/users', async (req, res) => {
  logger.info('Creating user', { email: req.body.email });
  
  try {
    const user = await createUser(req.body);
    
    logger.info('User created successfully', { 
      userId: user.id,
      email: user.email 
    });
    
    res.status(201).json(user);
  } catch (error) {
    logger.error('Error creating user', { 
      error: error.message,
      email: req.body.email 
    });
    
    res.status(500).json({ error: 'Internal server error' });
  }
});
```

---

## 📦 Frameworks Suportados

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

```javascript
require('api-stats-logger').init(); // Auto-detecta
const express = require('express');
const app = express();

// OU middleware manual
app.use(ApiStatsLogger.expressMiddleware());
```

### NestJS (8.x, 9.x, 10.x)

```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()
  }));
  
  await app.listen(3000);
}
```

### Fastify (3.x, 4.x, 5.x)

```javascript
require('api-stats-logger').init(); // Auto-detecta
const fastify = require('fastify');

// OU manual com hooks
fastify.addHook('onRequest', ApiStatsLogger.fastifyHook);
```

### Koa (2.x+)

```javascript
require('api-stats-logger').init(); // Auto-detecta
const Koa = require('koa');

// OU middleware manual
app.use(ApiStatsLogger.koaMiddleware());
```

### Outros Frameworks

```javascript
// Para qualquer framework HTTP
const logger = new ApiStatsLogger();

// Em cada requisição
function handleRequest(req, res) {
  const startTime = Date.now();
  
  logger.info('Request started', {
    method: req.method,
    url: req.url,
    ip: req.ip
  });
  
  // ... sua lógica
  
  const duration = Date.now() - startTime;
  logger.info(`${req.method} ${req.url} ${res.statusCode}`, {
    duration,
    statusCode: res.statusCode
  });
}
```

---

## ⚙️ Configuração Avançada

### Variáveis de Ambiente

```env
# Obrigatórias (geradas automaticamente pela CLI)
API_STATS_API_KEY=ak_1234567890abcdef...
API_STATS_URL=https://apistats.squareweb.app/logs
API_STATS_SERVICE=minha-api-backend
API_STATS_ENVIRONMENT=production

# Opcionais (performance)
API_STATS_BATCH_SIZE=10          # Logs por batch
API_STATS_FLUSH_INTERVAL=2000    # ms entre envios
API_STATS_MAX_RETRIES=3          # Tentativas em caso de erro

# Opcionais (captura)
API_STATS_CAPTURE_BODY=false     # Capturar request/response body
API_STATS_CAPTURE_HEADERS=true   # Capturar headers
API_STATS_ENABLED=true           # Habilitar/desabilitar
```

### Configuração Programática

```javascript
const logger = new ApiStatsLogger({
  // Básico
  apiKey: process.env.API_STATS_API_KEY,
  service: 'minha-api',
  environment: 'production',
  
  // Performance
  batchSize: 20,        // Mais logs por batch = menos requisições
  flushInterval: 5000,  // Intervalo maior = menos frequente
  maxRetries: 2,        // Menos tentativas = mais rápido em caso de erro
  
  // Segurança
  captureBody: false,          // Não capturar bodies por padrão
  captureHeaders: false,       // Não capturar headers sensíveis
  sensitiveHeaders: [          // Headers que nunca serão capturados
    'authorization',
    'cookie',
    'x-api-key'
  ],
  
  // Filtros
  skipPaths: ['/health', '/metrics', '/favicon.ico'],
  skipMethods: ['OPTIONS'],
  
  // Debug
  debug: process.env.NODE_ENV === 'development'
});
```

---

## 📊 Tipos de Logs e Métricas

### Logs Automáticos de Requisição

```javascript
// Capturado automaticamente para cada requisição HTTP
{
  "timestamp": "2024-05-29T10:30:00.000Z",
  "level": "info",
  "message": "POST /api/users 201",
  "service": "api-backend",
  "environment": "production",
  "metadata": {
    "requestId": "req_1717055400000_abc123",
    "method": "POST",
    "url": "/api/users",
    "statusCode": 201,
    "duration": 150,
    "ip": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "contentLength": 342,
    "framework": "express"
  }
}
```

### Logs de Erro Automáticos

```javascript
// Capturado automaticamente quando há erros
{
  "timestamp": "2024-05-29T10:30:00.000Z",
  "level": "error",
  "message": "POST /api/users 500",
  "service": "api-backend",
  "environment": "production",
  "metadata": {
    "requestId": "req_1717055400000_def456", 
    "method": "POST",
    "url": "/api/users",
    "statusCode": 500,
    "duration": 75,
    "error": "Database connection timeout",
    "stack": "Error: Database connection timeout\n    at..."
  }
}
```

### Logs de Negócio Manuais

```javascript
// Logs específicos da sua aplicação
logger.info('User authentication successful', {
  userId: 123,
  email: 'user@example.com',
  loginMethod: 'oauth2',
  provider: 'google',
  location: 'São Paulo, BR'
});

logger.warn('Slow database query detected', {
  query: 'SELECT * FROM users WHERE active = true',
  duration: 2500,
  threshold: 1000,
  table: 'users',
  rowsReturned: 15000
});

logger.error('Payment processing failed', {
  paymentId: 'pay_123456',
  userId: 789,
  amount: 99.90,
  currency: 'BRL',
  provider: 'stripe',
  error: 'Card declined',
  errorCode: 'card_declined'
});
```

### Métricas de Performance

```javascript
// Monitoramento de operações críticas
async function processPayment(paymentData) {
  const operationId = `payment_${Date.now()}`;
  const startTime = Date.now();
  
  logger.info('Payment processing started', {
    operationId,
    userId: paymentData.userId,
    amount: paymentData.amount,
    method: paymentData.method
  });
  
  try {
    // Operação principal
    const result = await paymentGateway.charge(paymentData);
    const duration = Date.now() - startTime;
    
    // Log de sucesso
    logger.info('Payment processed successfully', {
      operationId,
      paymentId: result.id,
      duration,
      status: result.status,
      transactionId: result.transactionId
    });
    
    return result;
  } catch (error) {
    const duration = Date.now() - startTime;
    
    // Log de erro
    logger.error('Payment processing failed', {
      operationId,
      duration,
      error: error.message,
      errorCode: error.code,
      amount: paymentData.amount
    });
    
    throw error;
  }
}
```

---

## 🔍 Verificação e Teste

### 1. Teste de Conectividade

```bash
# Testar endpoint diretamente
node test-endpoint.js
```

### 2. Teste Manual com curl

```bash
curl -X POST https://apistats.squareweb.app/logs \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key-aqui" \
  -d '[{
    "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)'",
    "level": "info",
    "message": "Teste manual",
    "service": "teste",
    "environment": "development"
  }]'
```

### 3. Debug no Código

```javascript
// Habilitar debug
const logger = new ApiStatsLogger({ 
  debug: true 
});

// Ver logs de envio
logger.info('Teste de log');
// Output: "Sending 1 logs to API Stats..."
```

### 4. Verificar no Dashboard

1. Acesse: https://apistats.squareweb.app
2. Faça login com suas credenciais
3. Selecione seu projeto
4. Verifique se os logs estão aparecendo

---

## 🚨 Solução de Problemas

### Problema: "API key inválida"

```bash
# Verificar API key
echo $API_STATS_API_KEY

# Regenerar se necessário
npx api-stats-init
```

### Problema: "Logs não aparecem"

1. **Verificar conectividade**:
   ```bash
   node test-endpoint.js
   ```

2. **Verificar configuração**:
   ```javascript
   const logger = new ApiStatsLogger({ debug: true });
   logger.info('Teste');
   // Deve mostrar logs de debug
   ```

3. **Verificar variáveis de ambiente**:
   ```bash
   env | grep API_STATS
   ```

### Problema: "Performance degradada"

```javascript
// Otimizar configurações
const logger = new ApiStatsLogger({
  batchSize: 50,        // Menos requisições
  flushInterval: 10000, // Menos frequente
  maxRetries: 1,        // Falha mais rápido
  captureBody: false,   // Menos dados
  captureHeaders: false // Menos dados
});
```

### Problema: "Muitos logs"

```javascript
// Filtrar logs desnecessários
const logger = new ApiStatsLogger({
  skipPaths: [
    '/health',
    '/metrics', 
    '/favicon.ico',
    '/static/*',
    '/_next/*'
  ],
  skipMethods: ['OPTIONS', 'HEAD']
});

// Ou desabilitar completamente em desenvolvimento
const logger = new ApiStatsLogger({
  enabled: process.env.NODE_ENV === 'production'
});
```

---

## 📈 Boas Práticas

### 1. Configuração por Ambiente

```javascript
// config/logging.js
const getLoggingConfig = () => {
  const baseConfig = {
    apiKey: process.env.API_STATS_API_KEY,
    service: process.env.API_STATS_SERVICE
  };

  switch (process.env.NODE_ENV) {
    case 'development':
      return {
        ...baseConfig,
        environment: 'development',
        captureBody: true,
        captureHeaders: true,
        debug: true
      };
      
    case 'staging':
      return {
        ...baseConfig,
        environment: 'staging',
        captureBody: false,
        captureHeaders: true,
        batchSize: 10
      };
      
    case 'production':
      return {
        ...baseConfig,
        environment: 'production',
        captureBody: false,
        captureHeaders: false,
        batchSize: 50,
        flushInterval: 5000
      };
      
    default:
      return {
        ...baseConfig,
        enabled: false
      };
  }
};

module.exports = { getLoggingConfig };
```

### 2. Logs Estruturados

```javascript
// helpers/logger.js
const ApiStatsLogger = require('api-stats-logger');
const logger = new ApiStatsLogger();

class AppLogger {
  // Operações de usuário
  static userAction(action, userId, metadata = {}) {
    logger.info(`User ${action}`, {
      category: 'user',
      action,
      userId,
      ...metadata
    });
  }

  // Operações de sistema
  static systemEvent(event, metadata = {}) {
    logger.info(`System ${event}`, {
      category: 'system',
      event,
      ...metadata
    });
  }

  // Erros de negócio
  static businessError(operation, error, metadata = {}) {
    logger.error(`Business error in ${operation}`, {
      category: 'business',
      operation,
      error: error.message,
      ...metadata
    });
  }

  // Performance
  static performance(operation, duration, metadata = {}) {
    const level = duration > 1000 ? 'warn' : 'info';
    logger.log({
      level,
      message: `Performance: ${operation} took ${duration}ms`,
      metadata: {
        category: 'performance',
        operation,
        duration,
        ...metadata
      }
    });
  }
}

module.exports = AppLogger;
```

### 3. Uso nos Controllers

```javascript
// controllers/userController.js
const AppLogger = require('../helpers/logger');

class UserController {
  async createUser(req, res) {
    const startTime = Date.now();
    
    try {
      AppLogger.userAction('create_attempt', null, {
        email: req.body.email,
        ip: req.ip
      });

      const user = await userService.create(req.body);
      const duration = Date.now() - startTime;

      AppLogger.userAction('create_success', user.id, {
        email: user.email,
        duration
      });

      AppLogger.performance('user_creation', duration, {
        userId: user.id
      });

      res.status(201).json(user);
    } catch (error) {
      const duration = Date.now() - startTime;

      AppLogger.businessError('user_creation', error, {
        email: req.body.email,
        duration
      });

      res.status(500).json({ error: 'Internal server error' });
    }
  }
}
```

---

## 📚 Recursos Adicionais

### Scripts Úteis

```json
{
  "scripts": {
    "logs:test": "node test-endpoint.js",
    "logs:setup": "npx api-stats-init",
    "logs:check": "node -e \"const l = require('api-stats-logger'); new l().testConnection().then(console.log)\""
  }
}
```

### Monitoramento

```javascript
// health-check.js
const ApiStatsLogger = require('api-stats-logger');

async function checkLoggingHealth() {
  try {
    const logger = new ApiStatsLogger();
    await logger.testConnection();
    
    console.log('✅ API Stats Logger: OK');
    return true;
  } catch (error) {
    console.log('❌ API Stats Logger: ERROR', error.message);
    return false;
  }
}

module.exports = { checkLoggingHealth };
```

### Documentação

- **README.md** - Visão geral e exemplos básicos
- **INSTALLATION-GUIDE.md** - Guia detalhado de instalação
- **TROUBLESHOOTING.md** - Soluções para problemas comuns
- **CHANGELOG.md** - Histórico de versões

### Suporte

- 📧 **Email**: dev@grupoloyalty.com.br
- 🌐 **API**: https://apistats.squareweb.app
- 📚 **GitHub**: https://github.com/grupo-loyalty/api-stats-logger

---

**✅ Integração Completa!**

Com esta documentação, você tem tudo o que precisa para integrar o API Stats Logger em qualquer aplicação back-end. O endpoint está 100% funcional e não possui bloqueios além da validação de API key.

Para dúvidas específicas ou suporte técnico, use os recursos de suporte listados acima.