Skip to main content

SpyGlass — Captura de requests HTTP

O plugin SpyGlass (spyglass) registra em arquivo de log todos os requests HTTP recebidos pelo ACCELERO. Para cada requisição que entra, ele grava o horário, o usuário logado (quando houver), o método HTTP e o path acessado. Existe exclusivamente para diagnóstico técnico — por exemplo, investigar qual rota está sendo chamada, em que ordem, e por qual operador.

Ferramenta de diagnóstico técnico (uso interno)

Este plugin é uma ferramenta interna de debug, sem interface de usuário, telas de configuração ou itens de menu. Ele apenas escuta o tráfego de entrada e escreve um arquivo de log no servidor. Deve ser instalado pela equipe técnica da IONGRADE quando há necessidade de auditar os requests recebidos — e desinstalado depois. Não é um recurso voltado ao cliente final.

Impacto em produção

O SpyGlass grava uma linha por request recebido, sem rotação automática nem limite de tamanho. Em ambientes com tráfego intenso o arquivo de log cresce rapidamente. Use de forma temporária durante uma investigação e limpe o log ao terminar (ver Limpar o log).

Disponibilidade

Disponibilizado como plugin (spyglass), instalado e habilitado pela equipe técnica da IONGRADE. Por ser uma ferramenta de diagnóstico, normalmente é ativado de forma temporária durante uma investigação.

Compatibilidade

Versão atual do plugin: 0.0.1 — compatível com ACCELERO 2.16.1.

O que o plugin faz​

Quando instalado e ativo, o plugin registra um listener no evento de request recebido do ACCELERO. A cada requisição HTTP que entra no sistema, ele acrescenta uma linha ao arquivo de log. Nenhuma ação do operador é necessária — o registro acontece automaticamente em segundo plano.

FuncionalidadeO que acontece no ACCELERO
Captura de requestsCada requisição HTTP recebida gera uma linha no log com horário, usuário, método e path
Identificação do usuárioSe houver um operador logado no momento do request, o nome do usuário é gravado; caso contrário, o campo fica vazio
Download do logUma rota dedicada (/spyglass/logs) devolve o conteúdo acumulado em formato de arquivo para download
Limpeza do logUma rota dedicada (/spyglass/clearlogs) apaga o arquivo de log do servidor
Quando usar

Útil para entender o que está chegando ao servidor em uma janela de tempo — sequência de chamadas, rotas inesperadas, qual operador disparou determinada ação — sem precisar habilitar XDebug ou ler logs de servidor web. Para depuração passo a passo do código, veja Debuggar em produção.

Dados capturados​

Cada request recebido gera uma linha no log com os seguintes campos:

CampoConteúdo
timestampData e hora do request, no formato Y-m-d H:i:s
usuarioNome do operador logado no momento do request; vazio quando não há sessão autenticada
methodMétodo HTTP da requisição (GET, POST, etc.)
pathCaminho (path) da URL requisitada
Sem corpo nem cabeçalhos

O SpyGlass registra apenas os quatro campos acima. Ele não grava parâmetros de query string, corpo da requisição, cabeçalhos, IP de origem ou resposta. É um registro leve do tráfego de entrada, não um dump completo.

Onde ficam os logs​

Os registros são gravados em um arquivo no diretório temporário privado do servidor:

<TMP_DIR_PRIVATE>/spyglass_logs.txt

O arquivo é acumulativo: novas linhas são sempre acrescentadas ao final, até que o log seja limpo manualmente.

Retenção

Não há retenção configurável, rotação ou expiração automática. O arquivo cresce indefinidamente enquanto o plugin estiver ativo, e só é zerado pela rota de limpeza ou removendo o arquivo manualmente do servidor.

Como acessar os logs​

O plugin expõe duas rotas HTTP. Ambas exigem a permissão master — apenas um operador com esse nível consegue baixar ou limpar o log.

Baixar o log​

Rota: GET /spyglass/logs

Retorna o conteúdo acumulado como arquivo para download (spyglass.txt). O conteúdo é montado a partir das linhas do log: a primeira linha define os cabeçalhos das colunas (timestamp, usuario, method, path) e cada linha seguinte vira um registro.

Se o arquivo de log não existir ou estiver vazio, a rota responde com conteúdo vazio.

TODO: Adicionar Screenshot

Exemplo do arquivo spyglass.txt baixado, mostrando as colunas timestamp, usuario, method e path com algumas linhas de tráfego real.

Limpar o log​

Rota: GET /spyglass/clearlogs

Apaga o arquivo spyglass_logs.txt do servidor, zerando o histórico de captura. Use ao concluir uma investigação para liberar espaço em disco.

Fluxo recomendado

Ative o plugin, reproduza o cenário que deseja investigar, baixe o log por GET /spyglass/logs, analise e em seguida limpe com GET /spyglass/clearlogs. Se a investigação terminou, desinstale o plugin.

Como funciona internamente​

  • O plugin registra um EventListener no evento request_incoming do ACCELERO (canal spyglass_request_incoming). Esse listener é disparado a cada requisição recebida.
  • Para cada request, o listener tenta obter o operador logado. Se não houver sessão (NotLoggedInException), o campo de usuário fica nulo.
  • Os quatro campos são serializados em JSON e acrescentados ao arquivo de log com FILE_APPEND — uma linha JSON por request.
  • O SpyGlassController expõe as ações logs (download) e clearLogs (limpeza), ambas protegidas pela checagem de permissão master.
  • O download usa o CSVGenerator do núcleo para transformar as linhas JSON em um arquivo tabular de saída.
Cache de rotas

O post_install.php invalida o cache de descoberta de rotas (RouteDiscovery) ao instalar o plugin, garantindo que as rotas /spyglass/logs e /spyglass/clearlogs passem a responder imediatamente após a instalação.

Casos de uso​

Investigar uma sequência de chamadas​

  1. Instalar e habilitar o plugin spyglass no ambiente sob investigação.
  2. Limpar o log com GET /spyglass/clearlogs para começar com um arquivo limpo.
  3. Reproduzir a ação ou cenário a investigar (ex.: um fluxo de tela que apresenta comportamento estranho).
  4. Baixar o log com GET /spyglass/logs e analisar a sequência de method + path, com horários e usuário.
  5. Limpar o log e desinstalar o plugin ao concluir.

Identificar qual operador disparou um request​

  1. Com o plugin ativo, baixar o log por GET /spyglass/logs.
  2. Localizar o path de interesse e conferir a coluna usuario da mesma linha (e o timestamp).
  3. Linhas com usuario vazio indicam requests sem operador logado (ex.: rotas públicas ou anteriores ao login).

Boas práticas​

  • Uso temporário: ative apenas durante a investigação e desinstale logo depois — o log cresce sem limite.
  • Limpe antes e depois: comece com o log zerado para isolar o cenário, e limpe ao final para não deixar dados residuais no servidor.
  • Permissão master: garanta que apenas operadores master da IONGRADE tenham acesso às rotas de download e limpeza.
  • Atenção ao disco: em ambientes de tráfego alto, monitore o tamanho de spyglass_logs.txt para não esgotar o espaço do diretório temporário.

Troubleshooting​

As rotas /spyglass/logs e /spyglass/clearlogs retornam 404​

Possíveis causas:

  • Plugin não instalado ou não habilitado.
  • Cache de rotas não foi invalidado.

Solução:

  1. Confirme que o plugin spyglass está instalado e ativo.
  2. Reexecute o post_install.php (ou limpe o cache de rotas) para forçar a redescoberta das rotas.

As rotas retornam erro de permissão​

Possível causa: o operador autenticado não possui a permissão master.

Solução: acesse com um operador que tenha o nível master. As duas rotas são restritas a esse perfil.

O log fica vazio mesmo com tráfego no sistema​

Possíveis causas:

  • O plugin não está habilitado, então o listener request_incoming não está registrado.
  • O arquivo de log foi limpo recentemente.

Solução:

  1. Confirme que o plugin está ativo e que o evento request_incoming está sendo emitido pelo ACCELERO.
  2. Gere alguns requests e baixe o log novamente por GET /spyglass/logs.

Ferramentas internas relacionadas​

  • Debuggar em produção — quando o registro de requests não basta e é preciso depurar o código passo a passo com XDebug.
  • Logger de mensagens de facial — ferramenta interna análoga, voltada ao diagnóstico das mensagens trocadas com o gateway facial.
  • Rotas HTTP — como o ACCELERO descobre e registra rotas de plugins.

Próximos Passos​