Sentinel

Overview

Tracking rarely breaks with an error message. A new consent banner, a tag manager change or a relaunch without the tracking code, and Matomo simply records fewer visits or no conversions at all. Usually nobody notices until the monthly report, and the missing data cannot be recovered.

Sentinel checks every website's data every hour and compares it with what is normal for that very website: the median of the same weekday and hour over the last 8 weeks. When tracking looks broken, Sentinel alerts you by email, Slack, Microsoft Teams or webhook, and sends an all-clear once the data looks normal again. Because Sentinel reads the raw tracking data, late archiving never looks like an outage.

The checks

• No visits (critical): no visits for some hours (default 3), although the website usually has enough at that time.
• Drop in visits (critical): a day with far fewer visits than the same weekday usually has.
• Goal no longer converts (warning): a goal that usually converts, or the orders of an online shop, without a conversion for some days (default 2).
• Unusual spike (bots, spam) (warning): far more visits than usual together with signs of bots or spam, such as a very high bounce rate, very short visits, one country or provider dominating, or a new referrer.
• Actions per visit off (warning): actions per visit change sharply, a sign of pageviews tracked twice or not at all.
• Tracking failures (warning): Matomo rejects tracking requests (unknown site ID, missing authentication).
• Archiving (warning): archiving does not keep the reports up to date, or a large website is archived in the browser.
• CNIL exemption on a German site (note): Matomo's CNIL policy is active for a website that targets Germany.

You choose for each website which checks run and how sensitive they are.

Alarms without the flood

Sentinel sends one alarm when a problem starts and one all-clear when it is over, with no repeats in between. When a website gets no visits at all, the follow-up alarms wait instead of flooding your inbox. Critical alarms always go out immediately, warnings can be collected into a daily report at 8:00 site time, and notes are only shown in Matomo. Quiet periods hold back new incidents during maintenance, and every alarm email has an unsubscribe link for its recipient.

At a glance in Matomo

• Visitors → Tracking health: health score from 0 to 100, open incidents and the last 30 days, also as a dashboard widget.
• Administration → Diagnostic → Sentinel: checks, recipients, webhooks, quiet periods and test message per website.
• Administration → Diagnostic → System Check: time of Sentinel's last run and open incidents.

Privacy

Sentinel stores hourly visit counts per website (no personal data, kept 70 days) and the incidents it finds, all in your Matomo database. It sends no data anywhere, only alarms to the email addresses and webhooks you enter.

Requirements

Matomo 5.0 or newer, PHP 8.1 or newer and Matomo's cron job (core:archive) or browser-triggered tasks, since Sentinel runs every hour as a scheduled task.

The optional add-on Sentinel Pro adds forecasts as expected values, public holidays per website, checks for single channels and conversion rates, and an external watchdog.

Use cases

• Notice outages within hours, not weeks: Sentinel checks every hour. When a website stops receiving visits, the alarm arrives a few hours later, not when someone opens the monthly report.
• Measured against your website's normal: Every website is compared with itself: the same weekday and hour over the last 8 weeks. Quiet nights and weekends do not raise alarms.
• Goals and shop orders covered: "Goal no longer converts" reports goals that usually convert and online shops that no longer record orders.
• Bots, spam and double pageviews: Unusual spikes with signs of bots and sharp changes in actions per visit stand out before they distort your reports.
• Alarms where your team works: Email to the website's administrators and any addresses you add, plus webhooks for Slack, Microsoft Teams or any system that accepts JSON.
• Calm instead of alarm floods: One alarm when a problem starts, one all-clear when it is over. Warnings as a daily report if you like, quiet periods for maintenance or a closed shop.
• Archiving and tracking failures too: Sentinel tells you when archiving no longer keeps reports up to date or Matomo rejects tracking requests.
• Free and open source: GPL v3 or later. All data stays in your Matomo database.

Sentinel watches the tracking data of your websites in Matomo and alerts you as soon as tracking looks broken: missing visits, sudden drops, goals without conversions, bot spikes and archiving problems. It checks every website every hour, compares it with its own normal values and alerts you by email, Slack, Microsoft Teams or webhook. When the problem is over, an all-clear follows.

Step-by-step setup

Installation and activation are covered in Installing plugins. Sentinel needs Matomo 5.0 or newer and PHP 8.1 or newer. Sentinel's page needs admin access to at least one website; the settings of the whole instance need super user access.

1. Install Sentinel

With the connector, open Administration → Plugins → Feinwerk Plugins and click Install next to Sentinel. The connector downloads the matching version, installs and activates it. Without the connector, get the ZIP file via Download ZIP on the plugin page, upload it in Matomo and activate Sentinel under Administration → Plugins → Manage Plugins or on the command line:

./console plugin:activate FeinwerkSentinel

Before activating on an instance with real data: by default the administrators of each website receive the alarms (or the super users, if a website has none). The first run reads up to 8 weeks of past visits per website, spread over several runs on large instances, and may already find problems of the past days. So check the recipients right after activation (step 5).

2. Keep scheduled tasks running

Sentinel checks every hour as one of Matomo's scheduled tasks, so it only runs while Matomo's cron job (core:archive) or browser-triggered tasks run. The cron job is recommended: without it, Sentinel runs only when someone opens Matomo. If Sentinel has not run for over two hours, Tracking health shows a hint and the System Check shows a warning.

3. Open Sentinel's page

Open Administration → Diagnostic → Sentinel. The page is available to every user with admin access to at least one website and lists only their websites. At the top, choose the website to configure under Website. All of the following settings apply to that one website.

4. Choose checks and thresholds

Under Checks every check is listed with its Severity and Settings. Each check can be switched on or off for the website; all are on by default.

• No visits (Critical): Hours without visits (default 3) and At least expected (default 20). No alarm when fewer visits are expected in that time.
• Drop in visits (Critical): Sensitivity (k) (default 4) and Share of the usual value (default 0.5: an alarm needs fewer than half of the usual visits).
• Goal no longer converts (Warning): Days without conversion (default 2) and At least expected (default 3 conversions). Applies to every goal that usually converts and, for online shops, to the Shop orders as well.
• Unusual spike (bots, spam) (Warning): Sensitivity (k) (default 4). An alarm needs more visits than usual plus signs of bots or spam: a very high bounce rate, very short visits, one country or provider suddenly dominating, or a new referrer sending many visits.
• Actions per visit off (Warning): Sensitivity (k) (default 4) and Minimum change (default 0.4: the value must change by at least 40 %).
• Tracking failures (Warning): no settings. Reports when Matomo rejects tracking requests for this website (unknown site ID, missing authentication).
• CNIL exemption on a German site (Note): no settings. A hint when Matomo's CNIL policy is active for a website that targets Germany.

For Sensitivity (k), higher values alarm less often; 4 is a good start. The Archiving check exists once for the whole instance and is set up in step 9.

5. Choose email recipients

In the Email section:

• Notify the administrators of this website (if it has none: the super users): on by default. Every administrator receives the emails in the language they chose in Matomo.
• Additional email addresses: one address per line, at most 20.
• Send warnings as a daily report: warnings are collected and sent once a day at 8:00 (site time). Critical alarms always go out immediately; notes are only shown in Matomo.

Anyone who unsubscribed via the link in an alarm email is listed here under Unsubscribed via the link in an alarm mail. Add again makes them receive alarms again (see "Good to know").

6. Webhooks for Slack, Microsoft Teams and other systems

In the Webhooks (Slack, Microsoft Teams, others) section, click Add webhook and enter the URL, the Format and optionally a Secret. Up to 5 webhooks per website are possible.

• Slack: the URL of an incoming webhook.
• Microsoft Teams: the URL of a workflow "When a Teams webhook request is received".
• Generic JSON: for any other system. Each alarm arrives as a JSON object with, among others, event, site, check, severity, state (open, resolved or test), message, started_at, resolved_at and report_url.

With a secret, every request carries the header X-Fw-Sentinel-Signature: sha256=<HMAC>, an HMAC SHA-256 of the body with your secret (at most 200 characters). The receiving system uses it to verify that the message comes from your Matomo. Only https addresses on the internet are allowed, without a user name or password in the URL; Sentinel rejects addresses in internal networks.

7. Add quiet periods

Under Quiet periods Sentinel opens no new incidents for certain times, for example a planned maintenance or a closed shop. All times are in the website's time zone.

• Every week: Add weekly period lets you choose Days, From and To, for example Sundays from 2:00 to 6:00. To 24:00 means until the end of the day.
• Once: Add period takes the date and time of a single period in From and To, for example for a relaunch or a company holiday.

Sentinel does not take public holidays into account automatically.

8. Save and send a test message

Click Save. Then Send test message sends a test to all recipients and webhooks of the website, exactly the way real alarms will arrive. The test message uses the saved settings; wait a minute between two test messages. Matomo confirms how many email addresses and webhooks it went to.

9. Settings of the whole instance

Super users find these under Administration → System → General settings → Feinwerk Sentinel (FeinwerkSentinel) (linked from Sentinel's page via Settings of the whole instance):

• Archiving: alarm after how many hours without a complete run (default 6, allowed 1 to 168). Matomo should run core:archive at least every hour; 6 hours avoids alarms for single slow runs.
• Archiving: visits per day from which browser archiving is too slow (default 10,000). With browser-triggered archiving, websites above this value lead to a hint to set up the cron job.
• Notify super users (default on): super users receive the alarms of the whole instance, such as archiving problems, and the alarms of websites without an administrator.
• Additional email addresses for alarms of the whole instance: one per line.
• Webhook for alarms of the whole instance, with Format of this webhook and Secret for the signature (optional): as in step 6, https only.
• Maximum run time per hour in seconds (default 120, allowed 10 to 3,600). Large instances with many websites may need more. Work that does not fit into one run continues in the next.

10. Keep an eye on tracking health

Under Visitors → Tracking health Sentinel shows for the selected website:

• the health from 0 to 100: 100 minus 40 for each open critical incident, 15 for each warning and 5 for each note,
• the open incidents, each with its start,
• the time of the last check,
• the health of the last 30 days,
• for super users, the open incidents of the whole Matomo instance, such as archiving problems.

Administrators of the website get to Sentinel's page straight from Sentinel settings. Tracking health is also available as a dashboard widget. Everyone with view access to the website can see it.

Practical examples

Relaunch without the tracking code. A new version of the website goes live in the morning, and the tracking snippet is missing from the new template. After three hours without visits, No visits opens a critical incident and alerts the administrators and the Slack channel. The follow-up alarms for drops and goals wait as long as no visits arrive at all. Once the code is back, the all-clear follows.

Consent banner after an update. After an update, tracking starts for only a small share of visitors. Visits still arrive, but far fewer. The next morning Drop in visits reports that the previous day had only a fraction of that weekday's usual visits, with the measured and the expected value.

Form goal after a tag manager change. The thank-you page of a contact form has a new URL, and the goal no longer matches. After two days without a conversion, Goal no longer converts reports the goal by name. For online shops the same applies to the orders.

Maintenance every Sunday. A shop is serviced every Sunday from 2:00 to 6:00. A weekly quiet period for those hours prevents alarms. The team receives warnings as a daily report at 8:00, while critical alarms still go out immediately.

Good to know

• How Sentinel compares: "usual" means the median of the same weekday and hour over the last 8 weeks. Statistical checks start after three weeks of data. Websites with very little traffic are not judged, to avoid false alarms. No visits and Goal no longer converts check every hour; Drop in visits, Unusual spike and Actions per visit off judge completed days.
• Raw data, not reports: Sentinel reads Matomo's raw tracking data, so late or failed archiving never looks like missing visits; the Archiving check covers that separately.
• One alarm per problem: one alarm when a problem starts, one all-clear when it is over, no repeats. Where it fits, alarms name the measured and the expected value and link to the report in Matomo.
• Unsubscribing and adding people again: every alarm email has an unsubscribe link for its recipient and website. The link opens the page Unsubscribe from Sentinel alarms, and a click on Unsubscribe confirms. From then on the person receives no alarms for that website, even as an administrator or a listed address. On Sentinel's page they appear under Unsubscribed via the link in an alarm mail, and an administrator can bring them back with Add again. Super users see unsubscriptions from the alarms of the whole instance at the top of the page. If every recipient of a website has unsubscribed, the test message sends nothing either.
• System Check: under Administration → Diagnostic → System Check the entry Sentinel (tracking health) shows the time of the last run and the open incidents. If the last run is more than two hours ago, it shows a warning.
• Stored data: hourly visit counts per website (no personal data, kept 70 days), the normal values computed from them, the incidents (resolved ones for up to 400 days), your settings and the unsubscriptions, stored as keys and never as addresses. Sentinel keeps daily totals of up to 400 days only when an add-on such as Sentinel Pro needs them. All of it stays in your Matomo database.
• Nothing leaves your server: Sentinel sends no data anywhere except the alarms to the email addresses and webhooks you enter. When uninstalled, Sentinel removes its tables and settings.
• Command line: ./console feinwerksentinel:run starts a run right away, with --idsite=N for one website only. --dry-run only prints the results, --no-notify updates the incidents without sending alarms.
• Sentinel Pro: the optional add-on adds forecasts as expected values, public holidays per website, checks for single channels and conversion rates, and an external watchdog. Its checks appear on the same page next to Sentinel's.
• Troubleshooting: if Tracking health says "Sentinel has not checked this site yet" or shows the cron job hint, check cron and scheduled tasks. If no email arrives, send a test message and check Matomo's email settings. More in Troubleshooting.

Technical reference

Property	Value
Technical name	FeinwerkSentinel
Current version	0.2.1
Matomo	≥ 5.0.0, < 7.0.0-b1
PHP	≥ 8.1.0
License	free
Database changes	none in the current version

FAQ

Why does broken tracking in Matomo go unnoticed for so long?

Matomo shows no error, it simply records less. A changed consent banner, a tag manager change or a relaunch without the tracking code usually only shows when someone opens the monthly report. By then the missing data cannot be recovered.

How does Sentinel know what is normal for my website?

For every website Sentinel takes the median of the same weekday and hour over the last 8 weeks. Statistical checks start once a website has three weeks of data. Websites with very little traffic are not judged.

Will late archiving cause false alarms?

No. Sentinel reads Matomo's raw tracking data, not the archived reports, so late archiving never looks like missing visits. If archiving stops for too long, a check of its own reports that.

Who receives the alarms?

By default the website's administrators (or the super users, if a website has none), plus the email addresses and webhooks you add. Every alarm email has an unsubscribe link for its recipient.

Can I pause alarms during maintenance?

Yes. With quiet periods, every week or once, Sentinel opens no new incidents for those times.

What do I need?

Matomo 5.0 or newer, PHP 8.1 or newer and Matomo's cron job (core:archive) or browser-triggered tasks. Sentinel runs every hour as one of Matomo's scheduled tasks.

Is any data sent to Feinwerk or third parties?

No. Sentinel keeps everything in your Matomo database and sends alarms only to the email addresses and webhooks you enter.

What does Sentinel cost?

Nothing, Sentinel is free and open source. For forecasts, public holidays and checks per channel, add the optional add-on Sentinel Pro.