How to use the QueuedTracking plugin

The QueuedTracking plugin is designed for Matomo On-Premise users who manage their own server resources. It helps handle medium to high traffic volumes by queuing tracking requests and processing them in controlled batches to reduce load and improve reliability. Without QueuedTracking, every tracking request is executed immediately, which can overload your server and cause data loss during traffic spikes.

When to use QueuedTracking

If your Matomo tracking server is failing to track because it is getting overwhelmed by requests, you can either pay more to increase server resources, or add our free plugin for Queued Tracking.

Once you add the queued tracking, the spikes will be less likely to overwhelm your server as all of the tracking requests are stored temporarily in a queue (MySQL or Redis). When the queue reaches a configurable threshold, requests are processed in bulk. The batched requests are then inserted into Matomo, ensuring tracking is not impacted even during heavy load.

How do I know that my server is being overwhelmed and failing to track?

To detect when your Matomo tracking server is overwhelmed, watch for an increase in HTTP code 500 responses (usually a sign of resource exhaustion, like threads, memory, or DB connections). Also check the response time of the HTTP code 200 responses, which will show increased latency as your Matomo server struggles to keep up.

How to install QueuedTracking

1. In Matomo, go to Administration > Platform > Marketplace.
2. Search for QueuedTracking.
3. Install and activate the plugin.
4. To configure the settings, choose the queue backend: MySQL or Redis.
   • MySQL: When enabled, additional tables (e.g., queuedtracking_queue) are created in your Matomo database to hold the queued requests. Requests are stored as binary files until processed. Learn more about how to configure Matomo to handle unexpected peak in traffic.
   • Redis: Recommended for very high traffic sites and it is generally faster than MySQL for queue operations, but both options are better than not queuing at all. To use Redis, it will need to be installed on your server. Learn how to configure Matomo to use Redis.
5. In the plugin settings, you can configure:
   • Number of queue workers: Defines how many parallel processes handle queued requests (higher values handle more traffic but use more CPU).
   • Batch size: Defines how many requests are processed at a time before being sent to Matomo.

For many sites, the default settings work well and are a good starting point, but everyone’s environment will have different optimal configurations.

Note the following exceptions:

Number of queue workers

This field accepts a number between 1 and 16. Best practice is to set the number of CPUs you want to make available for queue processing. Be aware you need to make sure to start the workers manually. It is recommended not to use 9-15 workers, instead use 8 or 16.

We can share that one customer who successfully queued up to 10,000 requests per second during traffic spikes had their configuration set for queue workers: 16 and number of requests to process: 25.

Process during Tracking Request

The last option is checked by default: Process during tracking request.

When you have multiple servers, it is recommended to disable this option and instead use a Cron (or in Windows, a Scheduled Task) to activate queue workers. The recommended method for this is to start a queue worker once every minute:

* * * * * php /path/to/matomo/console queuedtracking:process --no-ansi >/dev/null 2>&1

This should ensure that enough queue workers process the queue. You would execute this on each host that you want working on the queue (i.e. tracking servers). It’s fine to start this command from multiple different servers all working off the same database, as each queue worker will lock the table, take out the set number of requests, and then unlock the table for other queue workers to continue.

Troubleshooting

Read the guide on several useful commands that can be run from the CLI.

Redis

If you’ve optimised your configuration and performance is still unsatisfactory, consider switching from MySQL to Redis for better throughput. Redis stores the tracking queue in memory, making it much faster. However, because data is not persisted to disk, any queued requests will be lost if the server crashes.

Summary

With proper configuration, QueuedTracking can greatly improve the stability and reliability of your Matomo On-Premise setup. It also helps reduce hosting costs by smoothing out traffic spikes, so high-traffic data can be processed during low-traffic periods. This allows you to use a smaller, more cost-efficient server.

Get the plugin from the Matomo Marketplace and explore frequently asked questions about QueuedTracking.