Introdução
Quando o Affilentra é executado self‑hosted, a responsabilidade pela integridade do tracking, entrega de webhooks e pelos jobs de pagamento recai sobre o operador. Conversões em falta, jobs de payout atrasados ou processamento de webhooks com erros colocam em risco a receita e a confiança dos parceiros. Este playbook descreve passos pragmáticos e acionáveis: conversões sintéticas como checks end‑to‑end, métricas Prometheus para estado e desempenho e alerting através do Alertmanager com integrações PagerDuty/Slack para rápida escalada.
Visão geral: O que precisa de ser monitorizado
- Endpoint do tracker: receção de cliques/leads/encomendas e validação imediata.
- Entrega de webhooks: envio de notificações de conversão para comerciantes ou sistemas externos.
- Jobs de payout: execuções em batch, cálculo de comissões e processos de pagamento.
- Métricas de infraestrutura: latência, taxas de erro, ligações à base de dados, comprimento das filas.
Transações sintéticas: configurar verificações end‑to‑end
O objetivo é um teste automático e periódico que simule todo o percurso de uma conversão — desde o clique no tracker até à entrega do webhook e ao processamento do payout.
1. Criar identidades de teste e comerciantes de teste
Crie um ou vários parceiros de teste e comerciantes de teste na sua instância Affilentra. Essas contas devem ser claramente identificadas, com privilégios reduzidos e separadas dos dados de produção.
2. Definir o fluxo de simulação
Um fluxo típico:
- HTTP‑GET/POST ao endpoint do tracker com um link de tracking de teste.
- Aguardar o processamento interno; opcionalmente verificar se a conversão foi registada na BD.
- Verificar a entrega do webhook ao receptor de webhook de teste configurado.
- Disparar um job de payout (manual ou via API) e verificar a conclusão dos jobs.
3. Implementação técnica
Implemente o runner como um Cronjob, Kubernetes‑CronJob ou num serviço externo de Synthetic Monitoring. Componentes de exemplo:
- Um script leve (curl, Python, Go) executa requisições ao tracker e verifica o código HTTP e o payload da resposta.
- Um endpoint receiver aceita notificações de webhook e confirma a receção; o runner compara os eventos de webhook esperados com os reais.
- Opcional: validação em tabelas da base de dados através de um utilizador read‑only ou via API do Affilentra.
Importante: dados de teste não devem disparar comissões reais. Use flags de teste ou comerciantes de teste separados.
Prometheus: definir e expor métricas
O Prometheus é adequado para agregar indicadores de disponibilidade e desempenho. Dois abordagens:
- Métricas da Aplicação: Affilentra expõe um endpoint /metrics (ou um pequeno script PHP‑Exporter) com métricas centrais.
- Exporter/Proxies: Sidecar‑exporters externos recolhem latência e erros a partir de logs do servidor web, sistemas de fila ou Cron‑Runnables.
Métricas Recomendadas
- affilentra_tracker_requests_total{status="200|400|500"}
- affilentra_tracker_latency_seconds_bucket
- affilentra_webhook_deliveries_total{status="success|failure"}
- affilentra_webhook_retry_count
- affilentra_payout_jobs_total{state="running|failed|success"}
- affilentra_payout_job_duration_seconds
- affilentra_db_connections_current
- affilentra_queue_length
Exponha sempre latência (Histogram) e contadores de erros (Counters). Um intervalo de scrape de 15–30s é prático; intervalos mais longos para jobs não críticos.
Alertmanager: Regras e Escalações
Encaminhe alerts do Prometheus para o Alertmanager e configure receivers para PagerDuty e Slack.
Regras de Alerting Exemplares (Conceito)
- Erros do Tracker: Se tracker_errors_total em 5min > 1% das requests → Warning; > 5% em 5min → Critical.
- Falha de Webhook: Se webhook_failures_total em 10min > 3 → Critical.
- Latência de Webhook: Se webhook_latency_p95 > 2s durante 10min → Warning.
- Falha de Job de Pagamento: Se payout_jobs_failed_total > 0 em 15min → Critical.
- Acúmulo na Fila: Se affilentra_queue_length > threshold configurado → Warning.
Formule os alerts de modo a indicarem ações concretas (por exemplo, "Verifique o endpoint do Webhook, os últimos códigos de resposta e a fila de retries").
Integração com PagerDuty e Slack
O Alertmanager suporta múltiplos receivers. Configure:
- PagerDuty: Use a API‑Key do PagerDuty como receiver do Alertmanager para alerts Critical. Configure o roteamento para que Critical alerts apareçam imediatamente nas rotações on‑call.
- Slack: Envie Warnings e Incidents para canais dedicados; inclua links para o dashboard Grafana e para o runbook.
Teste o roteamento através de triggers direcionados: conversão sintética com respostas manipuladas, para verificar toda a cadeia.
Dashboards e Runbooks
Um dashboard (Grafana) deve conter os seguintes painéis:
- Tracker: Requests/sec, taxa de erros, latência p95/p99.
- Webhook: Taxa de deliveries, motivos de falha, fila de retries.
- Payout‑Jobs: Jobs em execução, duração, jobs falhados.
- Infraestrutura: Conexões DB, CPU, memória, comprimentos das filas.
Crie para cada alert crítico um runbook curto com: verificações iniciais, causas típicas, passos rápidos de remediação e como escalar um incidente. Lincar os runbooks diretamente nas mensagens do Slack e em incidents do PagerDuty.
Exemplos práticos: verificações rápidas
- Synthetic Tracker Check: POST HTTP ao tracker, verificar 200 e payload válido; em caso de erro → aumentar o nível de logging, verificar os logs do servidor web e as gravações na BD.
- Webhook Check: Webhook de teste recebe o evento; verificar assinatura/autenticação e código de estado 200; em caso de 4xx → verificar configuração, em caso de 5xx → contactar a parte recetora.
- Payout Job Check: Iniciar job em modo de teste; verificar se o job passa por queued → processed → completed dentro do tempo esperado.
Rollout e operação
Comece com um Minimum Viable Monitoring: Synthetic Runner + 5–8 métricas Prometheus + dois receivers do Alertmanager (PagerDuty, Slack). Intensifique gradualmente: mais métricas, alerts granulares, dashboards e remediação automatizada (ex.: reiniciar Background‑Worker via Kubernetes Job).
Recomendação final
Self‑hosting significa controlo — traduza esse controlo numa monitorização fiável. Com conversões sintéticas verifica-se a funcionalidade end‑to‑end; Prometheus fornece métricas observáveis; o Alertmanager com PagerDuty/Slack garante reação rápida. Assim, Affilentra pode ser operada proativamente: tracking transparente, webhooks fiáveis, pagamentos verificáveis.
Pronto para o próximo passo? Escolha o ponto de entrada e teste as Best Practices de monitorização diretamente na sua instância Affilentra: Einstieg wählen.
Próximo passo
Experimentar o Affilentra
Plataforma unificada que integra a disponibilização de produtos, tracking, validação de conversões, cálculo de comissões e pagamentos através de papéis claramente separados; opção de instalação self‑hosted com licença perpétua sem partilha de receitas; os comerciantes mantêm o controlo sobre produtos, condições e materiais promocionais; os parceiros recebem links de tracking pessoais e um histórico de pagamentos verificável.