Matomo-Timeouts beheben: 504 Gateway Timeout, hängende Berichte, abgebrochene Exporte

· 9 Min. Lesezeit ·

Themen: Betrieb & Performance

Der Ladekreisel dreht sich, dann erscheint „504 Gateway Timeout“. Oder Matomo meldet „Oops… während der Anfrage ist ein Problem aufgetreten“ und tippt auf einen überlasteten Server oder einen Bericht mit zu vielen Daten. Der CSV-Export bricht ab, und das nächtliche API-Skript bekommt eine Fehlerseite statt Daten.

Meist steckt dahinter kein Fehler in Matomo, sondern eine Rechnung, die nicht aufgeht: Eine Anfrage soll mehr Arbeit erledigen, als ihr ein Glied der Kette Zeit lässt. Dieser Artikel zeigt, wo die Zeitlimits sitzen, warum Matomo an sie stößt und was Matomo selbst dagegen empfiehlt.

Zur Abgrenzung: Hängt die Archivierung selbst oder bleiben Berichte tagelang leer, finden Sie die Details in unserem Artikel zu Archivierungsproblemen in Matomo. Das allgemeine Tuning von Server und Datenbank behandelt Matomo-Performance optimieren.

Die Zeitlimits einer Matomo-Anfrage in fünf Schichten: 1. Browser, zeigt nur das Ergebnis. 2. Reverse Proxy oder Load Balancer, bei nginx proxy_read_timeout 60 Sekunden. 3. Webserver, nginx fastcgi_read_timeout 60 Sekunden, Apache Timeout 60 Sekunden. 4. PHP, max_execution_time 30 Sekunden, auf der Kommandozeile kein Limit, memory_limit 128 MB. 5. Datenbank, Besucher-Log ohne Limit, Archivierungsabfragen zwei Stunden.
Jede Schicht hat ihre eigene Uhr. Die erste, die abläuft, beendet die Anfrage.

Wo die Zeitlimits sitzen#

Eine Anfrage an Matomo läuft durch mehrere Schichten, und jede hat ihre eigene Uhr. Die erste, die abläuft, beendet die Anfrage. Der Statuscode 504 bedeutet laut HTTP-Standard genau das: Ein Gateway oder Proxy hat vom Server dahinter nicht rechtzeitig eine Antwort bekommen.

  • Browser: Hier sehen Sie nur das Ergebnis: Ladekreisel, „Oops…“ oder die Fehlerseite des Servers.
  • Reverse Proxy oder Load Balancer: Ein vorgeschalteter Proxy wartet nur begrenzt, bei nginx sind es mit proxy_read_timeout standardmäßig 60 Sekunden. Load Balancer und CDNs haben eigene Grenzen; die Werte stehen in der Dokumentation Ihres Anbieters.
  • Webserver: nginx wartet mit fastcgi_read_timeout auf PHP-FPM, ebenfalls standardmäßig 60 Sekunden. Läuft die Zeit ab, schreibt nginx „upstream timed out“ ins Fehlerlog und antwortet mit 504. Bei Apache gilt Timeout (Standard 60 Sekunden); ist PHP-FPM über mod_proxy_fcgi angebunden, zählt ProxyTimeout, das ohne eigene Angabe den Wert von Timeout übernimmt.
  • PHP: max_execution_time beendet ein Skript standardmäßig nach 30 Sekunden, auf der Kommandozeile gilt 0, also kein Limit. memory_limit begrenzt den Speicher (Standard 128 MB). In PHP-FPM kann zusätzlich request_terminate_timeout den Worker beenden; der Standard ist 0, also aus.
  • Datenbank: Abfragen für Besucher-Log und Besucherprofil bricht Matomo standardmäßig nie ab, Archivierungsabfragen nach zwei Stunden.

Ein Detail erklärt, warum so oft der Webserver die 504 liefert: In der üblichen Linux-Konfiguration zählt PHP bei max_execution_time nur die Zeit, die das Skript selbst rechnet. Wartezeit auf Datenbankabfragen gehört laut PHP-Handbuch nicht dazu. Wartet Matomo 90 Sekunden auf MySQL, greift das PHP-Limit also nicht, das von nginx nach 60 Sekunden aber schon.

Welche Schicht war es?#

Die Logs verraten es meist:

  • „upstream timed out“ im nginx-Fehlerlog: nginx hat auf PHP gewartet.
  • „Maximum execution time of 30 seconds exceeded“: PHP hat das Skript beendet.
  • „Allowed memory size of … bytes exhausted“: kein Zeit-, sondern ein Speicherproblem. Für die Archivierung empfiehlt Matomo je nach Datenmenge 512 MB oder 2 GB, bei mittleren bis großen Instanzen sind 8 GB üblich. core:archive setzt selbst mindestens 768 MB.

Warum Matomo an diese Grenzen stößt#

Matomo speichert zuerst Rohdaten, Berichte entstehen erst durch die Archivierung. Teuer wird es, wenn diese Arbeit während einer Anfrage aus dem Browser oder einem Skript passiert.

  1. Archivierung beim Aufruf. Standardmäßig berechnet Matomo Berichte, wenn jemand sie in der Oberfläche aufruft. Berichte für heute gelten dabei nach 900 Sekunden als veraltet und werden beim nächsten Aufruf neu berechnet. Schon ab einigen Hundert Besuchen am Tag kann das laut Matomo Minuten dauern. Wer ungeduldig neu lädt, verschärft das Problem, wie Matomo selbst schreibt.
  2. Segmente in Echtzeit. Neue Segmente stehen standardmäßig auf „segmentierte Berichte werden in Echtzeit verarbeitet“. Anfragen mit so einem Segment stoßen die Berechnung an, selbst wenn die Browser-Archivierung abgeschaltet ist.
  3. Eigene Zeiträume. Tage, Wochen, Monate und Jahre berechnet die Cron-Archivierung vorab. Frei gewählte Zeiträume (period=range) nicht, mit Ausnahme der Standardzeiträume, die Nutzer in ihren Einstellungen wählen können (die letzten oder vorherigen 7 bzw. 30 Tage). Ein Bericht über „1. Januar bis heute“ entsteht deshalb beim Aufruf, auch bei abgeschalteter Browser-Archivierung.
  4. Exporte ohne Grenze. Die API liefert standardmäßig 100 Zeilen. Wer unter einer Tabelle „alle“ Zeilen wählt oder in der API filter_limit=-1 setzt, bekommt alles in einer Antwort. Für den Rohdaten-Export warnt Matomo: Ab etwa 10.000 Besuchen samt Aktionen kann die Anfrage sehr lange dauern oder abbrechen. Mehr als 4 GB Speicher empfiehlt Matomo dafür nicht, und manchmal reichen auch die nicht.
  5. Viele Websites. Berichte entstehen pro Website. Was auf Abruf berechnet wird, fällt bei einer Übersicht über alle Websites oder einem API-Aufruf mit idSite=all für jede einzelne an. Auf großen Servern mit vielen stark besuchten Websites kann schon die Archivierung laut Matomo Stunden dauern.

Was Matomo dagegen empfiehlt#

1. Archivierung per Cron, Browser-Archivierung aus#

Der wichtigste Schritt: Berichte nicht mehr beim Aufruf berechnen, sondern regelmäßig im Hintergrund. Auf der Kommandozeile gilt kein PHP-Zeitlimit, und kein Webserver wartet auf eine Antwort. Matomo empfiehlt einen stündlichen Lauf, als Benutzer des Webservers:

5 * * * * /usr/bin/php /var/www/matomo/console core:archive --matomo-domain=https://analytics.example.org > /dev/null

Danach unter Administration > System > Allgemeine Einstellungen:

  • „Berichte archivieren, wenn diese im Browser angezeigt werden“: Nein
  • „Archiviere Berichte mindestens alle X Sekunden“ (gemeint ist: höchstens): 3600

Damit auch Anfragen mit Segment keine Berechnung mehr anstoßen, ergänzen Sie in config/config.ini.php:

[General]
browser_archiving_disabled_enforce = 1

Stellen Sie vorher Ihre Segmente auf Vorverarbeitung um (nächster Abschnitt). Sonst zeigen Echtzeit-Segmente keine Daten mehr, sondern den Hinweis, dass die Konfiguration die Echtzeitverarbeitung aus Performancegründen verhindert.

Ein Haken: core:archive startet seine Arbeit als eigene PHP-Prozesse auf der Kommandozeile. Unterstützt das System das nicht, schickt es stattdessen HTTP-Anfragen an die eigene Instanz, und dann gelten wieder alle Webserver-Limits. Ob die Kommandozeilen-Variante funktioniert, zeigt:

./console diagnostics:run --all | grep -i "processes via cli"

Intervalle, Laufzeiten und hängende Cronjobs behandelt der Archivierungsartikel.

2. Segmente vorab verarbeiten#

Im Segment-Editor können Superuser für jedes Segment „Segmentierte Berichte werden im Voraus verarbeitet (schneller, benötigt archive.php Cron)“ wählen. Matomo empfiehlt das ausdrücklich, wenn die Echtzeit-Variante Berichte langsam macht. Drei Einstellungen in config/config.ini.php helfen auf Instanzen mit vielen Nutzern:

[General]
enable_create_realtime_segments = 0
process_new_segments_from = "segment_creation_time"
enable_segment_suggested_values = 0

Die erste zwingt neue Segmente in die Vorverarbeitung (bestehende Echtzeit-Segmente bleiben unverändert). Die zweite verhindert, dass ein neues Segment die gesamte Historie nachrechnet. Die dritte schaltet die Wertvorschläge im Segment-Editor ab; das empfiehlt Matomo bei sehr großen Datenbanken, auf denen die Vorschläge nicht rechtzeitig erscheinen.

Viele Segmente filtern nur einen Bereich der Website, etwa Blog oder Shop. Dafür gibt es unsere kostenlose Matomo-Erweiterung Page Filter Report: Sie legt Bereiche per URL-Muster an, und die Berichte dazu entstehen bei der normalen Archivierung.

3. Lange Zeiträume vorab berechnen#

Brauchen Sie einen bestimmten Zeitraum regelmäßig, kann die Cron-Archivierung ihn vorab berechnen:

[General]
archiving_custom_ranges[] = "last90"

Jeder Eintrag kostet Archivierungszeit, also nur für Zeiträume, die wirklich oft gebraucht werden. In Skripten hilft oft ein anderer Weg: Statt period=range fragen Sie period=month oder period=day ab und summieren selbst. Diese Perioden liegen nach dem Cron-Lauf fertig vor. Besuche oder Seitenaufrufe lassen sich so addieren, eindeutige Besucher nicht.

4. API-Abfragen in Seiten aufteilen#

Für große Datenmengen empfiehlt Matomo, nicht alles auf einmal zu holen, sondern 10.000 Zeilen pro Anfrage mit filter_limit und filter_offset:

?module=API&method=Live.getLastVisitsDetails&idSite=1&period=day&date=yesterday&format=json&filter_limit=10000&filter_offset=0
…&filter_limit=10000&filter_offset=10000
…&filter_limit=10000&filter_offset=20000

Das wiederholen Sie, bis keine Zeilen mehr kommen. Holen Sie Rohdaten tageweise, und schicken Sie das Token per POST statt in der URL; das empfiehlt Matomo aus Sicherheitsgründen. Mit showColumns oder hideColumns übertragen Sie nur die Spalten, die Sie wirklich brauchen.

Damit eine ausufernde Abfrage im Besucher-Log nicht unbegrenzt die Datenbank belegt, lässt sie sich begrenzen:

[General]
live_query_max_execution_time = 60

Das funktioniert laut Matomo nur mit MySQL ab 5.7 und der PHP-Erweiterung PDO_MYSQL; MariaDB unterstützt es unter Umständen nicht. Für Archivierungsabfragen gibt es archiving_query_max_execution_time (Standard 7200 Sekunden). Wird eine solche Abfrage abgebrochen, fehlt der Bericht womöglich, und Matomo meldet das nicht.

5. Geplante Berichte statt großer Ad-hoc-Exporte#

Wer regelmäßig dieselben Zahlen braucht, sollte sie nicht jedes Mal von Hand exportieren. Geplante Berichte gehen täglich, wöchentlich oder monatlich als HTML, PDF oder CSV per E-Mail hinaus. Versendet werden sie vom Archivierungs-Cron; ohne Cron hängt der Versand davon ab, dass gerade jemand eine getrackte Website besucht. Pro Tabelle enthalten sie standardmäßig 23 Zeilen, einstellbar über scheduled_reports_truncate, allerdings nur global für alle Berichte.

Tracking: wenn der Endpunkt unter Last aussteigt#

Timeouts gibt es auch auf der anderen Seite. Jede Tracking-Anfrage schreibt Matomo direkt in die Datenbank, und laut Plugin-Dokumentation kann eine solche Anfrage mehrere hundert Millisekunden dauern. Bei Lastspitzen kann der Server dann nicht mehr alle Anfragen direkt verarbeiten, etwa weil nginx oder MySQL zu viele Verbindungen haben.

Für diesen Fall verweist Matomo auf das Plugin QueuedTracking. Es schreibt Tracking-Anfragen zunächst in eine Warteschlange, bevorzugt in Redis, alternativ in MySQL. Das dauert nur wenige Millisekunden; verarbeitet werden die Anfragen danach gebündelt. Standardmäßig passiert das während einer Tracking-Anfrage, nachdem die Antwort an den Browser gegangen ist. Alternativ schalten Sie in den Plugin-Einstellungen „Process during tracking request“ ab und lassen einen Cronjob jede Minute arbeiten:

* * * * * cd /var/www/matomo && ./console queuedtracking:process > /dev/null 2>&1

Der Preis: Unter Last erscheinen neue Besuche erst mit Verzögerung in den Echtzeit-Berichten.

Was Sie besser lassen#

Alle Limits einfach hochzusetzen, verschiebt das Problem nur. Der Browser wartet länger, jede lange Anfrage belegt einen PHP-Prozess, und parallele Aufrufe stauen sich. Wenn Sie ein Limit anheben, dann gezielt und entlang der ganzen Kette: 300 Sekunden für PHP nützen nichts, wenn nginx nach 60 Sekunden aufgibt. Schwere Arbeit gehört auf die Kommandozeile, nicht in den Browser.

Checkliste#

  1. Logs prüfen: Webserver, PHP oder Speicher?
  2. Archivierung per Cron einrichten, Browser-Archivierung aus, Berichte für heute höchstens stündlich.
  3. Segmente auf Vorverarbeitung umstellen, dann browser_archiving_disabled_enforce = 1.
  4. Häufige eigene Zeiträume in archiving_custom_ranges[] eintragen.
  5. API-Skripte mit filter_limit und filter_offset in Seiten aufteilen, Rohdaten tageweise holen.
  6. Besucher-Log-Abfragen mit live_query_max_execution_time begrenzen.
  7. Wiederkehrende Exporte als geplante Berichte versenden.
  8. Bei Tracking-Spitzen QueuedTracking prüfen.

Wenn Sie sich darum nicht selbst kümmern möchten: In unserem Matomo-Hosting läuft die Archivierung als überwachter Hintergrundjob, abgestimmt auf Ihren Traffic, dazu Monitoring rund um die Uhr, Updates, Backups und Performance-Tuning. Den Umzug Ihrer bestehenden Instanz übernehmen wir, und Ihre Anfrage beantworten wir innerhalb eines Werktags.

Peter Boehlke

Über den Autor

Peter Boehlke

Gründer von feinwerk · Matomo-Spezialist seit 2009

Peter Boehlke arbeitet seit 2009 mit Matomo: als Mitglied des Matomo-Teams, Contributor zum Open-Source-Projekt und Implementation Partner im Matomo-Partnerprogramm. Mit feinwerk betreibt er Matomo-Instanzen bis in den High-Traffic-Bereich, entwickelt eigene Plugins für Matomo und berät zu Tag Management, Tracking-Konzepten und datenschutzkonformer Messung.

  • Matomo seit 2009
  • Matomo Implementation Partner
  • Matomo Contributor
  • Eigene Plugins für Matomo

Passt zu

Managed Matomo-Instanz

Unser Kernprodukt: Ihre Matomo-Instanz auf unserer Infrastruktur. Wir übernehmen Betrieb, Wartung und Optimierung, Sie behalten Ihre Daten.

Mehr zum Betrieb →

Passende Plugins

Plugins für Matomo aus eigener Entwicklung, die zu diesem Thema passen.

Hosting ab 99 € pro Monat · Angebot nach Bedarf

Erzählen Sie uns von Ihrem Matomo.

Beschreiben Sie kurz Traffic, Infrastruktur und Anforderungen. Sie erhalten innerhalb eines Werktags eine ehrliche Einschätzung und ein Angebot.

Worum geht es?