azify-logger/README.md

Azify Logger Client - Centralized logging for OpenSearch

# 🚀 Azify Logger - Logging Centralizado

Sistema de logging centralizado com OpenTelemetry e OpenSearch para múltiplas aplicações.

## 🔌 Integração Rápida

### URLs para configurar nas aplicações:

| Ambiente | URL                                                   |
|----------|-------------------------------------------------------|
| **Development** | `http://localhost:3001/log`                           |
| **Staging** | `https://logsdashboard.azify.dev/send`                |
| **Production** | `https://logsdashboard.azify.prd/send` (a configurar) |


### URLs para acessar os logs e dashs:

| Ambiente | URL                                              |
|----------|--------------------------------------------------|
| **Development** | `http://localhost:5601`                          |
| **Staging** | `https://logsdashboard.azify.dev`                |
| **Production** | `https://logsdashboard.azify.com` (a configurar) |


## 📦 Instalação

Na sua aplicação, adicione ao `package.json`:

```json
{
  "dependencies": {
    "azify-logger": "latest"
  }
}
```

Ou via npm:

```bash
npm install azify-logger
```

## ⚡ Utilização

### Para aplicações Restify:

**1. No arquivo de inicialização:**
```javascript
#!/usr/bin/env node
require('azify-logger/register-otel');
// Resto do código...
```

**2. No servidor Restify:**
```javascript
import { middleware as azifyMiddleware } from 'azify-logger'

const server = restify.createServer()
server.use(azifyMiddleware.restify())
```

**3. Variável de ambiente:**
```bash
APP_NAME=nome-app
```

**PRONTO! 🎉** 

### Para aplicações Express:

```javascript
require('azify-logger')

const express = require('express')
const app = express()
// Logs automáticos via OpenTelemetry
```

### ❌ O que NÃO precisa:
- ❌ Instalar dependências OpenTelemetry separadamente
- ❌ Configurar tracing manualmente

## ⚙️ Variáveis de Ambiente

| Variável | Padrão                            | Descrição |
|----------|-----------------------------------|-----------|
| `APP_NAME` | -                                 | Nome da aplicação |
| `AZIFY_LOGGER_URL` | `http://localhost:3001/log`       | URL do logger |
| `NODE_ENV` | `development` | Ambiente |

### 🌐 URLs por Ambiente

**Desenvolvimento (Local):**
```env
APP_NAME=minha-app
AZIFY_LOGGER_URL=http://localhost:3001/log
NODE_ENV=development
```

**Staging:**
```env
APP_NAME=minha-app
AZIFY_LOGGER_URL=https://logsdashboard.azify.dev/send
NODE_ENV=staging
```

**Production:**
```env
APP_NAME=minha-app
AZIFY_LOGGER_URL=https://logsdashboard.azify.prd/send (a conigurar)
NODE_ENV=production
```

### 🐳 Docker Compose (mesma network)

Apenas se estiver usando Docker Compose com rede compartilhada:

```env
AZIFY_LOGGER_URL=http://azify-logger:3001/log
```

### Docker e Node antigos

Se seu container usa uma versão antiga do Node e você ver erros de inicialização do OpenTelemetry (ex.: `Cannot find module 'node:events'` saindo de `google-logging-utils` ou `@opentelemetry/resource-detector-gcp`), defina no container:

```bash
AZIFY_LOGGER_AUTOREG_DISABLE=1
```

Isso evita carregar `register-otel.js` e mantém os envios de log via streams/middleware normalmente, permitindo visualização no OpenSearch.

## 🎯 O Que Você Ganha

- ✅ **Zero Config**: OpenTelemetry habilitado automaticamente
- ✅ **Logs Completos**: Headers, body, query params, status
- ✅ **Trace Consistente**: REQUEST e RESPONSE com mesmo traceId/spanId
- ✅ **Genérico**: Funciona com Bunyan, Pino, console.log ou qualquer logger
- ✅ **Centralizado**: Todos os logs no OpenSearch

## 🔧 Uso Avançado

### Com Bunyan existente (adicionar stream)

Se sua app **já tem Bunyan** e você quer adicionar o azify-logger como stream adicional:

```javascript
// Forma segura com try/catch (não quebra se não tiver instalado)
let createAzifyBunyanStream
try {
  createAzifyBunyanStream = require('azify-logger/streams/bunyan')
} catch (_) {
  createAzifyBunyanStream = null
}

const bunyan = require('bunyan')
const streams = [
  { level: 'info', stream: process.stdout }
]

// Adiciona stream do azify-logger se disponível
if (createAzifyBunyanStream) {
  streams.push({
    level: 'info',
    type: 'raw',
    stream: createAzifyBunyanStream({
      loggerUrl: process.env.AZIFY_LOGGER_URL || 'http://localhost:3001/log',
      serviceName: process.env.APP_NAME || 'app'
      loggerUrl: process.env.AZIFY_LOGGER_URL,
      serviceName: process.env.APP_NAME
    })
  })
}

const logger = bunyan.createLogger({ name: 'app', streams })
logger.info('Teste')  // Vai para stdout E para azify-logger
```

### Com Bunyan (auto-patch - mais simples)

```javascript
require('azify-logger')

const bunyan = require('bunyan')
const log = bunyan.createLogger({ name: 'nome-app' })

log.info('Teste')  // Automaticamente enviado para azify-logger
```

### Com Pino

```javascript
const { streams } = require('azify-logger')
const pino = require('pino')

const logger = pino({ level: 'info' }, streams.createPinoStream({
  loggerUrl: 'http://localhost:3001/log',
  serviceName: 'nome-app'
}))

logger.info('Teste')
```

### Logger Direto (sem Bunyan/Pino)

```javascript
const { createAzifyLogger } = require('azify-logger')

const logger = createAzifyLogger({
  serviceName: 'nome-app',
  loggerUrl: 'http://localhost:3001/log'
})

logger.info('Mensagem', { userId: '123' })
logger.error('Erro', new Error('Falha'), { context: 'payment' })
```

---

## 🛠️ Setup do Serviço de Logging (Infra)

Se você precisa subir a infraestrutura do azify-logger:


```bash
./start-docker.sh
```

Aguarde alguns minutos. Você verá:

```
✅ Tudo pronto!
📊 OpenSearch: http://localhost:9200
🎨 OpenSearch Dashboards: http://localhost:5601
📝 Logger API: http://localhost:3001/log
🔭 OTEL Collector: http://localhost:4318
```

### 2. Testar

```bash
curl -X POST http://localhost:3001/log \
  -H "Content-Type: application/json" \
  -d '{
    "level": "info",
    "message": "Teste",
    "meta": {"service": {"name": "teste"}}
  }'
```

### 3. Ver logs

**OpenSearch Dashboards:**
```bash
http://localhost:5601
```

**Como usar:**
Acesse: http://localhost:5601

## 📊 Estrutura dos Logs

Cada log no OpenSearch contém:

```json
{
  "timestamp": "2025-10-01T10:15:30.123Z",
  "level": "info",
  "message": "[REQUEST] POST /api/payment",
  "service": {
    "name": "nome-app",
    "version": "1.0.0"
  },
  "traceId": "abc123...",
  "spanId": "xyz789...",
  "method": "POST",
  "url": "/api/payment",
  "requestBody": { ... },
  "statusCode": 200,
  "responseTime": 123.45,
  "responseBody": { ... },
  "environment": "production",
  "hostname": "app-server-01"
}
```

## 🔍 Como Funciona

1. **OpenTelemetry** cria um span para cada request HTTP
2. **Middleware** captura request e response com o **mesmo span ativo**
3. **Logger** envia ambos os logs com **traceId e spanId iguais**
4. **OpenSearch** indexa e permite buscar por traceId

---

## 📖 Arquitetura

```
┌─────────────┐
│  aplicação  │  
└──────┬──────┘
       │ HTTP POST
       ↓
┌─────────────┐
│ azify-logger│  (recebe logs)
└──────┬──────┘
       │
       ↓
┌─────────────┐
│ OpenSearch  │  (armazena)
└──────┬──────┘
       │
       ↓
┌─────────────┐
│  Dashboards |
|  OpenSearch │ (visualiza)
└─────────────┘
```

## 📈 OpenSearch Dashboards

O azify-logger usa OpenSearch Dashboards para visualização dos logs:

### 🎯 Funcionalidades Disponíveis

1. **📊 Discover** - Visualização e busca de logs
   - Filtros por serviço, app, traceId, statusCode
   - Busca em tempo real
   - Visualização detalhada de cada log

2. **📈 Dashboard** - "Application Health Dashboard"
   - **Taxa de Sucesso** - Percentual de requisições 2xx
   - **Latência Média** - Tempo médio de resposta
   - **Erros 4xx/5xx** - Contador de erros
   - **Requisições por Minuto** - Gráfico temporal

### ⚠️ Preservação de Dados

**IMPORTANTE:** Logs do OpenSearch são armazenados em volume Docker persistente.

**Comandos seguros** (preservam dados):
```bash
docker-compose stop
docker-compose restart
pm2 stop azify-logger
```

**Comandos destrutivos** (APAGAM logs):
```bash
docker-compose down -v  # ⚠️ APAGA VOLUMES!
```