If you have a large Matomo (Piwik) instance, upgrading to the latest Matomo version may take a long time (if one of the newest Matomo releases include database schema changes).

To upgrade your large Matomo (Piwik) instance, follow the manual three step procedure. This includes putting Matomo UI and Tracker in maintenance mode, and run the core:update command in the console. While Matomo Tracker is in maintenance mode, no data is being collected in the database. Therefore you may lose data for the few hours when Matomo was in maintenance.

This FAQ explains how to import the missing tracking requests in Matomo (Piwik).

You have two options.

Option 1

During maintenance, visitors on your websites and mobile apps are still issuing the tracking requests. These piwik.php? tracking requests are stored in your Matomo (Piwik) server access logs files. Once the upgrade to the latest Matomo version is successful, you can create a new log file that contains all these piwik.php requests (for the time window that Matomo was in maintenance mode and not tracking).

Then you can replay this log file in Matomo (Piwik) which will backfill all your data: learn more in this FAQ.

Option 2

The second option requires the use of the QueuedTracking plugin with Redis.

  1. Install and setup QueuedTracking plugin.
  2. Enable writing requests into Redis
  3. Start Matomo (Piwik) upgrade
  4. Finish Matomo (Piwik) upgrade
  5. Process all requests from Redis into DB to backfill all your data (via ./console queuedtracking:process console command)
  6. Disable QueuedTracking plugin (Redis) again
  7. Matomo (Piwik) normal behavior resumes

If you have any feedback or suggestion, please leave a comment below.