Monitorização e Alertas PrestaShop (DataFirefly Monitor)

O DataFirefly Monitor vigia continuamente a sua loja PrestaShop 8 ou 9 e avisa-o quando fica em baixo, falha, fica lenta ou deixa de receber pagamentos. Esta documentação cobre a instalação, a tarefa cron, os canais de notificação, cada deteção e a gestão dos alertas.

Instalação

1. No back office, abra Módulos > Gestor de módulos, clique em Carregar um módulo e envie o ficheiro dfmonitor-1.1.0.zip.
2. O módulo cria as suas tabelas e um separador Parâmetros avançados > Monitorização e alertas. O botão Configurar do módulo leva diretamente a ele.
3. Na instalação, o email da loja é usado como destinatário e o estado Erro de pagamento é selecionado como estado de falha. Os registos do PrestaShop anteriores à instalação não são importados.

O módulo é compatível com PrestaShop 8.0 a 9.x, multiloja e multilíngue. Não usa dependências Composer. A atualização a partir da 1.0.0 faz-se carregando o novo ZIP: o script de atualização acrescenta as novas colunas e preenche a origem dos erros já registados.

Primeiros passos

O painel mostra uma lista de arranque em quatro passos enquanto não estiver concluída: receber uma primeira notificação, adicionar a tarefa cron, verificar os estados de pagamento falhado, adicionar um heartbeat externo. Cada passo leva ao separador de definições certo.

Tarefa cron

Os erros fatais e os pagamentos falhados são comunicados em tempo real. O resto (disponibilidade, tempo de resposta, pagamentos, encomendas, servidor, relatório) é avaliado por uma tarefa agendada que deve correr 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.

Cron por URL

Se o seu alojamento só permite crons web, chame o URL protegido por token mostrado no mesmo separador, a partir do painel de alojamento ou de um serviço como cron-job.org. Responde em JSON e funciona também com a loja em modo de manutenção. O botão Gerar um novo token invalida o URL anterior.

Sem cron

Com PHP-FPM, a opção de recurso sem cron lança as verificações pelo tráfego de visitantes quando nenhum cron correu há 10 minutos, depois de a página ser enviada. A verificação de disponibilidade e o heartbeat não correm neste modo, e uma falha à noite pode passar despercebida sem visitas.

Heartbeat externo

O módulo não consegue comunicar uma falha total do servidor. Crie um check no Healthchecks.io ou no Better Stack e cole o URL em URL de heartbeat: é chamado em cada execução do cron, e o serviço avisa-o se deixar de receber chamadas.

Canais de notificação

Ative quantos canais quiser em Definições > Canais de notificação. Cada canal tem uma gravidade mínima (aviso e crítico, ou apenas crítico) e um botão Guardar e enviar um teste que guarda o formulário e depois envia uma mensagem real. O resultado do último envio aparece sob o nome do canal.

Email

Introduza um ou mais destinatários separados por vírgulas. Os emails usam a configuração de email do PrestaShop (Parâmetros avançados > E-mail) e o idioma predefinido da loja.

Telegram

1. No Telegram, abra @BotFather, envie /newbot e siga as instruções.
2. Cole o token recebido em Token do bot.
3. 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

No Slack: Apps > Incoming Webhooks > Add to Slack, escolha o canal e copie o URL do webhook, que começa por https://hooks.slack.com/.

Discord

No 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 em cada novo alerta, lembrete e resolução, com o cabeçalho X-DataFirefly-Event:

{
  "event": "open",
  "alert": {
    "id": 42, "key": "payment:1", "type": "payment", "severity": "critical",
    "title": "...", "message": "...", "occurrences": 3,
    "first_at": "2026-10-07 16:35:00", "last_at": "2026-10-07 16:45:00",
    "ack_url": "https://..."
  },
  "shop": { "name": "...", "url": "https://..." },
  "sent_at": "2026-10-07T16:45:01+02:00"
}

Os valores de event são open, repeat, resolved e test. Se for definido um segredo de assinatura, cada pedido inclui o cabeçalho X-DataFirefly-Signature: sha256=…, o HMAC SHA-256 do corpo em bruto com esse segredo.

Regras de alerta

• Lembrete de um alerta em curso: intervalo entre duas notificações do mesmo problema (60 minutos por predefinição).
• Máximo de notificações por hora: 20 por predefinição, 0 sem limite.
• Mensagem de resolução: é enviada uma mensagem quando um problema notificado desaparece.
• Horas de silêncio: no período escolhido, só são enviados alertas críticos. Um aviso ainda aberto no fim do período é enviado na execução seguinte do cron.
• Relatório resumo por email: desativado, diário ou todas as segundas-feiras, à hora escolhida. Inclui disponibilidade, tempo de resposta, erros PHP, encomendas, pagamentos falhados, alertas do período e erros mais frequentes.

Pausa

O botão Pausa no cabeçalho suspende as notificações durante 30 minutos, 2, 8 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 erros fatais e avisos (e, opcionalmente, notices e descontinuações) na loja e, se a opção estiver ativa, no back office. Os erros idênticos são agrupados. Um novo erro fatal dispara de imediato um alerta crítico; o alerta expira sem mensagem após 24 horas sem nova ocorrência. É gerado um alerta de pico acima de 100 erros e avisos em 15 minutos (ajustável, 0 para desativar). Os registos do PrestaShop de gravidade 3 e 4 são importados em cada execução do cron.

Cada erro recebe uma origem provável: módulo, tema, override, template compilado ou núcleo. Quando o erro surge no núcleo, é usado o primeiro módulo encontrado na pilha de chamadas.

Tempo de resposta e disponibilidade

• O tempo de resposta é medido em visitas reais à loja. A percentagem de páginas medidas ajusta-se de 1 a 100%; cada página medida custa uma escrita na base de dados.
• É gerado um alerta quando o percentil 95 em 15 minutos ultrapassa o limite (3000 ms por predefinição), a partir de 20 páginas medidas.
• É gerado um alerta crítico quando a taxa de erros de servidor (HTTP 5xx ou erro fatal PHP) ultrapassa 5% em 15 minutos, com pelo menos 5 erros.
• A página inicial é carregada em cada execução do cron do servidor; duas falhas seguidas abrem o alerta crítico «Loja inacessível». A verificação fica suspensa em modo de manutenção.

Pagamentos e encomendas

• Pagamentos falhados: encomendas que passaram para um dos estados selecionados na última hora, com a desagregação por módulo de pagamento. Limite predefinido: 3. A verificação também é lançada assim que uma encomenda muda de estado. Selecione os estados que os seus módulos de pagamento usam para uma recusa.
• Conversão no checkout: o módulo regista cada carrinho que chega ao passo de pagamento e compara, numa janela de 2 horas que termina 30 minutos antes da verificação, a parte desses carrinhos que se tornou encomenda com a parte habitual em 28 dias. A verificação começa após cerca de 40 carrinhos de histórico e 8 carrinhos na janela (ajustável).
• Queda de encomendas: as encomendas das últimas 3 horas (ajustável) são comparadas com a média do mesmo período nas 4 semanas anteriores. A verificação é ignorada quando se esperam menos de 4 encomendas. Zero encomendas em vez da atividade habitual dá um alerta crítico.
• Sensibilidade: baixa, média (recomendada) ou alta. A alta avisa mais cedo, mas gera mais falsos alarmes.

Em multiloja, pagamentos, conversão e encomendas são avaliados loja a loja.

Saúde do servidor

• Certificado SSL: lido a cada 6 horas no domínio da loja. 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. Em alojamento partilhado com quota, o valor lido pode ser o disco inteiro do servidor.
• Vigilância do cron: depois de um cron do servidor já ter corrido, é gerado um alerta a partir do tráfego de visitantes ou do back office após 30 minutos sem execução.

Gerir os alertas

Um problema abre um único alerta, atualizado enquanto dura. O separador Alertas mostra o histórico e as notificações enviadas, com o resultado de cada envio.

• Confirmar: 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 de uma notificação

Cada notificação de alerta contém um link Confirmar e parar os lembretes. Abre uma página de confirmação na loja, adaptada ao telemóvel; o alerta só é confirmado após validação, o que impede os antivírus de email de o confirmar ao abrir o link.

Página de erros PHP

Filtre por gravidade ou origem, pesquise uma mensagem, um ficheiro ou uma página. Um erro expandido mostra a página, o controlador, as datas, a mensagem completa e, para os avisos, a pilha de chamadas. O botão 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 sem voltar a alertar.

Dados e privacidade

• Os endereços das páginas são guardados sem parâmetros de URL.
• A pilha de chamadas é guardada sem os argumentos das funções.
• O caminho do servidor e o nome da pasta de administração são removidos de todos os textos guardados e enviados.
• Os tokens do Telegram e os caminhos de webhook são ocultados no registo de notificações.
• O histórico é eliminado após 30 dias por predefinição (ajustável de 7 a 365 dias); os alertas fechados são conservados 90 dias.

Limites conhecidos

• Um erro fatal que ocorra antes de os módulos serem carregados não é capturado pelo gestor de erros; a verificação de disponibilidade e a taxa de 5xx assinalam-no.
• As páginas Symfony do back office não passam pelo hook usado para capturar os erros do back office.
• A conversão no checkout depende do hook displayPaymentTop. Se o seu módulo de checkout numa página não o chamar, desative esta verificação: a queda de encomendas continua vigiada.

Resolução de problemas

O teste de email falha

Verifique a configuração em Parâmetros avançados > E-mail e envie um email de teste a partir dessa página. A mensagem de erro exata aparece após o teste e no separador Alertas.

«Nenhum cron do servidor detetado» continua visível

Só o cron CLI ou o URL cron contam como cron do servidor. Execute o comando à mão por SSH: mostra um relatório JSON. Se falhar, verifique com o seu alojamento o caminho para o PHP CLI.

O teste do Telegram devolve «chat not found»

Um bot só pode escrever para uma conversa que já lhe escreveu. Envie-lhe uma mensagem e depois clique em Detetar o meu chat.