Monitorização e Alertas PrestaShop (DataFirefly Monitor)
Instalar o DataFirefly Monitor 2.0.0 no PrestaShop 1.7.8 a 9, agendar o cron, configurar os canais de alerta, as páginas monitorizadas e as regras, e compreender cada deteção.
O DataFirefly Monitor vigia a sua loja PrestaShop continuamente e avisa-o quando ela cai, falha, fica lenta ou deixa de receber pagamentos. Indica o módulo com mais probabilidade de ser o responsável, envia um único alerta por problema e diz-lhe quando tudo voltou ao normal. Esta documentação diz respeito à versão 2.0.0.

Instalação e atualização
Requisitos
- PrestaShop 1.7.8 a 9.x, multiloja e multilingue
- PHP 7.1 a 8.5, com cURL (recomendado)
- Uma tarefa cron a cada 5 minutos (recomendado, ver abaixo)
Instalação
- No back office, abra Módulos > Gestor de módulos, clique em Carregar um módulo e envie
dfmonitor-2.0.0.zip. - O módulo cria as suas tabelas e o separador Parâmetros Avançados > Monitorização e alertas. O botão Configurar do módulo leva diretamente até lá.
- Na instalação, o e-mail da loja é usado como destinatário e o estado Erro de pagamento é escolhido como estado de falha. Os logs do PrestaShop escritos antes da instalação não são importados.
Atualização a partir da 1.x
Carregue o novo zip por cima do antigo: o script de atualização acrescenta as novas colunas e definições sem mexer nos seus dados. O histórico de erros, os alertas, as notificações, as suas definições e o token do cron são mantidos, por isso o URL do cron que já usa continua a funcionar.
Painel
O cabeçalho resume o estado da loja numa frase: Tudo funciona, um aviso ou um problema crítico. Por baixo estão os alertas abertos com os botões Confirmar receção e Fechar, e seis indicadores: disponibilidade em 24 horas, tempo de resposta na última hora (p95), erros PHP em 24 horas, pagamentos falhados, encomendas de hoje comparadas com a atividade habitual e servidor.
A faixa de disponibilidade mostra as últimas 24 horas em blocos de 15 minutos. O cartão Páginas monitorizadas lista a página inicial e as páginas adicionais com o último código HTTP, o tempo de resposta e a disponibilidade em 24 horas.

Dois gráficos mostram o tempo de resposta (média e p95) e os erros PHP por hora em 24 horas, seguidos dos últimos erros e dos tipos de página mais lentos.

Tarefa cron
Os erros fatais e os pagamentos falhados são comunicados em tempo real. Tudo o resto (disponibilidade, tempo de resposta, encomendas, saúde do servidor, relatório) é avaliado por uma tarefa agendada a executar a cada 5 minutos.
Cron do servidor (recomendado)
*/5 * * * * php /caminho/para/prestashop/modules/dfmonitor/cron.php
O comando exato, com o caminho do seu servidor, aparece em Definições > Verificações agendadas com um botão Copiar. Execute-o com o utilizador do servidor web. O cron.php recusa qualquer chamada que não venha da linha de comandos.
Cron por URL
Se o seu alojamento só permite crons web, chame o URL indicado no mesmo separador a partir do painel de alojamento ou de um serviço como o cron-job.org. O token também pode ser enviado no cabeçalho X-Dfmonitor-Token. Sem o token correto, o endereço responde 403 e não revela nada. Com ele, a resposta só indica o estado, a duração e o número de alertas abertos: nenhum caminho, versão ou mensagem de erro. Através deste URL as verificações correm no máximo uma vez por minuto, e Gerar um novo token invalida o anterior.

Sem cron
Com PHP-FPM, a opção Alternativa sem cron lança as verificações a partir do tráfego de visitantes quando nenhum cron correu há 10 minutos, depois de a página ter sido enviada. O teste de disponibilidade e o heartbeat não correm neste modo. Com Apache mod_php, o cron é indispensável.
Heartbeat externo
O módulo não consegue comunicar uma avaria completa do servidor. Crie uma verificação no Healthchecks.io ou no Better Stack e cole o seu URL em URL de heartbeat: é chamado a cada execução do cron, e o serviço avisa-o quando as chamadas param.
Canais de notificação
Ative os canais que quiser em Definições > Canais de notificação. Cada canal tem uma gravidade mínima (aviso e crítico, ou só crítico) e um botão Guardar e enviar um teste. O resultado do último envio aparece por baixo do nome do canal.

Os segredos nunca voltam a ser mostrados. Depois de guardados, os webhooks do Slack e do Discord, o token do Telegram, o URL do webhook e o seu segredo, e o URL de heartbeat ficam ocultos: o campo fica vazio com uma pista como https://hooks.slack.com/...7f3a. Deixe-o vazio para manter o valor, escreva um novo para o substituir ou clique em Remover.
Indique um ou mais destinatários separados por vírgulas. Os e-mails usam a configuração de e-mail do PrestaShop (Parâmetros Avançados > E-mail). O Idioma dos alertas aplica-se a todos os canais; por predefinição é o idioma da loja. Os e-mails existem em português, inglês, francês, espanhol, alemão, italiano, neerlandês e polaco.

Telegram
- No Telegram, abra @BotFather, envie
/newbote siga as instruções. - Cole o token recebido em Token do bot.
- Envie uma mensagem ao seu bot, ou adicione-o a um grupo, e clique em Detetar o meu chat: o ID do chat é preenchido automaticamente.
Slack e Discord
Slack: Apps > Incoming Webhooks > Add to Slack, escolha o canal e copie o URL que começa por https://hooks.slack.com/. Discord: Definições do servidor > Integrações > Webhooks > Novo webhook e depois Copiar URL do webhook.
Webhook
Para Zapier, Make, n8n, uma ferramenta de piquete ou o seu próprio script. É enviado um POST JSON por cada novo alerta, lembrete e resolução, com o cabeçalho X-DataFirefly-Event (open, repeat, resolved, test). O corpo contém event, alert (id, key, type, severity, title, message, occurrences, first_at, last_at, ack_url), shop e sent_at. Com um segredo de assinatura, cada pedido leva X-DataFirefly-Signature: sha256=…, o HMAC SHA-256 do corpo em bruto.
Por segurança, os endereços da rede privada, do próprio servidor e dos serviços de metadados cloud são recusados, e os redirecionamentos não são seguidos. Se a sua ferramenta estiver alojada na sua própria rede, ative Permitir um webhook na rede privada; os endereços de metadados cloud continuam recusados.
Regras de alerta
- Lembrete de um alerta em curso: intervalo entre duas notificações sobre o mesmo problema (60 minutos por predefinição). Um problema que piora, de aviso para crítico, é notificado de imediato.
- Máximo de notificações por hora: 20 por predefinição, 0 para não limitar. Um alerta enviado para vários canais conta uma vez. Uma mensagem retida aparece como Retido no registo e é enviada mais tarde.
- Resolver após: número de verificações corretas seguidas antes de fechar um alerta (2 por predefinição), para que um valor que oscila em torno de um limite não envie mensagens de abertura e resolução em ciclo.
- Mensagem de resolução: é enviada uma mensagem quando um problema notificado desaparece.
- Privacidade: os endereços de e-mail presentes nas mensagens de erro são ocultados no Slack, no Telegram, no Discord e no webhook (ativado por predefinição).
- Horas de silêncio: no período escolhido só são enviados os alertas críticos; os avisos esperam pelo fim do período.
- Relatório resumo por email: desativado, diário ou todas as segundas-feiras, à hora escolhida.

Pausa
O botão Pausa suspende as notificações durante 30 minutos, 2 horas, 8 horas ou 24 horas, por exemplo durante uma atualização. Os problemas continuam a ser detetados e registados; os que ainda estiverem abertos no fim da pausa são notificados.
O que o módulo deteta
Erros PHP
O módulo captura os erros fatais e os avisos (e, opcionalmente, notices e deprecations) na loja e, se a opção estiver ativa, no back office. Os erros idênticos são agrupados. Um novo erro fatal gera de imediato um alerta crítico; este expira sem mensagem após 24 horas sem nova ocorrência. É lançado um alerta de pico acima de 100 erros e avisos em 15 minutos (ajustável, 0 para desativar). Os logs do PrestaShop de gravidade 3 e 4 são importados a cada execução do cron. Cada erro recebe uma origem provável: módulo, tema, override, template compilado ou núcleo; quando o erro ocorre no núcleo, é usado o primeiro módulo da pilha de chamadas.
Tempo de resposta
O tempo de resposta é medido nas visitas reais. A Percentagem de páginas medidas vai de 1 a 100 %; cada página medida custa uma escrita na base de dados. É lançado um alerta quando o percentil 95 em 15 minutos ultrapassa o limite (3000 ms por predefinição), a partir de 20 páginas medidas, e fica resolvido quando o p95 volta a ficar 10 % abaixo do limite. É lançado um alerta crítico quando mais de 5 % dos pedidos terminam com erro de servidor em 15 minutos, com pelo menos 5 erros.
Disponibilidade e páginas monitorizadas
A cada execução do cron do servidor, o módulo carrega a página inicial e até 5 páginas à sua escolha: uma categoria, um produto, o carrinho, a página de contacto… Uma página está disponível quando responde HTTP 2xx ou 3xx (após no máximo 3 redirecionamentos), 401 ou 429. Está indisponível quando não responde, responde 5xx ou outro 4xx, não contém o texto esperado que definiu ou, no caso da página inicial, está em branco. Após 2 falhas seguidas (ajustável) abre-se um alerta crítico. A verificação fica suspensa em modo de manutenção.

Só são aceites endereços nos domínios da sua loja: para esta verificação, o módulo nunca contacta outro site. Use Guardar e testar as páginas agora para as verificar de imediato. Se o servidor não conseguir aceder ao seu próprio endereço público (alguns alojamentos, Docker, um proxy), indique o endereço local do servidor web em Endereço de ligação, por exemplo 127.0.0.1:80: o endereço da página e o seu cabeçalho Host mantêm-se.
Pagamentos e encomendas
- Falhas de pagamento: encomendas que passaram para um dos estados escolhidos na última hora, por módulo de pagamento (limite de 3 por predefinição). A verificação também corre assim que uma encomenda muda de estado, depois de a resposta ser enviada: nunca atrasa a encomenda.
- Conversão do checkout: percentagem de carrinhos que chegaram ao passo de pagamento e se tornaram encomendas, numa janela de 2 horas, comparada com a percentagem habitual em 28 dias. Começa após cerca de 40 carrinhos de histórico.
- Queda de encomendas: encomendas das últimas 3 horas (ajustável) comparadas com o mesmo período das 4 semanas anteriores. Ignorada quando se esperam menos de 4 encomendas.
- Sensibilidade: baixa, média (recomendada) ou alta.

Saúde do servidor
- Certificado SSL: lido a cada 6 horas. Aviso 14 dias antes de expirar (ajustável), crítico a 3 dias.
- Espaço em disco: aviso abaixo de 2048 MB livres (ajustável), crítico abaixo de um quarto desse limite.
- Vigilância do cron: assim que um cron do servidor tiver corrido, é lançado um alerta após 30 minutos sem execução.

Gerir os alertas
Um problema abre um único alerta, atualizado enquanto dura. O separador Alertas mostra um balanço de 30 dias (alertas, alertas críticos, tempo médio de resolução, mensagens enviadas), o histórico com a duração de cada incidente e o registo de cada envio.

- Confirmar receção: para os lembretes. A mensagem de resolução continua a ser enviada.
- Fechar: fecha o alerta. Se o problema persistir, abre-se um novo alerta na verificação seguinte.

Confirmar a partir do telemóvel
Cada notificação de alerta contém uma ligação Confirmar e parar os lembretes, assinada para esse alerta. Abre na loja uma página de confirmação pensada para o telemóvel, e o alerta só é confirmado depois de validar: os antivírus de correio que abrem as ligações não o podem confirmar no seu lugar.

Página de erros PHP
Filtre por gravidade ou origem e pesquise uma mensagem, um ficheiro ou uma página. Um erro expandido mostra a página, o controlador, as datas, a mensagem completa e a pilha de chamadas. Copiar o relatório para um programador copia um texto com as versões do PrestaShop e do PHP, o ficheiro, a origem, a página, as ocorrências, a mensagem e a pilha de chamadas. Silenciar continua a contar o erro mas nunca mais alerta sobre ele.

Permissões
Um funcionário cujo perfil só tem a permissão ver em Monitorização e alertas consulta todos os ecrãs só em leitura: os campos ficam desativados e as ações (executar, pausa, confirmar, definições) são recusadas.
Dados e privacidade
- Os endereços das páginas são guardados sem parâmetros de URL, e a pilha de chamadas sem argumentos de funções.
- O caminho do servidor e o nome da pasta de administração são retirados de todos os textos guardados ou enviados.
- Os tokens de bot e os caminhos de webhook são ocultados no registo de notificações.
- O histórico é eliminado após 30 dias por predefinição (7 a 365 dias), em pequenos lotes; os alertas fechados são guardados pelo menos 90 dias.
Limitações conhecidas
- O teste de disponibilidade parte do próprio servidor: não vê uma falha de rede ou de DNS exterior. O heartbeat externo cobre esse caso.
- Um erro fatal ocorrido antes do carregamento dos módulos não é captado pelo gestor de erros; o teste de disponibilidade e a taxa de 5xx assinalam-no.
- As páginas Symfony do back office não passam pelo hook que capta os erros do back office.
- A conversão do checkout baseia-se no hook
displayPaymentTop. Se o seu checkout numa página não o chamar, desative esta verificação: a queda de encomendas continua ativa.
Resolução de problemas
O teste de e-mail falha
Verifique a configuração em Parâmetros Avançados > E-mail e envie um teste a partir dessa página. O erro exato aparece depois do teste e no separador Alertas.
A página inicial aparece indisponível embora a loja funcione
O servidor provavelmente não consegue aceder ao seu próprio endereço público. Preencha Endereço de ligação (por exemplo 127.0.0.1:80) e clique em Guardar e testar as páginas agora.
«Nenhum cron do servidor detetado» continua a aparecer
Só contam o cron pela linha de comandos e o URL do cron. Execute o comando manualmente por SSH: mostra um relatório JSON. Se falhar, confirme o caminho do PHP CLI com o seu alojamento.
O teste do webhook responde «endereço recusado»
O URL aponta para a rede privada ou para o próprio servidor. Use um endereço público, ou ative Permitir um webhook na rede privada se a sua ferramenta estiver alojada na sua própria rede.