Was ist „Log Analytics“ bei Matomo?

Bevor wir in die technische Umsetzung gehen, lohnt sich eine kurze Definition:

Standardmäßig sammelt Matomo Besuchsdaten über JavaScript-Tracking (im Browser) oder über die Tracking API.
Log Analytics bedeutet, dass man stattdessen oder ergänzend Webserver-Zugriffsprotokolle (Access Logs / Server Logs) einliest und daraus Analysedaten erzeugt.
Dadurch benötigt man kein JavaScript-Tracking (z. B. wenn man kein Tracking-Script einbauen kann oder will), und man kann auch historische Logdaten nachträglich importieren. ([Analytics Platform - Matomo][1])
Einige Funktionen (z. B. Heatmaps, Ereignistracking, Formularanalysen) sind bei Log-Analytics nicht möglich, da solche Daten typischerweise nur durch das Frontend-Tracking gewonnen werden. ([Analytics Platform - Matomo][1])

Vorteile von Log Analytics:

Datenschutz & Kontrolle: Sie behalten vollständige Kontrolle über alle Daten und benötigen kein Third-Party-JavaScript. ([Analytics Platform - Matomo][1])
Vollständigkeit & Resilienz: Auch wenn Nutzer Plugins oder Adblocker aktiv haben, bleiben Logdaten bestehen.
Historische Datenanalyse: Bestehende Logdateien lassen sich rückwirkend importieren. ([Analytics Platform - Matomo][2])

Aber: Man verliert bestimmte Metriken (z. B. Bildschirmauflösung, Ereignisse) und ist auf die Felder angewiesen, die im Log enthalten sind.

Technische Voraussetzungen

Damit Log Analytics mit Matomo funktioniert, müssen eine Reihe von Bedingungen erfüllt sein — sowohl auf Seiten des Matomo-Servers als auch der Log-Server.

Voraussetzungen für Matomo (On-Premise / Hosting)

Zuerst einmal die allgemeinen Voraussetzungen, damit Matomo überhaupt läuft:

Ein Webserver (Apache, Nginx, IIS etc.) mit PHP und Datenbank (MySQL / MariaDB) ([Analytics Platform - Matomo][3])
PHP-Version mindestens 7.2.5 oder neuer (für neuere Matomo-Versionen) ([Analytics Platform - Matomo][3])
MySQL oder MariaDB (Version ≥ 5.5 oder besser) ([Analytics Platform - Matomo][3])
PHP-Erweiterungen wie pdo, pdo_mysql (oder mysqli), php-gd, php-xml, php-mbstring etc. empfohlen ([Analytics Platform - Matomo][3])
Die Möglichkeit, CLI-Befehle auf dem Server auszuführen (z. B. via SSH), da das Import-Skript meist als Python-Skript läuft. ([Analytics Platform - Matomo][4])

Insbesondere für Log Analytics:

Zugang zur Serverseite, um Skripte auszuführen (SSH oder vergleichbar). ([Analytics Platform - Matomo][4])
Installation von Python (Version 3.5 oder neuer) auf dem Server, von dem aus man die Logs importiert (kann auch derselbe Server wie Matomo sein). ([Analytics Platform - Matomo][4])
Zugang zu den Logdateien (Read-Permissions) und idealerweise Sortierung nach Datum (Logzeilen müssen fortlaufend sein) ([Analytics Platform - Matomo][4])
Für Geolokalisierung: Wenn nur Logdaten verwendet werden, fehlen oft Browserdaten (z. B. „Accept-Language“) – daher sollte der GeoIP/Geolocation-Dienst in Matomo eingerichtet sein, damit Herkunftsländer etc. korrekt erkannt werden. ([Analytics Platform - Matomo][4])

Zudem:

Wenn Sie Matomo in der Cloud (Matomo Cloud) betreiben, können Sie trotzdem Log Analytics nutzen, allerdings müssen Sie das Import-Skript extern laufen lassen und das --token-auth verwenden. ([Analytics Platform - Matomo][5])
Log Analytics funktioniert mit Matomo Cloud, On-Premise und Matomo für WordPress. ([Analytics Platform - Matomo][4])

Anforderungen an die Logdateien und deren Format

Damit das Import-Skript die Logs korrekt verarbeiten kann, ist das Format der Logdateien entscheidend:

Die Logs sollten ein erweitertes Log-Format (extended log format) verwenden, mit Informationen wie User-Agent, Referrer, vollständige URLs (einschließlich Hostnamen). ([Analytics Platform - Matomo][4])
Wenn Felder fehlen (z. B. Hostname, Referer, User-Agent), wird die Genauigkeit der Analysen abnehmen. ([Analytics Platform - Matomo][4])
Der Importer unterstützt eine Reihe von Logformaten nativ (z. B. common, common_vhost, ncsa_extended, common_complete, w3c_extended, iis etc.). ([Analytics Platform - Matomo][6])
Falls Ihr Logformat nicht unterstützt wird oder stark angepasst ist (z. B. eigenes Format, besondere Felder), können Sie mittels --log-format-regex ein eigenes Parsing-Muster angeben. ([Analytics Platform - Matomo][6])
Die Reihenfolge der Zeilen in der Logdatei sollte nach Zeit sortiert sein, damit das Skript korrekt arbeitet. ([Analytics Platform - Matomo][4])
Standardmäßig ignoriert der Importer Bot-Traffic, statische Dateien (CSS, JS, Bilder) und HTTP-Fehler/Redirects — diese können optional aktiviert werden mit Flags. ([Analytics Platform - Matomo][7])

Wenn diese Voraussetzungen erfüllt sind, steht dem Setup nichts mehr im Wege.

Schritt-für-Schritt: Einrichtung von Log Analytics mit Matomo

Nachfolgend eine typische Anleitung, wie Sie Log Analytics in einer typischen Umgebung einrichten können. Sie sollten sich jedoch ggf. an Ihre spezifische Systemumgebung (Betriebssystem, Logserver, Sicherheit) anpassen.

1. Matomo-Setup vorbereiten

Stellen Sie sicher, dass Ihre Matomo-Installation läuft und korrekt konfiguriert ist (Webserver, Datenbank, PHP etc.).
Erstellen Sie in Matomo eine neue “Website” (Messobjekt), unter dem Sie die Logdaten erfassen möchten (z. B. „MeinWebsite – LogImport“). Notieren Sie sich die idsite dieser Website.
Falls Matomo in der Cloud oder auf einem anderen Server läuft, besorgen Sie sich den token_auth (API-Token) für einen Benutzer mit ausreichenden Rechten.

Der Token muss ggf. so eingestellt sein, dass auch unsichere Verbindungen erlaubt sind (wenn der Import über HTTP erfolgt) — aber idealerweise sollte alles über HTTPS laufen. ([Analytics Platform - Matomo][5])
1. Stellen Sie sicher, dass Geolocation (GeoIP) in Matomo eingerichtet ist, besonders wenn Sie ausschließlich Logdaten nutzen (sonst fehlen Herkunftsstatistiken).

2. Importskript beschaffen

Das Importskript heißt typischerweise import_logs.py und befindet sich innerhalb Ihrer Matomo-Installation unter misc/log-analytics/import_logs.py. ([Analytics Platform - Matomo][6]) Wenn Sie eine Cloud-Version nutzen und keinen Zugriff auf das Matomo-Server-Filesystem haben, können Sie das Skript aus dem GitHub-Repository herunterladen. ([Analytics Platform - Matomo][5]) Überprüfen Sie, dass Python 3 installiert ist und aufgerufen werden kann (python3).

3. Ersttest: Einmaliger Import

Führen Sie einen ersten Import durch, um zu prüfen, ob das Setup funktioniert. Ein Beispielbefehl (unter Linux / Apache) könnte so aussehen:

sudo python3 /pfad/zu/matomo/misc/log-analytics/import_logs.py \
  --url=https://analytics.example.com/matomo \
  --idsite=1234 \
  --token-auth=DEIN_TOKEN_HIER \
  --recorders=4 \
  --enable-http-errors \
  --enable-http-redirects \
  --enable-static \
  /var/log/apache2/access.log

Erläuterungen:

--url=... ist die Basis-URL Ihrer Matomo-Instanz (mit https://). ([Analytics Platform - Matomo][6])
--idsite=1234 legt fest, in welche Matomo-Website (Messobjekt) importiert wird
--token-auth= gibt den API-Token an (nur nötig, wenn Sie das Skript extern ausführen) ([Analytics Platform - Matomo][6])
--recorders=4 gibt an, mit wie vielen parallelen Threads der Import durchgeführt wird — optimalerweise Anzahl der CPU-Kerne oder ähnlich
--enable-http-errors, --enable-http-redirects, --enable-static aktivieren optionale Datentypen, die standardmäßig ausgeschlossen sind (Fehlerseiten, Weiterleitungen, statische Ressourcen) ([Analytics Platform - Matomo][7])
Danach folgen ein oder mehrere Pfade zu Logdateien, z. B. /var/log/apache2/access.log

Wenn alles funktioniert, sollten Sie eine Zusammenfassung erhalten (z. B. wie viele Zeilen verarbeitet, wie viele Requests importiert) ([Analytics Platform - Matomo][6]) Wichtig: Es gibt keine automatische Duplikaterkennung — wenn Sie denselben Logdateiinhalt mehrfach importieren, gibt es Doppelzählungen. ([Analytics Platform - Matomo][6]) Deshalb empfiehlt es sich, zunächst in eine Test-Website zu importieren. ([Analytics Platform - Matomo][8])

4. Archivierung & Berichte erzeugen

Sobald Logs importiert wurden, müssen die Daten „archiviert“ werden, damit Matomo Berichte generiert:

/path/to/matomo/console core:archive --force-all-websites --url=https://analytics.example.com/matomo

Dies erzeugt die aggregierten Statistiken, die im Dashboard angezeigt werden. ([Cloudron Forum][9])

Sie können diesen Befehl regelmäßig (z. B. per cronjob) ausführen lassen, um automatisch Berichte zu aktualisieren.

5. Automatisierung via Cronjob

Damit Log Analytics dauerhaft sinnvoll ist, empfiehlt sich eine Automatisierung:

Log-Rotation sicherstellen (z. B. access.log.1, access.log.2.gz etc.).
Ein Cronjob, der z. B. einmal täglich (z. B. nachts) alle Logdateien des Vortags importiert und anschließend das Archiv ausführt.

Beispiel für Crontab:

0 1 * * * /usr/bin/python3 /pfad/zu/matomo/misc/log-analytics/import_logs.py \
 --url=https://analytics.example.com/matomo \
 --idsite=1234 \
 --token-auth=DEIN_TOKEN \
 --recorders=4 \
 --enable-http-errors \
 --enable-http-redirects \
 --enable-static \
 /var/log/apache2/access.log.1 && \
/pfad/zu/matomo/console core:archive --force-all-websites --url=https://analytics.example.com/matomo

Sicherstellen, dass Berechtigungen (Benutzer) korrekt sind und dass das Skript genügend Rechte auf die Logdateien hat.

6. Monitoring und Anpassung

Überprüfen Sie regelmäßig die Berichte in Matomo, ob Daten plausibel ankommen.
Vergleich mit JavaScript-Tracking (wenn parallel aktiv) kann helfen, Abweichungen zu erkennen.
Falls manche Logzeilen nicht erkannt werden (Importer berichtet „invalid lines“), kann man das Log-Format oder --log-format-regex anpassen. ([Cloudron Forum][9])
Für sehr große Logdateien kann man den Import stückweise durchführen (z. B. nach Zeitbereichen).
Die Anzahl der recorders und andere Parameter (Payload-Größe, etc.) kann man optimieren, um Performance zu verbessern. ([Analytics Platform - Matomo][7])

Typische Fallstricke & Lösungen

Problem	Mögliche Ursache	Lösung / Hinweis
„0 Zeilen importiert“	Logformat wird nicht erkannt oder Regex passt nicht	Aktivieren Sie `--debug`, prüfen Sie das Format, passen Sie `--log-format-regex` an ([Analytics Platform - Matomo][6])
Doppelzählungen	Derselbe Log-Inhalt wurde mehrfach importiert	Nutzen Sie separate „Test“-Website, vermeiden Sie Mehrfachimporte ([Analytics Platform - Matomo][8])
Fehlende Geo-Daten	Geolocation nicht eingerichtet oder fehlt in Logs	Stellen Sie sicher, dass GeoIP/GeoLocation in Matomo aktiviert ist ([Analytics Platform - Matomo][4])
Ungenaue Analytics (fehlende Metriken)	Log enthält nicht alle nötigen Felder (z. B. Referrer, User Agent)	Passen Sie das Logformat an oder ergänzen Sie fehlende Felder
Performanceprobleme bei großen Logs	Zu wenige Recorder, zu große Payload, zu große Dateien auf einmal	Reduzieren Sie Loggrößen, erhöhen Sie Parallelität, optimieren Sie Parameter
Konflikte mit JavaScript-Tracking	Kombination im selben Messobjekt führt zu doppelten Zählungen	Importieren Sie Logdaten in eigenes Messobjekt (anderen `idsite`) ([Analytics Platform - Matomo][8])

Empfehlungen

Log Analytics mit Matomo ist eine mächtige Methode, Webanalysen auch ohne JavaScript-Tracking durchzuführen und historische Daten aus Logs zu nutzen. Doch: Der Erfolg hängt stark von der Qualität und dem Format der Logdateien sowie von korrekter Konfiguration und Automatisierung ab.

Wenn Sie planen, das in Ihrem Setup zu nutzen, empfehle ich:

Ein Prototyp-Import in einer Test-Website zuerst durchführen
Logformat und Parser mit --debug explorieren
Cronjobs und Archivierung einrichten
Laufende Kontrolle und Anpassung