tutorial

Monitoring Matomo Analytics with Vigilmon: Health Checks, Tracking Endpoint & SSL Certificate Alerts

How to monitor self-hosted Matomo Analytics with Vigilmon — homepage health check, JS tracking endpoint availability, API endpoint monitoring, SSL certificate alerts, and real-time notifications for your privacy-first analytics platform.

Matomo (formerly Piwik) is the leading open-source, self-hosted alternative to Google Analytics — trusted by organisations that need full data ownership and GDPR compliance. When your Matomo instance goes down, tracking scripts embedded across your websites silently fail to record visits, and your team loses access to real-time traffic dashboards. Vigilmon gives you external visibility into Matomo's health: the homepage availability, JavaScript tracking endpoint, REST API, and SSL certificates — so you catch outages before analytics data is lost.

What You'll Build

  • A monitor on Matomo's homepage for server and process health
  • A JavaScript tracking endpoint availability check (/matomo.js)
  • An API endpoint health check (/matomo.php)
  • SSL certificate monitoring for your Matomo domain
  • Alerting that distinguishes web layer failures from tracking script failures

Prerequisites

  • A running self-hosted Matomo instance with HTTPS access
  • Matomo accessible at a public or network-reachable URL (e.g., https://matomo.example.com)
  • A free account at vigilmon.online

Step 1: Verify Matomo's Endpoints

Before adding monitors, confirm Matomo's key endpoints respond correctly:

# Homepage — should return 200
curl -I https://matomo.example.com

# JavaScript tracking file — should return 200 with Content-Type: application/javascript
curl -I https://matomo.example.com/matomo.js

# Tracking API endpoint — returns 1x1 GIF or 204 No Content for GET requests
curl -I https://matomo.example.com/matomo.php

# Matomo API (replace TOKEN_AUTH with a token from Settings → Personal → Security)
curl "https://matomo.example.com/index.php?module=API&method=API.getMatomoVersion&format=JSON&token_auth=TOKEN_AUTH"

A healthy Matomo returns 200 from the homepage and matomo.js. The tracking endpoint (matomo.php) accepts GET requests and returns a 200 with a 1x1 transparent GIF. The API endpoint returns JSON with the Matomo version number.

Step 2: Create a Vigilmon Monitor for the Homepage

Matomo's homepage availability confirms the PHP-FPM/web server stack is operational. If the homepage fails, all tracking and dashboard access fails too:

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://matomo.example.com.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: Matomo (present in the page title on a healthy instance).
  7. Label: Matomo Homepage.
  8. Click Save.

The keyword check catches misconfigured web servers that serve a blank 200 response rather than the Matomo application.

Step 3: Monitor the JavaScript Tracking Endpoint

The matomo.js file is loaded by the tracking snippet on every website using your Matomo instance. If this file becomes unavailable, all tracking silently stops across every site that uses your Matomo — no pageviews, no events, no conversions are recorded:

  1. Add Monitor → HTTP.
  2. URL: https://matomo.example.com/matomo.js.
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: Matomo (present inside the JS file).
  7. Label: Matomo JS Tracker.
  8. Click Save.

This is the most externally visible component of Matomo — your tracked websites depend on it being available. A failure here silently drops all analytics across every site using your instance.

Step 4: Monitor the Tracking API Endpoint

The matomo.php endpoint receives tracking data from both the JavaScript tracker and server-side tracking integrations. Unlike the homepage, this endpoint should remain available even during dashboard maintenance:

  1. Add Monitor → HTTP.
  2. URL: https://matomo.example.com/matomo.php.
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Label: Matomo Tracking API.
  7. Click Save.

A 404 or 502 from this endpoint means visit data is not being recorded even if the homepage appears healthy. This can happen when a misconfigured nginx rewrite rule removes the file or a PHP-FPM pool restart causes temporary failures.

Step 5: Monitor the Matomo REST API

Matomo's REST API (index.php?module=API) powers integrations, dashboards, and custom reports. Monitoring it confirms the PHP application layer and database backend are healthy:

  1. Add Monitor → HTTP.
  2. URL: https://matomo.example.com/index.php?module=API&method=API.getMatomoVersion&format=JSON&token_auth=anonymous (use anonymous if anonymous API access is enabled, or a dedicated read-only token).
  3. Check interval: 5 minutes.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: value (present in the JSON response {"value":"5.x.x"}).
  7. Label: Matomo REST API.
  8. Click Save.

Token security: Create a dedicated API token in Matomo under Settings → Personal → Security → Auth tokens with no administrative privileges. Do not use the superuser token for monitoring.

If this monitor fires while the homepage is healthy, the database backend (MySQL/MariaDB) may be unavailable, which also means tracking data is not being persisted.

Step 6: Monitor SSL Certificates

Matomo's tracking snippet is served over HTTPS and loaded from every website you track. An expired SSL certificate breaks the matomo.js script load across all tracked sites — browsers block the load with no server-side error, so Matomo itself shows no error while tracking silently stops everywhere:

  1. Add Monitor → SSL Certificate.
  2. Domain: matomo.example.com.
  3. Alert when expiry is within: 30 days.
  4. Alert again: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

SSL expiry is particularly damaging for Matomo because the failure cascades silently to every site using your tracking snippet.

Step 7: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | Homepage | Non-200 or keyword missing | Web server or PHP-FPM failure; check nginx/Apache and PHP | | JS tracker (matomo.js) | Non-200 | Tracking stopped on all sites; critical data loss | | Tracking API (matomo.php) | Non-200 | Visits not being recorded; check PHP-FPM and rewrites | | REST API | Non-200 or keyword missing | Database may be unreachable; check MySQL/MariaDB | | SSL certificate | < 30 days to expiry | Renew certificate; check Let's Encrypt auto-renewal |

Alert after: 1 consecutive failure for the JS tracker and tracking API — tracking data loss is immediate. 2 failures for the homepage and REST API to avoid false positives during Matomo upgrades.

Common Matomo Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | PHP-FPM crash or OOM | Homepage returns 502; all monitors fire | | MySQL/MariaDB unreachable | REST API keyword check fails; tracking data not persisted | | Disk full on Matomo server | PHP errors; homepage returns 500 | | matomo.js deleted or path changed | JS tracker monitor fires; tracking stops everywhere | | nginx rewrite misconfiguration | Tracking API returns 404; homepage may still be healthy | | Let's Encrypt renewal failure | SSL monitor alerts at 30-day threshold | | Matomo upgrade failure | Homepage returns error; homepage and API monitors fire | | High traffic causes PHP-FPM queue to fill | Response timeout fires; check pm.max_children |

Matomo failures are uniquely damaging because they cascade silently to every website using your tracking snippet. A broken matomo.js endpoint drops analytics across your entire portfolio of tracked sites without any server-side log entries — your sites keep running while data collection stops completely. Vigilmon's layered monitoring of the homepage, tracking script, API, and SSL certificate gives you the external visibility to catch Matomo outages before analytics data is permanently lost.

Start monitoring Matomo in under 5 minutes — register free at vigilmon.online.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles