Appearance
Background worker & email
The tracking script's batches are not processed while the visitor waits: the ingest endpoint checks them and puts them on a queue, and a background worker turns them into sessions, replays, heatmaps and reports. Without a running worker, new recordings don't appear. This page shows how to keep it running.
What the worker does
| Job | Queue | What it does |
|---|---|---|
| Recording batch | RECORDINGS_INGEST_QUEUE (default unless you change it) | Unpacks a batch, writes the events to recording storage, updates the session, pages, heatmaps, forms, errors, events, funnels and insights. 3 tries (after 5 and 30 seconds) |
| Stylesheet copy | default | Keeps a copy of a stylesheet a recorded page used, so replays keep their look |
| Alert | default | Sends a matching alert by email, Slack or webhook |
| Announcement | default | Emails an announcement to every user when the administrator chose to |
| HubSpot | default | Puts the link to a visitor's latest replay on their HubSpot contact |
Settings
.env key | Default | What it does |
|---|---|---|
QUEUE_CONNECTION | database (written by the installer) | Where jobs wait: database (the jobs table, nothing else to install), redis (recommended for high volume), or sync (no queue: jobs run inside the request, no worker needed) |
RECORDINGS_INGEST_QUEUE | default | The queue recording batches go to. Set it to ingest on busy sites so a burst of recordings never delays alerts and emails, and run separate workers for it |
RECORDINGS_INGEST_PER_MINUTE | 600 | Tracker requests accepted per minute from one IP address (a visitor sends about 12 a minute, so 600 covers about 50 visitors behind one office or mobile network address) |
REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_CLIENT | 127.0.0.1, 6379, null, phpredis (as shipped in .env.example) | The Redis server, when QUEUE_CONNECTION=redis (also used for cache and sessions, see Scaling) |
After changing any of them run php artisan config:clear (if you cache configuration) and php artisan queue:restart.
Supervisor (recommended on a VPS)
bash
sudo apt install -y supervisorini
; /etc/supervisor/conf.d/replora-worker.conf
[program:replora-worker]
command=php /var/www/replora/artisan queue:work --sleep=1 --tries=3 --max-time=3600
user=www-data
numprocs=2
process_name=%(program_name)s_%(process_num)02d
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stopwaitsecs=60
stdout_logfile=/var/www/replora/storage/logs/worker.logbash
sudo supervisorctl reread && sudo supervisorctl update
sudo supervisorctl status replora-worker:*numprocsis the number of workers. Two are plenty for a few thousand sessions a day; add more when the Background jobs check reports waiting jobs.--max-time=3600makes each worker exit after an hour; Supervisor starts a fresh one, which keeps memory in check.
systemd (without Supervisor)
ini
# /etc/systemd/system/[email protected]
[Unit]
Description=Replora queue worker %i
After=network.target postgresql.service
[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/replora
ExecStart=/usr/bin/php artisan queue:work --sleep=1 --tries=3 --max-time=3600
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.targetbash
sudo systemctl daemon-reload
sudo systemctl enable --now replora-worker@1 replora-worker@2
systemctl status 'replora-worker@*'A separate queue for recordings
On busy sites keep recording batches apart from everything else. In .env:
ini
RECORDINGS_INGEST_QUEUE=ingestThen run two pools of workers: a larger one for ingest and a small one for the rest:
ini
; /etc/supervisor/conf.d/replora-worker.conf
[program:replora-ingest]
command=php /var/www/replora/artisan queue:work --queue=ingest --sleep=1 --tries=3 --max-time=3600
user=www-data
numprocs=4
process_name=%(program_name)s_%(process_num)02d
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stopwaitsecs=60
[program:replora-worker]
command=php /var/www/replora/artisan queue:work --sleep=3 --tries=3 --max-time=3600
user=www-data
numprocs=1
process_name=%(program_name)s_%(process_num)02d
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stopwaitsecs=60php artisan replora:doctor recommends this when RECORDINGS_INGEST_QUEUE is still default, and prints the two worker commands for your settings.
Shared hosting: no long-running processes
Most shared hosts stop programs that keep running. Use one of these instead of Supervisor:
bash
# cPanel › Cron Jobs, once per minute, next to the schedule:run entry
cd /home/USER/replora && php artisan queue:work --stop-when-empty --max-time=55 >> /dev/null 2>&1ini
# .env: process every batch inside the request that sends it
QUEUE_CONNECTION=syncThe cron worker starts every minute, works through what is waiting and exits before the next one starts. With sync, nothing waits at all, but each tracker request takes longer; fine for low traffic, not for busy sites.
Restarting workers after changes
A running worker keeps the code and configuration it started with. After editing .env or uploading new files, run:
bash
php artisan queue:restartWorkers finish their current job and exit; Supervisor or systemd starts them again with the new code. Updates (the System page's Update now and php artisan replora:upgrade) do this for you.
Is it working?
Administration › System › Service status › Background jobs:
| Status | Message | Meaning |
|---|---|---|
| Working | Workers keep up (database). | Nothing waits longer than five minutes |
| Working | Jobs run at once, in the request (no worker needed). | QUEUE_CONNECTION=sync |
| Needs attention | 3 jobs failed in the last 24 hours (php artisan queue:failed lists them). | Some jobs failed three times |
| Failing | 120 jobs are waiting, the oldest for 14 minutes: is a queue worker running? | No worker runs (database queue), or too few |
Also check Recordings arriving: Nothing arrived for 2 days: is the tracking code still on your websites? (after a day without recordings)
From the command line:
bash
php artisan queue:monitor database:default,database:ingest # waiting jobs per queue
php artisan queue:failed # list failed jobs
php artisan queue:retry all # try them again
php artisan queue:flush # forget themEmail
Emails (invitations, password resets, alerts, service warnings, and in the SaaS edition sign-up confirmations, trial reminders and ticket replies) are delivered with the settings in Settings › Installation › Email delivery: an SMTP server, Mailgun, SendGrid or this server's sendmail, with the From address and From name. Until you choose one, Don’t send (write to the log) writes them to storage/logs/laravel.log. The same can be set with the MAIL_* keys in .env; dashboard settings win. See Email delivery.
