Introduction
Lorsque Affilentra est auto‑hébergé, la responsabilité de l'intégrité du suivi, de la livraison des webhooks et des tâches de paiement incombe à l'exploitant. Des conversions manquantes, des tâches de paiement retardées ou un mauvais traitement des webhooks mettent en péril le chiffre d'affaires et la confiance des partenaires. Ce playbook décrit des étapes pragmatiques et réalisables : conversions synthétiques comme contrôles de bout en bout, métriques Prometheus pour l'état et les performances ainsi que l'alerting via Alertmanager avec intégrations PagerDuty/Slack pour une escalade rapide.
Vue d'ensemble : Ce qu'il faut surveiller
- Endpoint du tracker : enregistrement des clics/leads/commandes et validation immédiate.
- Livraison des webhooks : envoi des notifications de conversion aux commerçants ou systèmes externes.
- Tâches de paiement : exécutions par lots, calcul des commissions et processus de versement.
- Métriques d'infrastructure : latence, taux d'erreur, connexions à la base de données, longueur des files d'attente.
Synthetic Transactions : mettre en place des vérifications de bout en bout
L'objectif est d'exécuter régulièrement et de manière automatisée un test qui simule le parcours complet d'une conversion — du clic via le tracker jusqu'à la livraison du webhook et le traitement du paiement.
1. Créer des identités de test et des marchands de test
Créez un ou plusieurs partenaires de test et marchands de test dédiés dans votre instance Affilentra. Ces comptes doivent être clairement identifiés, à privilèges réduits et séparés des données de production.
2. Définir le flux de simulation
Un flux type :
- HTTP‑GET/POST vers l'endpoint du tracker avec un lien de tracking de test.
- Attente du traitement interne ; contrôle optionnel que la conversion est bien enregistrée en base.
- Vérification de la livraison du webhook vers le récepteur de webhook de test configuré.
- Démarrage d'un job de paiement (manuellement ou via l'API) et vérification de l'achèvement du job.
3. Mise en œuvre technique
Implémentez le runner comme Cronjob, Kubernetes‑CronJob ou dans un service externe de Synthetic Monitoring. Composants d'exemple :
- Un script léger (curl, Python, Go) effectue les requêtes au tracker et vérifie le code HTTP et le payload de réponse.
- Un endpoint récepteur accepte les notifications webhook et confirme la réception ; le runner compare les événements webhook attendus avec ceux réellement reçus.
- Optionnel : validation dans les tables de la base de données via un utilisateur en lecture seule ou via l'API Affilentra.
Important : les données de test ne doivent déclencher aucune commission réelle. Utilisez des flags de test ou des marchands de test séparés.
Prometheus : définir et exposer des métriques
Prometheus convient pour l'agrégation des indicateurs de disponibilité et de performance. Deux approches :
- Métriques d'application : Affilentra expose un endpoint /metrics (ou un petit script PHP‑Exporter) avec les métriques principales.
- Exporter/Proxies : des sidecar externes collectent la latence et les erreurs issues des logs du serveur web, des systèmes de queue ou des tâches cron exécutables.
Métriques recommandées
- 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
Exposez dans tous les cas la latence (Histogram) et les compteurs d'erreurs (Counters). Un intervalle de scrape de 15–30s est pratique ; des intervalles plus longs sont acceptables pour les jobs non critiques.
Alertmanager : règles et escalades
Transférez les alerts de Prometheus vers Alertmanager et configurez des receivers pour PagerDuty et Slack.
Exemples de règles d'alerting (concept)
- Erreurs du tracker : si tracker_errors_total sur 5min > 1% des requêtes → Warning ; > 5% sur 5min → Critical.
- Échecs de webhook : si webhook_failures_total sur 10min > 3 → Critical.
- Latence webhook : si webhook_latency_p95 > 2s pendant 10min → Warning.
- Échec de job de payout : si payout_jobs_failed_total > 0 sur 15min → Critical.
- Remboursement de la file d'attente : si affilentra_queue_length > seuil configuré → Warning.
Formulez les alerts de manière à indiquer des actions concrètes (par ex. "Vérifier le endpoint webhook, les derniers codes de réponse et la file de retry").
Intégration avec PagerDuty et Slack
Alertmanager supporte plusieurs receivers. Configurez :
- PagerDuty : utilisez la clé API PagerDuty comme receiver d'Alertmanager pour les alerts Critical. Configurez le routage afin que les alerts Critical apparaissent immédiatement dans les rotations on‑call.
- Slack : envoyez les Warnings et incidents vers des channels dédiés ; ajoutez des liens vers le dashboard Grafana et vers le runbook.
Testez le routage par des déclencheurs ciblés : conversion synthétique avec réponses manipulées pour vérifier toute la chaîne.
Dashboards et runbooks
Un dashboard (Grafana) devrait contenir les panneaux suivants :
- Tracker : requêtes/sec, taux d'erreur, latence p95/p99.
- Webhook : taux de delivery, raisons des erreurs, file de retry.
- Payout‑Jobs : jobs en cours, durée, jobs échoués.
- Infrastructure : connexions DB, CPU, mémoire, longueurs de file d'attente.
Créez pour chaque alert critique un runbook court comprenant : contrôles initiaux, causes typiques, actions correctives rapides et procédure d'escalade d'incident. Liez les runbooks directement dans les messages Slack et les incidents PagerDuty.
Exemples pratiques : vérifications rapides
- Vérification Synthetic Tracker : POST HTTP vers le Tracker, vérifier 200 + payload valide ; en cas d'erreur → augmenter le niveau de logging, vérifier les logs du serveur web et les écritures en base de données.
- Vérification Webhook : un webhook de test reçoit l'événement ; vérifier la signature/authentification et le code d'état 200 ; en cas de 4xx → vérifier la configuration, en cas de 5xx → contacter le côté récepteur.
- Vérification du job Payout : lancer le job en mode test ; vérifier si le job passe par queued → processed → completed dans le délai attendu.
Déploiement et exploitation
Démarrez avec un Minimum Viable Monitoring : Synthetic Runner + 5–8 métriques Prometheus + deux receivers Alertmanager (PagerDuty, Slack). Intensifiez progressivement : plus de métriques, alertes plus granulaires, dashboards et remédiation automatisée (par ex. redémarrage d'un Background‑Worker via un Job Kubernetes).
Recommandation finale
Le self‑hosting signifie contrôle — transformez ce contrôle en surveillance fiable. Les conversions synthétiques vérifient la fonctionnalité de bout en bout ; Prometheus fournit des mesures observables ; Alertmanager avec PagerDuty/Slack assure une réaction rapide. Affilentra peut ainsi être exploité de manière proactive : tracking transparent, webhooks fiables, paiements vérifiables.
Prêt pour l'étape suivante ? Choisissez votre point d'entrée et testez les bonnes pratiques de monitoring directement dans votre instance Affilentra : Einstieg wählen.
Étape suivante
Tester Affilentra soi‑même
Plateforme unifiée qui rassemble de manière transparente la mise en production des produits, le tracking, la validation des conversions, le calcul des commissions et les paiements selon des rôles clairement séparés ; option d'installation self‑hosted avec licence perpétuelle sans partage de chiffre d'affaires ; les marchands conservent le contrôle des produits, des conditions et des supports publicitaires ; les partenaires reçoivent des liens de tracking personnels et un historique de paiements consultable.