Evan Genest's Learning Log

Web developer notes emphasizing LAMP, Symfony, PHP, Javascript, Drupal, and Node.

This is an Eleventy project created from the eleventy-base-blog repo.

Where to look for Matomo Error Messages

matomotroubleshooting

How does Matomo work; introduction to Matomo for beginners

We can start here with an explanation of what Matomo does when everything is going right, so we have something to aspire to!

Matomo comes in three flavors. We will assume in this article that you are running On Premise. Before troubleshooting, take some time to know the rudiments of what Matomo is doing.

In the most simple Matomo set up, Matomo will give you a somewhat generic short six line script to paste into the top of any web page you want to monitor. The script twlls that web page: "create a Javascript variable to store data in the browser. Then download a fairly large Javascript program from www.example.com/matomo, where example.com is replaced by your website domain."

This payload is sized 2kB to 20kB depending on how many bells and whistles you have turned on in your Matomo dashboard. (It's a common misconception: people ask "How large is the Matomo download? Why is it so much bigger than Plausible, et al?" But the payload is controlled by you; it can be made pretty small if you minimize what you are tracking. Do that in the user interface if you wish.) If you open and read the payload, this downloaded JS has lots of event listeners and selectors. There's nothing magical going on.

Matomo has a much better description of all this at the Matomo Developer Documentation.

Troubleshooting in the front end

If the problem is subtle, it's useful to start by seeing what is happening in the browser first.

In devtools, click the network tab to confirm what scripts are loading. Start by looking for the payload in files named matomo.js or piwik.js.

Then, as you click and interact with your site, keep watching the devtools. The network will show you the headers and content of the http requests and responses. The client in this case is your browser and it is talking to the Matomo tracking API.

Troubleshooting the http traffic

The traffic to the API can be checked first by looking at the Apache server (or similarly in nGinx).

/var/log/apache2/access*.log
This is not exactly errors. This is all of the http reqs. As a fun bonus, this one can be read into Matomo later with a log reader.py (in case you ever have Matomo go down and you lose data)

/var/log/apache2/error*.log
This is where you look during Matomo troubleshooting

Troubleshooting in the back end

The back end, written in PHP, will of course not be viewed in your browser. For the PHP errors, look in your logs for two things:

In my experience, 90% of the useful errors will be in the logs.

If you want to be proactive, go into the user interface (dashboard) and select admin > systems check
Or in the CLI:
./console diagnostics:run

If you are running a cron job for report archiving, the crontab errors arrive via email.

Find your php.ini file. Set this if it is not already:
log_errors = On
display_errors=Off

Find your matomo/config/common.config.ini.php Put the line logger_file_path = tmp/logs/matomo.log
Now when trouble strikes (and it will) you can peruse your matomo/tmp/logs/matomo.log
This shows how ./console core:archive is succeeding or not. This is an audit of all Matomo Rawdata -> ReportArchiving.

Enable the slow log for monitoring for weird slowness in the SQL database First, find the config file for mysql. In Linux, search here in descending priority, SQL loads the first file found in this list:
/etc/my.cnf
/etc/mysql/my.cnf
$MYSQL_HOME/my.cnf

Add this, including the square brackets line

[mysqld]
# threshold for what is considered slow
long_query_time=3
# location to log to
slow_query_log_file=/var/log/mysql-slow.log
# Enable slow query logging
slow-query-log=1

Restart mysql.
Now queries taking more than 3 seconds will be logged.
To view that log, the command is mysqldumpslow -t 10 mysql-slow.log > mysqldumpslow.out
This would give the top 10 queries, sorted by time they took