Introduction
When Affilentra is self-hosted, the operator is responsible for tracking integrity, webhook delivery and payout jobs. Missing conversions, delayed payout jobs, or faulty webhook processing jeopardize revenue and partner trust. This playbook describes pragmatic, actionable steps: synthetic conversions as end-to-end checks, Prometheus metrics for health and performance, and alerting via Alertmanager with PagerDuty/Slack integrations for rapid escalation.
Overview: What needs to be monitored
- Tracker endpoint: intake of clicks/leads/orders and immediate validation.
- Webhook delivery: delivery of conversion notifications to merchants or external systems.
- Payout jobs: batch runs, commission calculation and payout processing.
- Infrastructure metrics: latency, error rates, database connections, queue length.
Synthetic Transactions: setting up end-to-end checks
The goal is a regular, automated test run that simulates the complete path of a conversion — from click through the tracker to webhook delivery and payout processing.
1. Create test identities and test merchants
Create one or more dedicated test partners and test merchants in your Affilentra instance. These accounts should be clearly labeled, low-privilege and separated from production data.
2. Define the simulation flow
A typical flow:
- HTTP GET/POST to the tracker endpoint with a test tracking link.
- Wait for internal processing; optionally verify that the conversion is recorded in the DB.
- Verify webhook delivery to the configured test webhook receiver.
- Trigger a payout job (manually or via API) and verify job completion.
3. Technical implementation
Implement the runner as a cronjob, Kubernetes CronJob, or in an external synthetic monitoring service. Example components:
- A lightweight script (curl, Python, Go) issues tracker requests and checks HTTP status code and response payload.
- An endpoint receiver accepts webhook notifications and acknowledges receipt; the runner compares expected with actual webhook events.
- Optional: validation against database tables using a read-only DB user or via the Affilentra API.
Important: test data must not trigger real payouts. Use test flags or separate test merchants.
Prometheus: defining and exposing metrics
Prometheus is suitable for aggregating availability and performance metrics. Two approaches:
- Application Metrics: Affilentra exposes a /metrics‑endpoint (or a small PHP‑exporter‑script) with core metrics.
- Exporter/Proxies: External sidecar exporters collect latency and errors from webserver logs, queue systems or cron runnables.
Recommended metrics
- 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
In any case, expose latency (Histogram) and error counters (Counters). A scrape interval of 15–30s is practical; longer intervals for non‑critical jobs.
Alertmanager: rules and escalations
Forward alerts from Prometheus to Alertmanager and configure receivers for PagerDuty and Slack.
Example alerting rules (concept)
- Tracker errors: If tracker_errors_total in 5min > 1% of requests → Warning; > 5% in 5min → Critical.
- Webhook failure: If webhook_failures_total in 10min > 3 → Critical.
- Webhook latency: If webhook_latency_p95 > 2s for 10min → Warning.
- Payout job failure: If payout_jobs_failed_total > 0 in 15min → Critical.
- Queue backlog: If affilentra_queue_length > configured threshold → Warning.
Phrase alerts so they point to concrete actions (e.g. "Check webhook endpoint, recent response codes and retry queue").
Integration with PagerDuty and Slack
Alertmanager supports multiple receivers. Configure:
- PagerDuty: Use the PagerDuty API key as an Alertmanager receiver for Critical alerts. Set routing so Critical alerts appear immediately in the on‑call rotations.
- Slack: Send Warnings and incidents to dedicated channels; include links to the Grafana dashboard and the runbook.
Test routing by targeted triggers: synthetic conversion with manipulated responses to exercise the entire chain.
Dashboards and runbooks
A dashboard (Grafana) should contain the following panels:
- Tracker: Requests/sec, error rate, p95/p99 latency.
- Webhook: Delivery rate, failure reasons, retry queue.
- Payout jobs: Running jobs, duration, failed jobs.
- Infrastructure: DB connections, CPU, memory, queue lengths.
Create a short runbook for each critical alert with: initial checks, common causes, quick remediation steps, and how to escalate an incident. Link runbooks directly in Slack messages and PagerDuty incidents.
Practical examples: Quick checks
- Synthetic Tracker Check: HTTP POST to Tracker, verify 200 + valid payload; on error → increase logging level, check webserver logs and DB writes.
- Webhook Check: Test webhook receives event; verify signature/authentication and 200 status code; on 4xx → check configuration, on 5xx → contact receiver side.
- Payout Job Check: Start job in test mode; verify that job goes from queued → processed → completed within expected time.
Rollout and operations
Start with a Minimum Viable Monitoring: Synthetic Runner + 5–8 Prometheus metrics + two Alertmanager receivers (PagerDuty, Slack). Intensify gradually: more metrics, granular alerts, dashboards and automated remediation (e.g. restart background worker via Kubernetes Job).
Final recommendation
Self-hosting means control — you should translate that control into reliable monitoring. With synthetic conversions you check end-to-end functionality; Prometheus provides observable metrics; Alertmanager with PagerDuty/Slack ensures fast response. This allows operating Affilentra proactively: transparent tracking, reliable webhooks, verifiable payouts.
Ready for the next step? Choose your entry and test monitoring best practices directly in your Affilentra instance: Choose entry.
Next step
Try Affilentra yourself
A unified platform that transparently brings together product provisioning, tracking, conversion validation, commission calculation and payout across clearly separated roles; option for self-hosted installation with perpetual license without revenue sharing; merchants retain control over products, terms and promotional materials; partners receive personal tracking links and a traceable payout history.