Pular para o conteúdo principal

logs-padrao

Padrão de logs e debug da aplicação​

Este documento define como registrar logs de debug no Cronospay para facilitar testes e investigação de bugs, especialmente ao usar o Cursor.

1. Formato padrão de log (app_log)​

Helper definido em config/log_helper.php:

  • Função: app_log(string $module, string $action, string $level = 'DEBUG', array $context = [])
  • Formato da linha:
[YYYY-mm-dd HH:ii:ss] [NÍVEL][MÓDULO][AÇÃO] | CONTEXT: {...}
  • Exemplos:
    • [2026-03-12 10:15:30] [DEBUG][LOGIN][VALIDACAO_ENTRADA] | CONTEXT: {"email":"usuario@teste.com","ip":"127.0.0.1"}
    • [2026-03-12 10:16:02] [ERROR][PAGAMENTOS][CHAMADA_GATEWAY] | CONTEXT: {"transactionId":123,"httpStatus":500}

Os arquivos são gravados em config/logs/app_YYYY-MM-DD.log.

2. Convenções de uso​

  • MÓDULO ($module):

    • Use nomes em MAIÚSCULAS e estáveis, por exemplo:
      • LOGIN, USUARIOS, CLIENTES, ESTABELECIMENTOS
      • PAGAMENTOS, TRANSACOES, MOVINGPAY, ENTREPAY
      • FINANCEIRO, COMISSOES, CONSING, WHITE_LABEL
      • TERMINAIS, DASHBOARD, RELATORIOS, WEBHOOKS

  • AÇÃO ($action):

    • Descreve o ponto do fluxo onde o log é feito, por exemplo:
      • VALIDACAO_ENTRADA, VALIDACAO_REGRAS
      • CHAMADA_GATEWAY, RETORNO_GATEWAY, MONTAGEM_REQUEST
      • BUSCA_BANCO, ATUALIZACAO_STATUS, GERACAO_RELATORIO
      • PROCESSAMENTO_WEBHOOK, REPROCESSAMENTO_JOB

  • NÍVEL ($level):

    • DEBUG: detalhes de fluxo, apenas ambiente de desenvolvimento.
    • INFO: eventos normais importantes (início/fim de processo).
    • WARNING: situações inesperadas, mas não fatais.
    • ERROR: falhas que causam erro no fluxo.

  • CONTEXT ($context):

    • Array associativo com informações úteis, por exemplo:
      • IDs: transactionId, userId, estabelecimentoId, whiteLabelId
      • Parâmetros de filtro, datas, status
    • Evite colocar dados sensíveis:
      • Senhas, tokens, dados de cartão, documentos completos.

3. Dados que NUNCA devem ir para o log​

Mesmo em ambiente de desenvolvimento, NÃO logar:

  • Senhas (senha, password).
  • Tokens (token, access_token, refresh_token).
  • Dados completos de cartão (número, CVV).
  • Documentos completos quando não necessário (usar máscara).

O helper app_log já tenta mascarar algumas chaves sensíveis, mas isso é apenas uma proteção extra. A responsabilidade principal é de quem chama.

4. Padrões recomendados por tipo de fluxo​

  • Autenticação / Login

    • app_log('LOGIN', 'VALIDACAO_ENTRADA', 'DEBUG', ['email' => $email, 'ip' => $_SERVER['REMOTE_ADDR'] ?? null]);
    • app_log('LOGIN', 'USUARIO_NAO_ENCONTRADO', 'INFO', ['email' => $email]);
    • app_log('LOGIN', 'SENHA_INCORRETA', 'INFO', ['userId' => $userId ?? null]);

  • Pagamentos / Transações

    • app_log('PAGAMENTOS', 'CRIACAO_TRANSACAO', 'INFO', ['transactionId' => $id, 'valor' => $valor]);
    • app_log('MOVINGPAY', 'CHAMADA_GATEWAY', 'DEBUG', ['transactionId' => $id, 'endpoint' => $url]);
    • app_log('MOVINGPAY', 'RETORNO_GATEWAY', 'DEBUG', ['transactionId' => $id, 'status' => $status, 'httpStatus' => $httpStatus]);

  • Jobs / Polling / Cron

    • app_log('TRANSACOES', 'POLLING_INICIO', 'INFO', ['dataRef' => $data]);
    • app_log('TRANSACOES', 'POLLING_FIM', 'INFO', ['quantidadeProcessada' => $qtd]);
    • app_log('TRANSACOES', 'POLLING_ERRO', 'ERROR', ['mensagem' => $e->getMessage()]);

5. Diferença entre logs genéricos e logs específicos de módulo​

Já existe um helper específico para terminais em config/terminais/logs.php (logTerminal).
O app_log é um padrão genérico de aplicação e pode ser usado em qualquer fluxo.

Recomendação:

  • Em código novo, priorizar app_log.
  • Em código legado que usa file_put_contents direto ou helpers antigos:
    • Ir migrando aos poucos para app_log quando estiver refatorando/testando aquele fluxo.

6. Como usar nos testes e debug​

  1. Escolher o módulo e a ação de acordo com o fluxo que você está testando.
  2. Registrar logs na entrada e saída das funções principais.
  3. Registrar logs em decisões importantes (ifs, switches).
  4. Analisar o arquivo de log diário em config/logs/app_YYYY-MM-DD.log para acompanhar o caminho real percorrido pelo código.

Com isso, os testes descritos nos arquivos de cenários por módulo ficam muito mais fáceis de reproduzir e inspecionar.