Console Command to Manually Reset Stuck Invalidation Records

[sgiehl]

Background

In the current Matomo archiving process, invalidations that need to be processed are marked as "started" when processing begins. However, if the process is interrupted due to events such as server crashes or restarts, these invalidations may remain in the "started" state indefinitely.

Although the system is designed to automatically restart such invalidations if they have been in the "started" state for more than 24 hours, this delay can result in outdated aggregated data, potentially causing inconvenience to users and administrators.

Proposed Solution

To provide administrators with a more immediate and flexible way to handle stuck invalidations, we propose implementing a new console command that allows manual resetting of invalidation records without directly modifying the database.

Command Capabilities

The proposed command should offer the following features:

• Reset stuck invalidations

  • Unset the "started" status of invalidations to allow reprocessing.

• Filtering options to target specific invalidations, including:

  • --processing-host: Specify the hostname of the archiving server.
  • --idSite: Limit the reset operation to a specific site.
  • --date-range: Define a range of start times to narrow down affected invalidations.

Use Case Example

Consider a scenario where an archiving server crashes, leaving several invalidations in a "started" state. Instead of waiting for the automatic 24-hour reset, an administrator could manually run the proposed console command to clear invalidation states for the affected host, ensuring timely data aggregation and reporting.

Implementation Considerations

• The command should include safeguards such as confirmation prompts or dry-run modes to prevent accidental modifications.

refs / requires #22970