Skip to content

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.

10 minutesDevOps, site ownersServer administrationSingle user · SaaS

What the worker does ​

JobQueueWhat it does
Recording batchRECORDINGS_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 copydefaultKeeps a copy of a stylesheet a recorded page used, so replays keep their look
AlertdefaultSends a matching alert by email, Slack or webhook
AnnouncementdefaultEmails an announcement to every user when the administrator chose to
HubSpotdefaultPuts the link to a visitor's latest replay on their HubSpot contact

Settings ​

.env keyDefaultWhat it does
QUEUE_CONNECTIONdatabase (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_QUEUEdefaultThe 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_MINUTE600Tracker 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_CLIENT127.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.

bash
sudo apt install -y supervisor
ini
; /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.log
bash
sudo supervisorctl reread && sudo supervisorctl update
sudo supervisorctl status replora-worker:*
  • numprocs is 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=3600 makes 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.target
bash
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=ingest

Then 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=60

php 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>&1
ini
# .env: process every batch inside the request that sends it
QUEUE_CONNECTION=sync

The 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:restart

Workers 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:

StatusMessageMeaning
WorkingWorkers keep up (database).Nothing waits longer than five minutes
WorkingJobs run at once, in the request (no worker needed).QUEUE_CONNECTION=sync
Needs attention3 jobs failed in the last 24 hours (php artisan queue:failed lists them).Some jobs failed three times
Failing120 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 them

Email ​

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.

Replora: see what your visitors see.