Matomo (fka PIWIK)

Siehe auch

Verwandte Artikel

• Apache httpd

• GeoIP-Datenbanken

• MariaDB

• PHP

Offizielle Dokumentation

• Matomo Documentation

• Matomo Log Analytics

Linuxfabrik

• LFOps-Rolle apache_httpd (deployt import_logs.py)

• Monitoring-Plugin matomo-reporting

• Monitoring-Plugin matomo-version

Matomo von InnoCraft hiess bis Januar 2018 PIWIK und ist eine self-hosted Open-Source-Alternative zu Google Analytics. Es ist eine PHP-Applikation, läuft typischerweise unter Apache httpd und nutzt MariaDB als Datenbank.

Matomo gehört auf einen eigenen Host (z.B. analytics.example.com), nicht unter die URL der auszuwertenden Webseite. Matomo liefert für die eigene Oberfläche bewusst offene Content-Security-Policy-Header aus (unsafe-inline, unsafe-eval und data:-URIs), was Security-Scanner monieren - beim Betrieb unter der Webseiten-URL (example.com/analytics) fällt das im Security-Ranking auf die Webseite zurück.

Begriffe

• Archivierung: Matomo verdichtet die Roh-Tracking-Daten periodisch zu Reports (console core:archive). Läuft die Archivierung nicht, brechen die Widgets der Weboberfläche mit wachsender Datenmenge wegen Timeouts zusammen.

• Auth-Token: API-Schlüssel eines Matomo-Benutzers, angelegt unter „Administration > Personal > Security“. Wird für die HTTP-API und den Log-Import benötigt.

• Log Analytics: Import von Webserver-Logfiles per import_logs.py, als Ergänzung oder Ersatz für den JavaScript-Tracking-Code.

• Tracking-Code: JavaScript-Schnipsel (matomo.js), den die auszuwertende Webseite einbindet.

Installation

Ein aktuelles PHP unter Apache httpd verwenden, als Datenbank ist MariaDB empfohlen.

dnf -y install php php-pdo php-mysqlnd php-mbstring php-gd php-dom

Damit sind alle von Matomo benötigten und empfohlenen PHP-Extensions vorhanden (prüfbar per console diagnostics:run). Das memory_limit hebt Matomo selbst per ini_set() an, sofern PHP das erlaubt: auf 128 MB im Web-Betrieb, auf 768 MB beim Archivieren (minimum_memory_limit und minimum_memory_limit_when_archiving in der [General]-Sektion).

Download und Entpacken:

rm -f /tmp/latest.zip
rm -rf /tmp/matomo*
wget https://builds.matomo.org/latest.zip --output-document=/tmp/latest.zip
unzip -o /tmp/latest.zip -d /var/www/html/
rm -rf /var/www/html/matomo/tmp/*

chown -R apache:apache /var/www/html/matomo

Matomo schreibt zur Laufzeit in config/ (Einstellungen), matomo.js / piwik.js (Tracker-Updates durch Plugins), tmp/ (Caches) und misc/ (GeoIP-Datenbanken). SELinux entsprechend konfigurieren:

semanage fcontext --add --type httpd_sys_rw_content_t "/var/www/html/matomo/config(/.*)?"
semanage fcontext --add --type httpd_sys_rw_content_t "/var/www/html/matomo/matomo.js"
semanage fcontext --add --type httpd_sys_rw_content_t "/var/www/html/matomo/misc(/.*)?"
semanage fcontext --add --type httpd_sys_rw_content_t "/var/www/html/matomo/piwik.js"
semanage fcontext --add --type httpd_sys_rw_content_t "/var/www/html/matomo/tmp(/.*)?"

restorecon -Fvr /var/www/html/matomo

Cronjob für die automatische Archivierung einrichten, stündlich und als Webserver-Benutzer - läuft die Konsole als root, gehören die angelegten Cache-Dateien unter tmp/ root, und der Webserver kann nicht mehr hineinschreiben:

/etc/cron.d/matomo-archive

# Matomo Auto Archiving
5 * * * * apache /usr/bin/php /var/www/html/matomo/console core:archive --url=https://analytics.example.com/ > /var/log/matomo-archive.log 2>&1

touch /var/log/matomo-archive.log
chown apache:apache /var/log/matomo-archive.log

Derselbe Job als systemd-Timer (der Output landet im Journal):

/etc/systemd/system/matomo-archive.service

[Unit]
Description=Matomo Archive Service

[Service]
ExecStart=/usr/bin/php /var/www/html/matomo/console core:archive --url=https://analytics.example.com/
Type=oneshot
User=apache

/etc/systemd/system/matomo-archive.timer

[Unit]
Description=Matomo Archive Timer

[Timer]
OnCalendar=*:05:00
Unit=matomo-archive.service

[Install]
WantedBy=timers.target

systemctl daemon-reload
systemctl enable --now matomo-archive.timer

Jetzt die Instanz per https://analytics.example.com/index.php aufrufen und im Setup-Wizard den ersten Benutzer anlegen.

Upgrade

Eine bestehende Matomo-Installation wird per Kommandozeile aktualisiert. Zuerst die Dateibasis:

INSTALL_DIR=/var/www/html/matomo
MATOMO_URL=analytics.example.com

rm -f /tmp/latest.zip
rm -rf /tmp/matomo*

wget https://builds.matomo.org/latest.zip --output-document=/tmp/latest.zip
unzip -o /tmp/latest.zip -d /tmp

\cp -r /tmp/matomo/* $INSTALL_DIR/
rm -rf /tmp/matomo

chmod +w $INSTALL_DIR/matomo.js
chmod +w $INSTALL_DIR/config/config.ini.php
chown -R apache:apache $INSTALL_DIR
restorecon -Fvr $INSTALL_DIR

systemctl restart php-fpm.service

Dann das eigentliche Upgrade:

sudo -u apache php $INSTALL_DIR/console --matomo-domain=$MATOMO_URL core:update
sudo -u apache php $INSTALL_DIR/console --matomo-domain=$MATOMO_URL core:clear-caches
sudo -u apache php $INSTALL_DIR/console --matomo-domain=$MATOMO_URL core:run-scheduled-tasks

sudo -u apache php $INSTALL_DIR/console diagnostics:run

Plugins aktualisieren:

1. Plugin-Liste ausgeben. Relevant sind nur die „Optional“-Plugins:

sudo -u apache php /var/www/html/matomo/console plugin:list
+-----------------------+-------------------+---------------+
| Plugin                | Core or optional? | Status        |
+-----------------------+-------------------+---------------+
| CustomVariables       | Optional          | Activated     |
| FormAnalytics         | Optional          | Not activated |
| Provider              | Optional          | Activated     |
+-----------------------+-------------------+---------------+

2. Kompatibilität pro Plugin unter https://plugins.matomo.org/<PluginName> prüfen (Requirements).

3. Passen die Requirements, die Plugins aktualisieren:

sudo -u apache php /var/www/html/matomo/console plugin:install-or-update CustomVariables FormAnalytics Provider

Konfiguration

Wenn Matomo hinter einem Reverse Proxy läuft (FAQ 98):

/var/www/html/matomo/config/config.ini.php

[General]
assume_secure_protocol = 1
proxy_client_headers[] = HTTP_X_FORWARDED_FOR
proxy_host_headers[] = HTTP_X_FORWARDED_HOST

GeoIP: Matomo speichert Geolocation-Datenbanken im Unterordner misc/ und richtet sie im Web-GUI unter „Administration > System > Geolocation“ ein (Maxmind empfohlen, siehe GeoIP-Datenbanken). Für Download und automatische Updates über das GUI muss der Webserver in misc/ schreiben dürfen (SELinux-Kontext siehe Installation).

Matomo ohne Tracking-Code (matomo.js)

Adblocker verhindern die Ausführung der matomo.js. Wer trotzdem grundlegende Statistiken haben möchte, kann den Webserver anweisen, bei Bedarf sogar in Echtzeit direkt nach Matomo zu loggen.

Zunächst das Python-Script import_logs.py z.B. in /usr/local/sbin/import_logs.py auf dem Webserver ablegen, der die Seite über die Domain-Namen verarbeitet (also beispielsweise auf dem Reverse Proxy). Den Shebang auf #!/usr/bin/python3 ändern, da das Script mit #!/usr/bin/python ausgeliefert wird und RHEL kein unversioniertes python kennt.

chmod +x /usr/local/sbin/import_logs.py

In Matomo unter „Administration > Personal > Security“ ein neues Auth-Token anlegen. Die Description könnte „srv-proxy site.example.com import_logs.py“ lauten, wenn es ein Token für „site.example.com“ auf dem Reverse Proxy „srv-proxy“ sein soll.

Das Auth-Token in einer Konfigurationsdatei ablegen, statt es per --token-auth auf der Kommandozeile zu übergeben. Die Datei gehört dem Benutzer, der das Script ausführt (beim Realtime-Logging ist das der Benutzer, der httpd gestartet hat, also root), und darf nur für diesen lesbar sein, sonst warnt das Script:

/etc/matomo-auth.conf

[auth]
token_auth=linuxfabrik

chmod 600 /etc/matomo-auth.conf

Bemerkung

• Mit --url ist die URL des Matomo-Servers gemeint, nicht die der auszuwertenden Seite.

• Das Auth-Token muss von einem Benutzer mit Admin- oder Superuser-Rechten kommen.

• --token-auth, --login und --password auf der Kommandozeile sind deprecated und erzeugen eine Warnung, da die Werte für alle Benutzer in der Prozessliste sichtbar sind. Stattdessen --auth-config verwenden.

• Auth-Token mit aktivem „Only allow secure requests“ („Secure use only“) funktionieren, da das Script das Token per POST-Body überträgt.

• Das Import-Tool prüft rein gar nichts vor dem Import. Mehrfache Aufrufe auf die gleichen Log-Daten führen in Matomo also auch zu mehrfach gezählten Daten.

Real-time-Auswertung der Logfiles

Die Apache vHost-Definition anpassen:

vhost.conf

# Matomo Realtime Logging
LogFormat "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" matomo
CustomLog "||/usr/local/sbin/import_logs.py \
    --auth-config=/etc/matomo-auth.conf \
    --debug \
    --enable-bots \
    --enable-http-errors \
    --idsite=1234 \
    --output=/var/log/matomo.log \
    --recorders=4 \
    --url=https://analytics.example.com \
    -" matomo

Auswertung aktivieren:

httpd -t
setsebool -P httpd_can_network_connect on
systemctl reload httpd

SELinux:

semanage fcontext --add --type httpd_log_t "/var/log/matomo.log"
restorecon -Fv /var/log/matomo.log

Periodische Auswertung der Logfiles

Per Cronjob oder systemd-Timer folgenden Aufruf konfigurieren:

/usr/local/sbin/import_logs.py \
    --auth-config=/etc/matomo-auth.conf \
    --debug \
    --enable-bots \
    --enable-http-errors \
    --idsite=1234 \
    --output=/var/log/matomo.log \
    --recorders=4 \
    --url=https://analytics.example.com \
    /path/to/analytics.example.com-access.log

Um bereits rotierte Logfiles von gestern zu importieren, folgendes Konstrukt verwenden:

/usr/local/sbin/import_logs.py \
    ... \
    $(date --date=yesterday +/path/to/analytics.example.com-access.log-\%Y\%m\%d)

Logging:

tail -f /var/log/audit/audit.log /var/log/httpd/analytics.example.com-error.log /var/log/matomo.log

Alle Parameter liefert import_logs.py --help, dokumentiert in der Projekt-README.

Daten aufräumen

Rohdaten für einen bestimmten Tag löschen:

• Zunächst Rohdaten per Matomo > „Administration > Privacy > GDPR Tools“ löschen, beispielsweise auf Basis „Time in UTC“ „Starts with“ „2020-12-09“. Muss evtl. mehrfach wiederholt werden, da die Seite die Ergebnisliste begrenzt.

• Dann die historischen Reports neu berechnen lassen:

sudo -u apache php /var/www/html/matomo/console core:invalidate-report-data --periods=all --cascade --dates=2020-12-09,2020-12-10 --sites=2

Matomo Console Cheat Sheet

Die Konsole immer als Webserver-Benutzer aufrufen, sonst gehören die Cache-Dateien unter tmp/ anschliessend root.

cd /var/www/html/matomo

sudo -u apache ./console list

sudo -u apache ./console core:archive --url=https://analytics.example.com
sudo -u apache ./console core:clear-caches
sudo -u apache ./console core:convert-to-utf8mb4 --show
sudo -u apache ./console core:run-scheduled-tasks
sudo -u apache ./console core:update

# all section names: see config/global.ini.php; plugins add their own sections
sudo -u apache ./console config:get --section=General
sudo -u apache ./console config:set --section=database --key=host --value=127.0.0.1

sudo -u apache ./console database:optimize-archive-tables 2025-0{1..9} 2025-1{0..2}

sudo -u apache ./console diagnostics:run

Troubleshooting

Allgemeine Diagnose

sudo -u apache php /var/www/html/matomo/console diagnostics:run

PHP Fatal error: Cannot override final method Piwik\Plugin\ConsoleCommand::execute() in /var/www/html/matomo/plugins/CoreConsole/Commands/GenerateAngularComponent.php on line 27 beim Aufruf von console nach einem Update

Der oben beschriebene (und von Matomo empfohlene) Update-Vorgang aktualisiert nur bestehende und neue Files auf dem Server, löscht aber niemals alte Files. Das führt zu Problemen, wenn es Files in einer neueren Version von Matomo nicht mehr gibt. Die überflüssigen Files entfernen, am besten indem die Files auf dem Server mit den Files in der ZIP-Datei verglichen werden. Bei der obigen Fehlermeldung hilft folgendes (siehe Issue #21718):

\rm -f /var/www/html/matomo/plugins/CoreConsole/Commands/GenerateAngularComponent.php
\rm -f /var/www/html/matomo/plugins/CoreConsole/Commands/GenerateAngularConstructBase.php
\rm -f /var/www/html/matomo/plugins/CoreConsole/Commands/GenerateAngularDirective.php

sudo -u apache php /var/www/html/matomo/console diagnostics:run

Unable to write in the cache directory (/var/www/html/matomo/tmp/templates_c/8a)

Caches leeren. Tritt der Fehler auf, nachdem die Konsole als root lief, gehören Dateien unter tmp/ root - dann zusätzlich chown -R apache:apache /var/www/html/matomo/tmp ausführen.

sudo -u apache php /var/www/html/matomo/console core:clear-caches

Unable to execute check for https://analytics.example.com/tmp/: curl_exec: Connection timed out after 2000 milliseconds. Hostname requested was: analytics.example.com

Matomo rennt bei lokalem Aufruf von curl https://analytics.example.com in einen Timeout. Könnte an fehlenden /etc/hosts-Einträgen auf dem Matomo-Host liegen.