@nicollasfrazao/liguelead-log-service 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, LigueLead
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,689 @@
+# Log Service Node.js
+
+Este é um **serviço de logging standalone** para aplicações Express com armazenamento multi-destino (arquivos locais + S3 via Kinesis Firehose) e rastreamento abrangente de requisições. O serviço utiliza o **padrão strategy** com classes base abstratas para destinos de armazenamento.
+
+## Instalação
+
+```bash
+npm install @ligue-lead-tech/log-service-nodejs
+```
+
+## Uso Rápido
+
+### 1. Configuração Básica
+
+```typescript
+import express from 'express';
+import { LogService, loggingMiddleware } from '@ligue-lead-tech/log-service-nodejs';
+
+const app = express();
+
+// Configure as variáveis de ambiente
+process.env.LOG_USE = 'true';
+process.env.LOG_LEVEL = 'info';
+process.env.LOG_DESTINATION = 'both'; // 'console', 'storage', ou 'both'
+process.env.NODE_ENV = 'development';
+
+// Adicione o middleware de logging (obrigatório para correlation IDs)
+app.use(loggingMiddleware);
+
+// Suas rotas
+app.get('/api/users', (req, res) => {
+  // O middleware já loga automaticamente requisições e respostas
+  
+  // Logging manual com contexto da requisição
+  const context = LogService.createContextFromRequest(req);
+  LogService.info('Buscando usuários', context);
+  
+  res.json({ users: [] });
+});
+
+app.listen(3000, () => {
+  LogService.info('Servidor iniciado', { 
+    method: 'SYSTEM', 
+    url: 'localhost:3000', 
+    ip: '127.0.0.1' 
+  });
+});
+```
+
+### 2. Configuração com S3 via Kinesis Firehose
+
+```typescript
+// Configuração para produção com S3
+process.env.LOG_USE_S3_STORAGE = 'true';
+process.env.LOG_FIREHOSE_STREAM_NAME = 'my-app-logs-firehose';
+process.env.LOG_AWS_REGION = 'us-east-1';
+
+// Para desenvolvimento com LocalStack
+process.env.LOG_AWS_ENDPOINT = 'http://localhost:4566';
+process.env.LOG_AWS_ACCESS_KEY_ID = 'test';
+process.env.LOG_AWS_SECRET_ACCESS_KEY = 'test';
+```
+
+### 3. Logging Manual
+
+```typescript
+import { LogService, LogError } from '@ligue-lead-tech/log-service-nodejs';
+
+// Logging simples
+LogService.info('Operação realizada', { 
+  method: 'POST', 
+  url: '/api/users', 
+  ip: '192.168.1.1' 
+});
+
+LogService.error('Erro na operação', { 
+  method: 'POST', 
+  url: '/api/users', 
+  ip: '192.168.1.1',
+  error: 'Database connection failed' 
+});
+
+// Erro customizado que loga automaticamente
+throw new LogError('Usuário não encontrado', 404, { userId: 123 });
+```
+
+### 4. Logging de APIs Externas
+
+```typescript
+import { LogService } from '@ligue-lead-tech/log-service-nodejs';
+import axios from 'axios';
+
+app.post('/api/process', async (req, res) => {
+  try {
+    // Loga automaticamente request/response da API externa
+    const response = await LogService.executeRequestWithLogging(
+      req,                                    // Request Express (para correlation)
+      () => axios.post('https://api.external.com/data', { data: 'test' }),
+      'POST', 'https://api.external.com/data', { data: 'test' }
+    );
+    
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to process' });
+  }
+});
+```
+
+## Características Principais
+
+- ✅ **Logging automático** de todas as requisições HTTP
+- ✅ **Correlation ID único** para rastreamento de requisições
+- ✅ **Medição de tempo de resposta**
+- ✅ **Sanitização automática** de dados sensíveis
+- ✅ **Logging estruturado** em formato JSON
+- ✅ **Configuração por ambiente** (development, homologation, production, test)
+- ✅ **Diferentes níveis de log** (debug, info, warn, error)
+- ✅ **Armazenamento via Kinesis Firehose** para S3 com buffering e compressão
+- ✅ **Fallback para armazenamento local** em caso de falha do S3
+- ✅ **Padrão de serviço estático** - sem necessidade de instanciação
+
+## Estrutura dos Arquivos de Log
+
+Os logs são organizados por ambiente e salvos via **Kinesis Firehose** para S3, com fallback para arquivos locais:
+
+### Armazenamento S3 (via Kinesis Firehose)
+```
+ll-api-logs/
+├── logs/
+│   ├── development/
+│   │   └── 2025-10-27-combined.log.gz     # Logs comprimidos pelo Firehose
+│   ├── production/
+│   │   └── 2025-10-27-combined.log.gz
+│   ├── homologation/
+│   │   └── 2025-10-27-combined.log.gz
+│   └── test/
+│       └── 2025-10-27-combined.log.gz
+```
+
+### Armazenamento Local (Fallback)
+```
+src/storage/logs/
+├── development/                     # Ambiente de desenvolvimento
+│   └── 2025-10-27-combined.log     # Todos os logs do dia específico
+├── production/                      # Ambiente de produção
+│   └── 2025-10-27-combined.log
+├── homologation/                    # Ambiente de homologação
+│   └── 2025-10-27-combined.log
+└── test/                           # Ambiente de testes
+    └── 2025-10-27-combined.log
+```
+
+## Destinos de Log
+
+O sistema suporta diferentes destinos para os logs através da variável `LOG_DESTINATION`:
+
+### 1. Storage (`LOG_DESTINATION="storage"`)
+- Logs são salvos apenas em arquivos locais ou S3
+- Não aparecem no console da aplicação
+- Ideal para produção onde você não quer poluir os logs do Lambda/container
+
+### 2. Console (`LOG_DESTINATION="console"`)
+- Logs aparecem apenas no console da aplicação
+- Não são salvos em arquivos ou S3
+- Útil para desenvolvimento local ou debugging
+
+### 3. Both (`LOG_DESTINATION="both"`)
+- Logs são salvos em arquivos/S3 E aparecem no console
+- Máxima visibilidade e persistência
+- Útil para ambientes de homologação
+
+### Armazenamento S3 via Kinesis Firehose
+
+Quando `LOG_USE_S3_STORAGE=true`, os logs são enviados para **Kinesis Firehose** que faz a entrega otimizada para S3:
+
+- **Firehose Stream**: Definido por `LOG_FIREHOSE_STREAM_NAME`
+- **Bucket S3**: Configurado no Firehose Stream
+- **Estrutura**: `logs/{prefix}/` (definido na configuração do Firehose)
+- **Buffering**: Firehose agrupa logs em batches para eficiência
+- **Compressão**: Logs são automaticamente comprimidos (GZIP)
+- **Endpoint**: Configurável via `LOG_AWS_ENDPOINT` (útil para LocalStack)
+- **Credenciais**: Via variáveis de ambiente AWS ou perfis IAM
+
+Exemplo de estrutura no S3 via Firehose:
+```
+ll-api-logs/
+├── logs/
+│   ├── 2025/10/27/14/
+│   │   ├── firehose_output-1-2025-10-27-14-01-01-uuid.gz
+│   │   └── firehose_output-2-2025-10-27-14-02-01-uuid.gz
+│   └── error-logs/                  # Logs com erro de entrega
+│       └── processing-failed/
+```
+
+## Configuração
+
+### Variáveis de Ambiente
+
+O serviço é configurado através de variáveis de ambiente. Aqui estão as principais:
+
+#### Configurações Essenciais
+```bash
+# Controle principal
+LOG_USE=true                           # Ativa/desativa o sistema de logging
+LOG_LEVEL=info                         # debug|info|warn|error
+LOG_DESTINATION=both                   # storage|console|both
+NODE_ENV=development                   # development|production|homologation|test
+
+# S3 via Kinesis Firehose
+LOG_USE_S3_STORAGE=true               # Ativa envio para S3 via Firehose
+LOG_FIREHOSE_STREAM_NAME=my-app-logs  # Nome do stream Kinesis Firehose
+
+# AWS (apenas para desenvolvimento/LocalStack)
+LOG_AWS_ENDPOINT=http://localhost:4566  # Endpoint AWS (LocalStack)
+LOG_AWS_REGION=us-east-1                # Região AWS
+LOG_AWS_ACCESS_KEY_ID=test              # Access Key (dev only)
+LOG_AWS_SECRET_ACCESS_KEY=test          # Secret Key (dev only)
+
+# Controle de conteúdo
+LOG_INCLUDE_REQUEST_BODY=true          # Inclui corpo da requisição
+LOG_INCLUDE_RESPONSE_BODY=true         # Inclui corpo da resposta
+LOG_MAX_BODY_SIZE=5000                 # Tamanho máximo dos corpos (bytes)
+```
+
+#### Configuração para Diferentes Ambientes
+
+**Desenvolvimento Local:**
+```bash
+LOG_USE=true
+LOG_LEVEL=debug
+LOG_DESTINATION=both
+LOG_USE_S3_STORAGE=false
+```
+
+**Produção:**
+```bash
+LOG_USE=true
+LOG_LEVEL=info
+LOG_DESTINATION=storage
+LOG_USE_S3_STORAGE=true
+LOG_FIREHOSE_STREAM_NAME=production-logs-firehose
+```
+
+**Desenvolvimento com LocalStack:**
+```bash
+LOG_USE=true
+LOG_LEVEL=debug
+LOG_DESTINATION=both
+LOG_USE_S3_STORAGE=true
+LOG_AWS_ENDPOINT=http://localhost:4566
+LOG_FIREHOSE_STREAM_NAME=dev-logs-firehose
+LOG_AWS_ACCESS_KEY_ID=test
+LOG_AWS_SECRET_ACCESS_KEY=test
+```
+
+### Configuração Programática
+
+Você também pode configurar o serviço programaticamente:
+
+```typescript
+import { LogService } from '@ligue-lead-tech/log-service-nodejs';
+
+// Configurar correlation ID personalizado
+LogService.setCorrelationId('custom-correlation-id');
+
+// Criar contexto personalizado
+const customContext = {
+  method: 'POST',
+  url: '/api/custom',
+  ip: '192.168.1.1',
+  user_id: 'user123',
+  custom_field: 'custom_value'
+};
+
+LogService.info('Mensagem personalizada', customContext);
+```
+
+### Configurações Avançadas
+
+O sistema usa as configurações definidas em `src/configs/log.service.config.ts`. As principais opções incluem:
+
+- `includeRequestBody`: Para incluir o corpo da requisição nos logs
+- `includeResponseBody`: Para incluir o corpo da resposta nos logs
+- `includeRequestHeaders`: Para incluir headers da requisição
+- `sensitiveFields`: Lista de campos sensíveis que serão mascarados
+- `maxBodySize`: Tamanho máximo do corpo da requisição/resposta a ser logado
+- `logExternalRequestCalls`: Para logging de chamadas para APIs externas
+
+### Variáveis de Ambiente
+
+```bash
+# ===== CONFIGURAÇÕES PRINCIPAIS =====
+
+# Habilita/desabilita logging completamente
+LOG_USE=true
+
+# Nível de logging (debug|info|warn|error)
+LOG_LEVEL=info
+
+# Nome do serviço (aparece nos logs)
+LOG_SERVICE_NAME=my-service
+
+# Prefixo para mensagens de log
+LOG_PREFIX=[MY-APP]
+
+# ===== CONFIGURAÇÕES DE CONTEÚDO =====
+
+# Incluir corpo das requisições nos logs
+LOG_INCLUDE_REQUEST_BODY=true
+
+# Incluir corpo das respostas nos logs
+LOG_INCLUDE_RESPONSE_BODY=true
+
+# Incluir headers das requisições
+LOG_INCLUDE_REQUEST_HEADERS=true
+
+# Tamanho máximo do corpo para logging (bytes)
+LOG_MAX_BODY_SIZE=5000
+
+# Logging de chamadas para APIs externas
+LOG_EXTERNAL_REQUEST_CALLS=true
+
+# ===== CONFIGURAÇÕES DE DESTINO DOS LOGS =====
+
+# Destino dos logs (storage|console|both)
+# - storage: salva apenas em arquivos/S3
+# - console: exibe apenas no console
+# - both: salva em arquivos/S3 e exibe no console
+LOG_DESTINATION=storage
+
+# ===== CONFIGURAÇÕES DE ARMAZENAMENTO S3 VIA KINESIS FIREHOSE =====
+
+# Habilita armazenamento no S3 via Kinesis Firehose (true|false)
+LOG_USE_S3_STORAGE=true
+
+# Nome do Kinesis Firehose stream
+LOG_FIREHOSE_STREAM_NAME=ll-api-logs-firehose
+
+# Região AWS
+LOG_AWS_REGION=us-east-1
+
+# Endpoint do S3/Firehose (para LocalStack)
+LOG_AWS_ENDPOINT=http://localhost:4566
+
+# Credenciais AWS (se não usando perfil/role)
+LOG_AWS_ACCESS_KEY_ID=test
+LOG_AWS_SECRET_ACCESS_KEY=test
+```
+
+### Configurações por Ambiente
+
+O sistema detecta automaticamente o ambiente atual através da variável `NODE_ENV`:
+
+- `NODE_ENV=development` → logs salvos em `logs/development/`
+- `NODE_ENV=production` → logs salvos em `logs/production/`
+- `NODE_ENV=homologation` → logs salvos em `logs/homologation/`
+- `NODE_ENV=test` → logs salvos em `logs/test/`
+- Sem `NODE_ENV` definido → logs salvos em `logs/development/` (padrão)
+
+- **Development**: Logs completos com cores
+- **Homologation**: Logs limitados sem cores
+- **Production**: Apenas warnings/errors, dados mínimos
+- **Test**: Apenas errors, logging mínimo
+
+### Exemplos de Configuração por Ambiente
+
+#### Desenvolvimento Local (com LocalStack)
+```bash
+NODE_ENV=development
+LOG_USE=true
+LOG_LEVEL=debug
+LOG_DESTINATION=both
+LOG_USE_S3_STORAGE=true
+LOG_FIREHOSE_STREAM_NAME=ll-api-logs-firehose
+LOG_AWS_ENDPOINT=http://localhost:4566
+LOG_AWS_ACCESS_KEY_ID=test
+LOG_AWS_SECRET_ACCESS_KEY=test
+```
+
+#### Homologação
+```bash
+NODE_ENV=homologation
+LOG_USE=true
+LOG_LEVEL=info
+LOG_DESTINATION=storage
+LOG_USE_S3_STORAGE=true
+LOG_FIREHOSE_STREAM_NAME=ll-api-logs-firehose-hml
+# AWS credentials via IAM role ou environment variables
+```
+
+#### Produção
+```bash
+NODE_ENV=production
+LOG_USE=true
+LOG_LEVEL=warn
+LOG_DESTINATION=storage
+LOG_USE_S3_STORAGE=true
+LOG_FIREHOSE_STREAM_NAME=ll-api-logs-firehose-prod
+LOG_INCLUDE_REQUEST_BODY=false
+LOG_INCLUDE_RESPONSE_BODY=false
+LOG_MAX_BODY_SIZE=1000
+# AWS credentials via IAM role
+```
+
+## Estrutura dos Logs
+
+### Log de Requisição
+```json
+{
+  "timestamp": "2025-10-27T10:30:00.000Z",
+  "level": "info",
+  "environment": "development",
+  "service": "log-service",
+  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "[MY-APP] Incoming request",
+  "context": {
+    "method": "POST",
+    "url": "/v1/voice/send",
+    "userAgent": "PostmanRuntime/7.32.3",
+    "ip": "192.168.1.100",
+    "headers": {
+      "content-type": "application/json",
+      "authorization": "[REDACTED]"
+    },
+    "requestBody": {
+      "title": "Test Voice Message",
+      "voice_upload_id": 123,
+      "phones": ["[REDACTED]", "[REDACTED]"]
+    }
+  }
+}
+```
+
+### Log de Resposta
+```json
+{
+  "timestamp": "2025-10-27T10:30:01.500Z",
+  "level": "info",
+  "environment": "development",
+  "service": "log-service",
+  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "[MY-APP] Request completed successfully",
+  "context": {
+    "method": "POST",
+    "url": "/v1/voice/send",
+    "statusCode": 200,
+    "responseTime": 1500,
+    "responseBody": {
+      "message": "Voice sent successfully",
+      "data": {
+        "campaign_id": "12345"
+      }
+    }
+  }
+}
+```
+
+## Como Usar
+
+### 1. Instalação
+```bash
+npm install
+```
+
+### 2. Dependências
+```json
+{
+  "dependencies": {
+    "@types/express": "^5.0.4",
+    "@aws-sdk/client-s3": "^3.658.1",
+    "@aws-sdk/client-firehose": "^3.658.1", 
+    "express": "^5.1.0",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/dotenv": "^8.2.3",
+    "@types/uuid": "^9.0.8",
+    "dotenv": "^17.2.3"
+  }
+}
+```
+
+### 3. Estrutura do Projeto
+```
+src/
+├── configs/                         # Configurações
+│   ├── log.service.config.ts
+│   └── log.storage.external.s3.config.ts
+├── errors/                          # Erros customizados
+│   └── log.error.ts
+├── interfaces/                      # Interfaces TypeScript
+│   ├── log.service.config.interface.ts
+│   ├── log.storage.base.service.interface.ts
+│   └── log.storage.external.s3.service.config.interface.ts
+├── middlewares/                     # Middlewares Express
+│   └── log.middleware.ts
+├── services/                        # Serviços principais
+│   ├── log.service.ts               # Serviço principal (estático)
+│   ├── log.storage.base.service.ts  # Classe base abstrata
+│   ├── log.storage.local.service.ts # Armazenamento local
+│   ├── log.storage.external.s3.service.ts # Armazenamento S3 via Firehose
+│   ├── log.storage.external.service.ts
+│   └── log.storage.service.ts       # Orquestrador de storage
+├── storage/                         # Diretório de logs locais
+│   └── logs/
+│       └── development/             # Logs por ambiente
+└── types/                          # Tipos TypeScript
+    ├── log.context.type.ts
+    └── log.type.ts
+scripts/                             # Scripts utilitários
+└── setup-localstack-firehose.sh    # Configuração LocalStack
+```
+
+### 4. Middleware de Logging Automático
+O middleware de logging é aplicado automaticamente a todas as rotas:
+
+```typescript
+import { loggingMiddleware } from './src/middlewares/log.middleware';
+
+app.use(loggingMiddleware);
+```
+
+### 5. Logging Manual
+```typescript
+import { LogService } from './src/services/log.service';
+
+// Métodos estáticos - sem necessidade de instanciação
+LogService.info("Operação realizada", context);
+LogService.warn("Aviso importante", { data: someData });
+LogService.error("Erro ocorreu", { error: err.message, ...context });
+LogService.debug("Informação de debug", { debugData: details });
+
+// Criar contexto a partir da requisição Express
+const context = LogService.createContextFromRequest(req);
+LogService.info("Operação customizada", context);
+```
+
+### 6. Logging de Requisições Externas
+```typescript
+// Use executeRequestWithLogging para chamadas externas
+const response = await LogService.executeRequestWithLogging<T>(
+  req,
+  () => axios.post(externalApiUrl, data),
+  'POST',
+  externalApiUrl,
+  data
+);
+```
+
+## Campos Sanitizados
+
+Os seguintes campos são automaticamente mascarados nos logs:
+- `password` / `senha`
+- `token` / `access_token` / `refresh_token`
+- `authorization`
+- `credit_card` / `creditCard`
+- `cpf` / `cnpj`
+- `phone` / `phones` / `telefone` / `numbers` / `number`
+- `email`
+- `api_key`
+- `secret`
+- `private_key`
+
+A sanitização é aplicada recursivamente a objetos aninhados com proteção contra referências circulares.
+
+
+## Análise de Performance
+
+Os logs incluem métricas importantes para análise:
+- **responseTime**: Tempo total da requisição
+- **statusCode**: Código de status HTTP
+- **method**: Método HTTP utilizado
+- **url**: Endpoint acessado
+
+## Monitoramento
+
+### Logs Importantes para Alertas
+1. **Errors (level: error)**: Problemas críticos
+2. **Alta latência (responseTime > 5000ms)**: Performance
+3. **Status codes 5xx**: Errors do servidor
+4. **Status codes 4xx**: Errors do cliente
+5. **Falhas do Firehose**: Logs que falharam na entrega para S3
+
+### Métricas Recomendadas
+- Taxa de requisições por minuto
+- Tempo médio de resposta
+- Taxa de errors por endpoint
+- Distribuição de status codes
+- Sucesso/falha de entrega do Firehose
+- Tamanho dos batches enviados ao S3
+
+### Monitoramento AWS
+- **CloudWatch Logs**: Monitore os logs do Firehose para detectar falhas
+- **CloudWatch Metrics**: 
+  - `DeliveryToS3.Records` - registros entregues com sucesso
+  - `DeliveryToS3.Success` - entregas bem-sucedidas  
+  - `DeliveryToS3.DataFreshness` - latência da entrega
+- **S3 Bucket Metrics**: Monitore o crescimento e padrões dos logs
+
+## Arquitetura
+
+### Componentes Principais
+
+- **LogService**: Serviço principal estático - ponto de entrada para todas as operações de logging
+- **LogStorageService**: Orquestra múltiplos destinos de armazenamento (local + S3 via Firehose)
+- **Padrão Strategy**: `LogStorageBaseService` → `LogStorageLocalService` + `LogStorageExternalS3Service`
+- **Middleware**: Auto-logging de requisições/respostas HTTP com correlation IDs
+- **Kinesis Firehose Integration**: Entrega otimizada para S3 com buffering, compressão e retry automático
+
+### Decisões Arquiteturais Críticas
+
+1. **Padrão de Serviço Estático**: `LogService` é inteiramente estático - sem necessidade de instanciação
+2. **Escritas baseadas em Queue**: Usa Map de Promises `writeQueue` para prevenir escritas concorrentes no Firehose
+3. **Organização baseada em Ambiente**: `logs/{environment}/{date}-combined.log`
+4. **Kinesis Firehose**: Logs enviados via Firehose com fallback para armazenamento local
+5. **Rastreamento por Correlation ID**: Correlação baseada em UUID através de todas as entradas de log
+6. **Buffering Inteligente**: Firehose agrupa logs para otimizar entregas ao S3
+
+## Exemplo de Implementação
+
+Para integrar o serviço em sua aplicação Express:
+
+```typescript
+import express from 'express';
+import { loggingMiddleware } from './src/middlewares/log.middleware';
+import { LogService } from './src/services/log.service';
+
+const app = express();
+
+// Aplicar middleware de logging
+app.use(loggingMiddleware);
+
+// Exemplo de uso manual
+app.get('/health', (req, res) => {
+  const context = LogService.createContextFromRequest(req);
+  LogService.info('Health check realizado', context);
+  
+  res.json({ status: 'OK' });
+});
+
+app.listen(3000, () => {
+  LogService.info('Servidor iniciado', { 
+    method: 'GET', 
+    url: '/startup', 
+    ip: '127.0.0.1', 
+    port: 3000 
+  });
+});
+```
+
+## Troubleshooting
+
+### Performance
+- Ajuste `LOG_MAX_BODY_SIZE` para reduzir tamanho dos logs
+- Use `LOG_LEVEL=warn` em produção para reduzir volume
+- Desabilite logging de bodies em produção se necessário
+
+### Armazenamento
+- Configure rotação de logs no ambiente de produção
+- Use ferramentas como ELK Stack ou CloudWatch para centralização
+- Considere usar async logging para alta performance
+
+### Debugging
+- Use `LOG_LEVEL=debug` temporariamente para investigação
+- Ative `LOG_INCLUDE_REQUEST_BODY=true` para debug de payloads
+- Use o `requestId` para rastrear requisições específicas
+
+### Destinos de Log
+- **Logs não aparecem**: Verifique `LOG_DESTINATION` e certifique-se que não está apenas em `storage`
+- **Kinesis Firehose não funciona**: Verifique credenciais AWS, se o stream existe e se `LOG_USE_S3_STORAGE=true`
+- **LocalStack**: 
+  - Execute o script `./scripts/setup-localstack-firehose.sh` primeiro
+  - Certifique-se que `LOG_AWS_ENDPOINT=http://localhost:4566` está configurado
+  - Verifique se o LocalStack está rodando na porta 4566
+- **Performance**: Use `LOG_DESTINATION=storage` para evitar latência do console
+
+### Kinesis Firehose
+- **Stream não existe**: Execute o script de configuração do LocalStack ou crie manualmente na AWS
+- **Logs não chegam no S3**: Firehose tem buffering - aguarde ou reduza o `IntervalInSeconds`
+- **Falha na entrega**: Logs automaticamente fazem fallback para armazenamento local
+- **Monitoramento**: Verifique CloudWatch Logs do Firehose para erros de entrega
+
+### Erros Comuns
+- **Serviço não instancia**: `LogService` é estático - use `LogService.info()` diretamente
+- **Correlation ID perdido**: Certifique-se que o middleware está aplicado antes das rotas
+- **Dados sensíveis expostos**: Verifique se os campos estão na lista `sensitiveFields`
+- **Firehose PutRecord falha**: Verifique credenciais AWS e se o stream existe
+- **Logs duplicados**: Não instancie `LogService` - ele é estático
+- **Queue de escrita**: Não modifique `writeQueue` diretamente - use os métodos do serviço

package/dist/configs/log.service.config.d.ts

@@ -0,0 +1,8 @@
+import { LogServiceConfigInterface } from "../interfaces/log.service.config.interface";
+/**
+ * Get logging configuration
+ *
+ * @returns {LogServiceConfigInterface}
+ */
+export declare const getLogServiceConfig: () => LogServiceConfigInterface;
+//# sourceMappingURL=log.service.config.d.ts.map