Pular para conteúdo

LOGGER - Sistema de Logs Estruturados

O que é este Node?

O LOGGER é o node responsável por criar logs estruturados e organizados do flow com níveis de severidade, categorias, tags e correlação para debug e auditoria.

Por que este Node existe?

Logs são essenciais para debug e monitoramento. O LOGGER existe para:

  1. Debug de flows: Rastrear execução e identificar problemas
  2. Auditoria: Registrar ações importantes para compliance
  3. Monitoramento: Acompanhar saúde e performance do sistema
  4. Troubleshooting: Facilitar investigação de erros e bugs
  5. Logs estruturados: Organizar informações com contexto completo

Como funciona internamente?

Quando o LOGGER é executado, o sistema:

  1. Captura dados do log (level, message, metadata)
  2. Adiciona contexto automático (flowId, userId, sessionId, nodeId)
  3. Gera correlation_id se não fornecido
  4. Formata entrada estruturada com timestamp e categorização
  5. Registra no logger do sistema conforme nível de severidade
  6. Retorna confirmação com dados do log criado

Código interno (analytics-executor.service.ts:75-120): 

private async executeLogger(parameters: any, context: any): Promise<any> {
  const { level, message, metadata, category, tags, correlation_id } = parameters;

  this.logger.log(`📝 LOGGER - Level: ${level || 'info'}, Message: "${message}"`);

  const logEntry = {
    timestamp: new Date().toISOString(),
    level: level || 'info',
    message: message || 'No message provided',
    metadata: metadata || {},
    category: category || 'general',
    tags: tags || [],
    correlation_id: correlation_id || this.generateCorrelationId(),
    context: {
      flowId: context.flowId,
      userId: context.userId,
      sessionId: context.sessionId,
      nodeId: context.currentNodeId
    }
  };

  // Log based on level
  switch (level?.toLowerCase()) {
    case 'error':
      this.logger.error(message, metadata);
      break;
    case 'warn':
      this.logger.warn(message, metadata);
      break;
    case 'debug':
      this.logger.debug(message, metadata);
      break;
    case 'verbose':
      this.logger.verbose(message, metadata);
      break;
    default:
      this.logger.log(message, metadata);
  }

  return {
    success: true,
    action: 'log_entry_created',
    logEntry: logEntry,
    timestamp: logEntry.timestamp
  };
}

Quando você DEVE usar este Node?

Use LOGGER sempre que precisar registrar informações para debug/auditoria:

Casos de uso:

  1. Debug de integração: Registrar payloads enviados/recebidos de APIs
  2. Auditoria de ações: Registrar operações críticas (compra, cancelamento)
  3. Rastreamento de erros: Capturar contexto quando algo falha
  4. Performance: Registrar tempos de execução de operações
  5. Flow complexo: Adicionar checkpoints para entender execução
  6. Compliance: Manter histórico de ações para regulamentações

Quando NÃO usar LOGGER:

  • Analytics de usuário: Use ANALYTICS para rastrear comportamento
  • Métricas de negócio: Use METRIC para KPIs
  • Eventos de produto: Use EVENT para eventos de negócio

Parâmetros Detalhados

level (string, opcional)

O que é: Nível de severidade do log.

Opções: error, warn, info, debug, verbose

Padrão: "info"

Flow completo para testar níveis:

{
  "name": "Teste LOGGER - Níveis",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "logger_debug",
      "type": "logger",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Log Debug",
        "parameters": {
          "level": "debug",
          "message": "Flow iniciado - modo debug",
          "category": "flow_execution"
        }
      }
    },
    {
      "id": "logger_info",
      "type": "logger",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Log Info",
        "parameters": {
          "level": "info",
          "message": "Processamento em andamento",
          "category": "flow_execution"
        }
      }
    },
    {
      "id": "logger_warn",
      "type": "logger",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Log Warning",
        "parameters": {
          "level": "warn",
          "message": "Operação próxima do timeout",
          "category": "performance"
        }
      }
    },
    {
      "id": "logger_error",
      "type": "logger",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Log Error",
        "parameters": {
          "level": "error",
          "message": "Falha ao conectar na API externa",
          "category": "integration"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Todos os níveis de log foram registrados"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "logger_debug" },
    { "source": "logger_debug", "target": "logger_info" },
    { "source": "logger_info", "target": "logger_warn" },
    { "source": "logger_warn", "target": "logger_error" },
    { "source": "logger_error", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Verifique os logs do sistema - cada nível aparecerá com formatação diferente

message (string, obrigatório)

O que é: Mensagem descritiva do log.

Flow completo para testar:

{
  "name": "Teste LOGGER - Message",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "CPF",
        "parameters": {
          "message": "Digite seu CPF:",
          "variable": "cpf"
        }
      }
    },
    {
      "id": "logger_1",
      "type": "logger",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Log Validação",
        "parameters": {
          "level": "info",
          "message": "CPF fornecido para validação: {{cpf}}",
          "category": "validation"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "CPF registrado no log!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "logger_1" },
    { "source": "logger_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite um CPF - será registrado no log com contexto completo

metadata (object, opcional)

O que é: Dados adicionais estruturados para incluir no log.

Flow completo para testar:

{
  "name": "Teste LOGGER - Metadata",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Valor",
        "parameters": {
          "message": "Valor da transação:",
          "variable": "valor",
          "decimals": 2
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Calcular Taxa",
        "parameters": {
          "operation": "set",
          "variables": {
            "taxa": "{{valor * 0.05}}",
            "total": "{{valor * 1.05}}"
          }
        }
      }
    },
    {
      "id": "logger_1",
      "type": "logger",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Log Transação",
        "parameters": {
          "level": "info",
          "message": "Transação processada com sucesso",
          "category": "transaction",
          "metadata": {
            "valor_original": "{{valor}}",
            "taxa_aplicada": "{{taxa}}",
            "valor_total": "{{total}}",
            "payment_method": "credit_card",
            "installments": 3
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "💰 Total: R$ {{total}}\n(valor: {{valor}} + taxa: {{taxa}})\n\n✅ Transação registrada!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "number_1" },
    { "source": "number_1", "target": "variable_1" },
    { "source": "variable_1", "target": "logger_1" },
    { "source": "logger_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite 100 - log terá metadata completa com valor, taxa e total calculados

category (string, opcional)

O que é: Categoria do log para organização e filtragem.

Padrão: "general"

Exemplos de categorias: - flow_execution - api_integration - validation - transaction - authentication - error_handling

tags (array, opcional)

O que é: Tags para classificação adicional e busca.

Padrão: []

Flow completo para testar:

{
  "name": "Teste LOGGER - Tags",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "logger_1",
      "type": "logger",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Log com Tags",
        "parameters": {
          "level": "info",
          "message": "Pedido criado com sucesso",
          "category": "order",
          "tags": ["checkout", "payment_success", "first_purchase", "high_value"]
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Log criado com tags para fácil busca!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "logger_1" },
    { "source": "logger_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Log será criado com múltiplas tags para facilitar buscas posteriores

correlation_id (string, opcional)

O que é: ID único para correlacionar múltiplos logs da mesma operação.

Padrão: Gerado automaticamente (corr_timestamp_random)

Parâmetros

Campo Tipo Obrigatório Descrição
level string Não Nível de severidade (error, warn, info, debug, verbose) - padrão: info
message string Sim Mensagem descritiva do log
metadata object Não Dados estruturados adicionais
category string Não Categoria do log (padrão: general)
tags array Não Tags para classificação (padrão: [])
correlation_id string Não ID para correlacionar logs (auto-gerado se omitido)

Exemplo 1: Debug de Integração API

Objetivo: Registrar requisição e resposta de API externa

JSON para Importar

{
  "name": "Debug API Integration",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Preparar Request",
        "parameters": {
          "operation": "set",
          "variables": {
            "api_endpoint": "https://api.example.com/users",
            "request_payload": "{\"name\": \"João\", \"email\": \"joao@example.com\"}",
            "correlation": "req_12345"
          }
        }
      }
    },
    {
      "id": "logger_request",
      "type": "logger",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Log Request",
        "parameters": {
          "level": "debug",
          "message": "Enviando requisição para API externa",
          "category": "api_integration",
          "correlation_id": "{{correlation}}",
          "metadata": {
            "endpoint": "{{api_endpoint}}",
            "method": "POST",
            "payload": "{{request_payload}}",
            "timestamp": "{{$timestamp}}"
          },
          "tags": ["api", "external", "outbound"]
        }
      }
    },
    {
      "id": "delay_1",
      "type": "delay",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Simular API",
        "parameters": {
          "duration": 2,
          "unit": "seconds"
        }
      }
    },
    {
      "id": "variable_2",
      "type": "variable",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Simular Response",
        "parameters": {
          "operation": "set",
          "variables": {
            "api_response": "{\"status\": \"success\", \"user_id\": \"user_789\"}",
            "status_code": 200
          }
        }
      }
    },
    {
      "id": "logger_response",
      "type": "logger",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Log Response",
        "parameters": {
          "level": "debug",
          "message": "Resposta recebida da API externa",
          "category": "api_integration",
          "correlation_id": "{{correlation}}",
          "metadata": {
            "endpoint": "{{api_endpoint}}",
            "status_code": "{{status_code}}",
            "response": "{{api_response}}",
            "timestamp": "{{$timestamp}}"
          },
          "tags": ["api", "external", "inbound", "success"]
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Integração completa!\n\nRequest e Response registrados com correlation_id: {{correlation}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "logger_request" },
    { "source": "logger_request", "target": "delay_1" },
    { "source": "delay_1", "target": "variable_2" },
    { "source": "variable_2", "target": "logger_response" },
    { "source": "logger_response", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Integração completa!

Request e Response registrados com correlation_id: req_12345

Logs gerados: 1. [DEBUG] Enviando requisição para API externa (correlation: req_12345) 2. [DEBUG] Resposta recebida da API externa (correlation: req_12345)

Exemplo 2: Auditoria de Transação Financeira

Objetivo: Criar log de auditoria completo de transação

JSON para Importar

{
  "name": "Auditoria de Transação",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "logger_start",
      "type": "logger",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Iniciar Transação",
        "parameters": {
          "level": "info",
          "message": "Transação iniciada",
          "category": "transaction",
          "tags": ["transaction", "started", "audit"],
          "metadata": {
            "transaction_id": "txn_{{$timestamp}}",
            "user_id": "{{$userId}}",
            "action": "transaction_started"
          }
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Valor",
        "parameters": {
          "message": "Valor da transferência:",
          "variable": "valor",
          "decimals": 2,
          "min": 0.01
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Destinatário",
        "parameters": {
          "message": "CPF do destinatário:",
          "variable": "destinatario"
        }
      }
    },
    {
      "id": "logger_validation",
      "type": "logger",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Validação",
        "parameters": {
          "level": "info",
          "message": "Validando dados da transação",
          "category": "transaction",
          "tags": ["transaction", "validation", "audit"],
          "metadata": {
            "amount": "{{valor}}",
            "recipient": "{{destinatario}}",
            "validation_status": "passed"
          }
        }
      }
    },
    {
      "id": "logger_completed",
      "type": "logger",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Concluir",
        "parameters": {
          "level": "info",
          "message": "Transação concluída com sucesso",
          "category": "transaction",
          "tags": ["transaction", "completed", "audit", "success"],
          "metadata": {
            "amount": "{{valor}}",
            "recipient": "{{destinatario}}",
            "status": "completed",
            "completed_at": "{{$timestamp}}"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Transferência de R$ {{valor}} concluída!\n\n📋 Toda a operação foi registrada para auditoria."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "logger_start" },
    { "source": "logger_start", "target": "number_1" },
    { "source": "number_1", "target": "input_1" },
    { "source": "input_1", "target": "logger_validation" },
    { "source": "logger_validation", "target": "logger_completed" },
    { "source": "logger_completed", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Valor da transferência:
Usuário: 500.00
Sistema: CPF do destinatário:
Usuário: 123.456.789-00
Sistema: ✅ Transferência de R$ 500.00 concluída!

📋 Toda a operação foi registrada para auditoria.

Resposta do Node

{
  "success": true,
  "action": "log_entry_created",
  "logEntry": {
    "timestamp": "2025-01-15T10:30:00.000Z",
    "level": "info",
    "message": "Transação concluída com sucesso",
    "metadata": {
      "amount": 500.00,
      "recipient": "123.456.789-00",
      "status": "completed"
    },
    "category": "transaction",
    "tags": ["transaction", "completed", "audit", "success"],
    "correlation_id": "corr_1736934600000_abc123xyz",
    "context": {
      "flowId": "flow_789",
      "userId": "user_456",
      "sessionId": "session_123",
      "nodeId": "logger_completed"
    }
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Níveis de Log

Level Uso Quando usar
error Erros críticos Falhas que impedem execução
warn Avisos Situações anormais mas não críticas
info Informações Eventos importantes de negócio
debug Debug Informações detalhadas para desenvolvimento
verbose Muito detalhado Informações extremamente detalhadas

Boas Práticas

✅ SIM: - Use correlation_id para rastrear operações multi-step - Inclua metadata relevante para troubleshooting - Use categorias consistentes em todo o sistema - Adicione tags para facilitar buscas - Use level apropriado (não abuse de error) - Registre timestamps de operações críticas

❌ NÃO: - Não logue senhas ou dados sensíveis - Não abuse de logs (pode impactar performance) - Não use level="error" para avisos - Não logue dados pessoais sem necessidade - Não crie logs genéricos sem contexto

Dicas

💡 Correlation ID: Use o mesmo correlation_id em todos os logs de uma operação para rastreamento completo

💡 Metadata estruturada: Sempre use objetos estruturados em metadata - facilita parsing e análise

💡 Categorias: Defina categorias padrão no início do projeto e mantenha consistência

💡 Tags: Use tags para multi-dimensional filtering (ex: ["payment", "success", "first_time"])

💡 Contexto automático: O sistema já adiciona flowId, userId, sessionId - não precisa duplicar

💡 Debug vs Info: Use debug para logs técnicos, info para eventos de negócio

Próximo Node

→ ANALYTICS - Rastrear eventos de usuário → METRIC - Rastrear métricas e KPIs → EVENT - Rastrear eventos de negócio