Introducción
Cuando Affilentra se ejecuta self‑hosted, la responsabilidad de la integridad del seguimiento, la entrega de webhooks y los trabajos de pago recae en el operador. Conversiones faltantes, trabajos de pago retrasados o el procesamiento defectuoso de webhooks ponen en riesgo los ingresos y la confianza de los socios. Este playbook describe pasos pragmáticos y accionables: conversiones sintéticas como comprobaciones de extremo a extremo, métricas Prometheus para estado y rendimiento, y alertas mediante Alertmanager con integraciones PagerDuty/Slack para una rápida escalación.
Resumen: Qué debe supervisarse
- Endpoint del tracker: recepción de clics/leads/pedidos y validación inmediata.
- Entrega de webhooks: envío de notificaciones de conversión a comerciantes o sistemas externos.
- Trabajos de pago: ejecuciones por lotes, cálculo de comisiones y procesos de pago.
- Métricas de infraestructura: latencia, tasas de error, conexiones a la base de datos, longitud de colas.
Transacciones sintéticas: configurar comprobaciones de extremo a extremo
El objetivo es una prueba periódica y automatizada que simule el recorrido completo de una conversión —desde el clic en el tracker hasta la entrega del webhook y el tratamiento del pago.
1. Crear identidades de prueba y comerciantes de prueba
Cree uno o varios socios de prueba y comerciantes de prueba dedicados en su instancia de Affilentra. Estas cuentas deben estar claramente etiquetadas, tener privilegios reducidos y estar separadas de los datos de producción.
2. Definir el flujo de simulación
Un flujo típico:
- HTTP‑GET/POST al endpoint del tracker con un enlace de tracking de prueba.
- Esperar el procesamiento interno; comprobación opcional de que la conversión se haya registrado en la BD.
- Verificar la entrega del webhook al receptor de webhook de prueba configurado.
- Disparar un trabajo de pago (manualmente o vía API) y verificar la finalización del trabajo.
3. Implementación técnica
Implemente el runner como un Cronjob, Kubernetes‑CronJob o en un servicio externo de Synthetic Monitoring. Componentes de ejemplo:
- Un script ligero (curl, Python, Go) realiza las solicitudes al tracker y comprueba el código HTTP y la carga útil de la respuesta.
- Un receptor endpoint acepta las notificaciones de webhook y confirma la recepción; el runner compara los eventos de webhook esperados con los reales.
- Opcional: validación en tablas de la base de datos mediante un usuario read‑only o a través de la API de Affilentra.
Importante: los datos de prueba no deben disparar comisiones reales. Use flags de prueba o comerciantes de prueba separados.
Prometheus: definir y exponer métricas
Prometheus es adecuado para la agregación de métricas de disponibilidad y rendimiento. Dos enfoques:
- Métricas de la aplicación: Affilentra expone un endpoint /metrics (o un pequeño script PHP‑Exporter) con métricas clave.
- Exportadores/Proxies: Exportadores sidecar externos recopilan latencia y errores a partir de logs del servidor web, sistemas de colas o tareas Cron.
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
Exponga en cualquier caso latencia (Histograma) y contadores de errores (Counters). Un intervalo de scrape de 15–30s es práctico; intervalos más largos para trabajos no críticos.
Alertmanager: reglas y escalados
Encamine las alertas de Prometheus a Alertmanager y configure receptores para PagerDuty y Slack.
Reglas de alertas ejemplares (concepto)
- Errores del tracker: Si tracker_errors_total en 5min > 1% de las solicitudes → Warning; > 5% en 5min → Critical.
- Fallo de webhook: Si webhook_failures_total en 10min > 3 → Critical.
- Latencia de webhook: Si webhook_latency_p95 > 2s durante 10min → Warning.
- Fallo de job de pago: Si payout_jobs_failed_total > 0 en 15min → Critical.
- Retraso en la cola: Si affilentra_queue_length > umbral configurado → Warning.
Formule las alertas de modo que indiquen acciones concretas a tomar (p. ej. "Revise el endpoint del webhook, los últimos códigos de respuesta y la cola de reintentos").
Integración con PagerDuty y Slack
Alertmanager admite múltiples receptores. Configure:
- PagerDuty: Use la API‑Key de PagerDuty como receptor de Alertmanager para alertas Critical. Configure el enrutamiento de forma que las alertas Critical aparezcan inmediatamente en las rotaciones on‑call.
- Slack: Envíe Warnings e incidents a canales dedicados; añada enlaces al dashboard de Grafana y al runbook.
Pruebe el enrutamiento mediante disparadores dirigidos: conversiones sintéticas con respuestas manipuladas para verificar toda la cadena.
Dashboards y runbooks
Un dashboard (Grafana) debería contener los siguientes paneles:
- Tracker: Requests/sec, tasa de errores, latencia p95/p99.
- Webhook: tasa de entregas, motivos de fallo, cola de reintentos.
- Jobs de pago: trabajos en ejecución, duración, trabajos fallidos.
- Infraestructura: conexiones a la BD, CPU, memoria, longitudes de colas.
Para cada alerta crítica, cree un runbook breve con: comprobaciones iniciales, causas típicas, pasos rápidos de remediación y cómo escalar un incidente. Vincule los runbooks directamente en los mensajes de Slack y en los incidents de PagerDuty.
Ejemplos prácticos: comprobaciones rápidas
- Comprobación Synthetic Tracker: HTTP POST al tracker, compruebe 200 + payload válido; en caso de error → aumente el nivel de logging, revise los logs del servidor web y las escrituras en la BD.
- Comprobación de Webhook: Webhook de prueba recibe evento; compruebe firma/autenticación y código de estado 200; en caso de 4xx → revisar configuración, en caso de 5xx → contactar con el receptor.
- Comprobación de Payout Job: Inicie el job en modo prueba; verifique si el job pasa de queued → processed → completed dentro del tiempo esperado.
Despliegue y operación
Comience con un Minimum Viable Monitoring: Synthetic Runner + 5–8 métricas de Prometheus + dos receptores de Alertmanager (PagerDuty, Slack). Intensifique de forma gradual: más métricas, alertas granulares, paneles y remediación automatizada (p. ej., reinicio de Background‑Worker mediante un Job de Kubernetes).
Recomendación final
El self‑hosting implica control — convierta ese control en una supervisión fiable. Con conversiones sintéticas compruebe la funcionalidad de extremo a extremo; Prometheus proporciona métricas observables; Alertmanager con PagerDuty/Slack garantiza una respuesta rápida. Affilentra puede operarse de forma proactiva: tracking transparente, webhooks fiables, payouts verificables.
¿Listo para el siguiente paso? Elija el punto de partida y pruebe las buenas prácticas de monitorización directamente en su instancia de Affilentra: Elegir punto de partida.
Paso siguiente
Probar Affilentra por sí mismo
Plataforma unificada que reúne de forma transparente la puesta a disposición de producto, tracking, validación de conversiones, cálculo de comisiones y pagos a lo largo de roles claramente separados; opción de instalación self‑hosted con licencia perpetua sin participación en los ingresos; los comerciantes conservan el control sobre productos, condiciones y materiales promocionales; los partners reciben enlaces de tracking personales e historial de pagos trazable.