🚀 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://cadence.aztech.host/send |

URLs para acessar os logs:

| Ambiente | URL | |----------|-----------------------------------| | Development | http://localhost:3002 | | Staging | https://logsdashboard.azify.dev | | Production | https://cadence.aztech.host |

📦 Instalação

npm install azify-logger

⚡ Utilização

Para aplicações Restify:

// 1. No arquivo de inicialização
require('azify-logger/register-otel');

// 2. No servidor
import { middleware as azifyMiddleware } from 'azify-logger'
const server = restify.createServer()
server.use(azifyMiddleware.restify())

// 3. Variável de ambiente
APP_NAME=nome-app

Para aplicações Express:

require('azify-logger')
const express = require('express')
const app = express()
const azifyMiddleware = require('azify-logger/middleware-express')
app.use(azifyMiddleware())

Para aplicações Fastify:

const fastify = require('fastify')()
const azifyPlugin = require('azify-logger/middleware-fastify')

await fastify.register(azifyPlugin, {
  serviceName: 'minha-app'
})

await fastify.listen({ port: 3000 })

⚙️ 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 | | OTEL_EXPORTER_OTLP_ENDPOINT | http://localhost:4318/v1/traces | Endpoint OTLP para traces (opcional) | | NODE_ENV | development | Ambiente |

🎯 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
• ✅ Tracing Completo: Traces exportados via OTLP para Grafana Tempo (opcional)

📡 OpenTelemetry Collector

O azify-logger inclui um OpenTelemetry Collector configurado para receber traces via OTLP e exportá-los para Grafana Tempo.

Configuração

Para habilitar o envio de traces, configure a variável de ambiente na sua aplicação:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces

URLs

| Ambiente | URL | |----------|-----| | Development | http://localhost:4318/v1/traces | | Staging | https://logsdashboard.azify.dev/v1/traces | | Production | https://cadence.aztech.host/v1/traces |

🔍 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 em logs-{appName})
└──────┬──────┘
       │
       ↓
┌─────────────┐
│   Grafana   │  (visualiza - Organizations por app)
└─────────────┘

📈 Grafana - Visualização de Logs

O azify-logger usa Grafana para visualização dos logs com controle de acesso por aplicação.

Funcionalidades

• 📊 Explore: Busca e visualização de logs em tempo real
• 📈 Dashboards: Dashboards automáticos com métricas (Total de Requisições, Taxa de Sucesso, Erros, Tempo Médio de Resposta, etc.)

Controle de Acesso Automático

Quando uma aplicação envia logs pela primeira vez, o sistema automaticamente:

1. ✅ Cria uma Organization no Grafana com o nome da aplicação
2. ✅ Cria um Datasource filtrado para o índice logs-{appName}
3. ✅ Cria um Dashboard completo com métricas
4. ✅ Isola completamente os logs da aplicação

Gerenciar acesso:

• Acesse Grafana como Server Admin
• Vá em Administration → Organizations
• Adicione usuários à Organization da app
• ⚠️ Importante: Use role Editor ou Admin para acesso ao Explorer (onde estão os logs). Role Viewer não tem acesso ao Explorer.

🛠️ Setup Local

./start-docker.sh

Aguarde alguns minutos. Você verá:

✅ Tudo pronto!
📊 OpenSearch: http://localhost:9200
📈 Grafana: http://localhost:3002
📝 Logger API: http://localhost:3001/log

Configuração de Ambiente

Copie os arquivos de exemplo e preencha com seus valores:

cp env/app.env.example env/app.env
cp env/grafana.env.example env/grafana.env

✅ Importante: configure seu e-mail para ser promovido a Admin

1. Abra env/grafana.env.
2. Atualize ADMIN_GLOBAL_EMAIL com seu e-mail corporativo (ex.: [email protected]).
3. Abra env/app.env.
4. Garanta que ADMIN_EMAILS contenha o mesmo e-mail (ex.: [email protected]).
5. Salve os arquivos e reinicie os containers (./start-docker.sh).

Assim, ao fazer login com Azure AD, você é promovido automaticamente a Server Admin e já enxerga o Explore e os dashboards da sua aplicação.

Testar

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

Acesse http://localhost:3002 e faça login com Azure AD.

🚀 Deploy

Staging - Deploy Automático

git push origin master

O deploy é feito automaticamente via GitHub Actions.

Production - Deploy Manual

1. Acesse: GitHub → Actions → Deploy
2. Clique em Run workflow
3. Configure: Environment: production
4. Clique em Run workflow

⚠️ Preservação de Dados

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

Comandos seguros (preservam dados):

docker compose stop
docker compose restart

Comandos destrutivos (APAGAM logs):

docker compose down -v  # ⚠️ APAGA VOLUMES!