Search by

el-choco / error-analyzer

el-choco

Group Flarum log errors, identify packages mentioned in stack traces, and prepare redacted support reports.

Package info

github.com/el-choco/error-analyzer

Type:flarum-extension

pkg:composer/el-choco/error-analyzer

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-18 18:24 UTC

This package is auto-updated.

Last update: 2026-11-18 18:39:44 UTC


README

Understand recurring forum log errors and prepare the information needed for support.

Version 1.0.0 · Flarum 2.0.2 or later · PHP 8.3 or later · MIT

Installation

Once version 1.0.0 is available on Packagist, run these commands from the Flarum installation directory as the forum's filesystem user:

composer require el-choco/error-analyzer:"^1.0" --update-no-dev --minimal-changes --no-scripts --no-interaction
php flarum cache:clear --force

Enable Error Analyzer in the administration panel. No worker or database migration is required.

For Docker, run Composer and Flarum commands inside the forum container as its Flarum user. With CrazyMax, run extension sync after the successful Composer operation and before clearing the cache to persist the extension list. Keep the Composer home used by your image. Container names and paths depend on your installation.

Choosing a version constraint

The recommended constraint is "^1.0": it allows compatible releases from 1.0.0 up to, but excluding, 2.0.0. Future 1.x releases can then be selected by a targeted Composer update or an update action in a management extension.

"*" also works, but permits any version, including future major releases such as 2.0.0. Composer's stability settings still determine whether prereleases are eligible. An exact constraint such as "1.0.0" keeps that version pinned until you change the requirement. Updates are not installed automatically by the constraint alone.

Updating

composer update el-choco/error-analyzer --update-no-dev --minimal-changes --no-scripts --no-interaction
php flarum cache:clear --force

Use the same user, directory and container settings as installation, including extension sync with CrazyMax. Reload PHP-FPM if OPcache retains old code, then refresh the admin page.

If upgrading from a local path installation, first remove or update its repository definition: a canonical local path repository can prevent Composer from selecting the Packagist release. Keep local sources until Composer no longer references them. Remove the repository entry from the configuration where it was defined (project or global). Then run the installation command above with "^1.0" to replace any pinned alpha requirement. A plain composer update does not change that requirement.

Source and issues · Packagist

Features

  • An admin page under Administration → Extensions → Error Analyzer.
  • Reads multiline Flarum/Monolog logs and one-record-per-line Monolog JSON logs.
  • Groups repeated entries by level, redacted message, initial stack frames and identified packages. Numeric values are normalized for grouping.
  • Shows occurrence counts and the first and last occurrence within the scanned sample.
  • Search by message or package, filter by package and sort by recency or frequency.
  • Identifies package paths using Composer's installed.json, including local packages with an install-path entry.
  • Attributes known message prefixes and identifies the evidence in the interface and report. [depot] maps to the installed ernestdefoe/depot. An explicit installed Composer package prefix such as [fof/upload] is also recognized.
  • Distinguishes extensions, core and libraries and shows their currently installed versions.
  • Prepares an editable report with reproduction notes, Flarum and web PHP versions, the redacted excerpt and packages mentioned in it.
  • Optionally includes the complete installed extension list and activation states.
  • Copies the reviewed report or saves it as a text file.
  • English and German interface translations.

Usage

  1. Open the extension's admin page and select Analyse logs.
  2. Choose an error group and inspect the packages and captured stack frames.
  3. Describe what happened, the expected result and how to reproduce the problem.
  4. Prepare the report and review the complete text.
  5. Copy the report into your support request or save it as text.

Every attribution shows Package path in log excerpt, Hint from log prefix, or both. Other short aliases require a reviewed mapping. The referenced package must be installed according to Composer metadata. It does not establish causation. Versions reflect the current installation and may differ from those installed when an older error occurred.

Scan scope

Scanning starts only when requested. It considers regular .log files in Flarum's storage/logs, newest by modification time first. Choose five, ten or twenty files.

Each file contributes at most its last 1 MiB. A scan reads at most 8 MiB, examines at most 2,500 recognized records, returns at most 200 groups and enumerates at most 2,000 directory entries. The interface reports limits and skipped files. Counts apply to the captured sample. Older records and large entries can fall outside it. Search filters the loaded snapshot.

Timestamps without an explicit timezone are interpreted as UTC. The interface displays dates in the browser's timezone.

Sensitive information

Redaction runs on the server before returning data to the browser. Additional request contexts and stack arguments are omitted. Common credential fields, known token patterns, URLs, email and IP addresses, private keys and local installation paths are masked. SQL statement text is omitted.

Automatic redaction can miss unfamiliar secrets and personal information in arbitrary messages. Review the report before sharing. Your own reproduction notes are included as entered.

Only administrators can access the API. Responses use no-store cache headers. The extension does not create a database of errors or modify log files. Reports and reproduction notes remain in the open admin page until you copy or download them. No report is sent automatically and no external analysis service is contacted.

Requirements and limitations

  • Flarum ^2.0.2 and PHP ^8.3. This initial release targets Flarum 2.
  • Web PHP needs read access to logs and vendor/composer/installed.json.
  • Recognizes standard Flarum logs and Monolog JSON records containing datetime, level_name and message.
  • External log formats, Docker logs, systemd journals and web server/PHP-FPM logs outside storage/logs require additional integrations.
  • The admin page requires a working Flarum installation.
  • Works independently of Log Viewer and Admin Console.
  • No additional worker, scheduled job or database migration is required.

Development

The installable ZIP includes the compiled frontend. Node.js is required only for development.

cd js
npm ci
npm run build
npm test

Run backend checks with PHP 8.3+ and a separate Flarum 2 dependency autoloader.

php tests/run.php /path/to/test-forum/vendor/autoload.php

Tests create their own temporary log and package fixtures and check grouping, filtering, limits, package attribution, redaction and authorization with real Flarum dependencies. Browser checks use sample data. The maintainer has repeatedly tested the functionality successfully on Flarum 2.0.2 with web PHP 8.5.12 in a CrazyMax container, including prefix attribution. Version 1.0.0 publishes that tested functionality as the first stable release.

Error Analyzer

Fehler im Forum schneller einordnen und die passenden Informationen für den Support zusammenstellen.

Version 1.0.0 · Flarum ab 2.0.2 · PHP ab 8.3 · MIT

Installation

Sobald Version 1.0.0 auf Packagist verfügbar ist, diese Befehle im Flarum-Verzeichnis als Dateisystembenutzer des Forums ausführen:

composer require el-choco/error-analyzer:"^1.0" --update-no-dev --minimal-changes --no-scripts --no-interaction
php flarum cache:clear --force

Error Analyzer anschließend im Adminbereich aktivieren. Ein Worker oder eine Datenbankmigration ist nicht erforderlich.

Bei Docker die Composer- und Flarum-Befehle im Forum-Container als Flarum-Benutzer ausführen. Bei CrazyMax nach erfolgreichem Composer-Vorgang und vor dem Cache-Leeren zusätzlich extension sync ausführen, damit die Erweiterungsliste gespeichert wird. Das von deinem Image verwendete Composer-Home beibehalten. Containername und Pfade hängen von deiner Installation ab.

Versionsvorgabe wählen

Empfohlen ist "^1.0": Damit sind Versionen ab 1.0.0 bis ausschließlich 2.0.0 erlaubt. Zukünftige 1.x-Versionen können dann durch ein gezieltes Composer-Update oder die Update-Funktion einer Verwaltungserweiterung ausgewählt werden.

"*" funktioniert ebenfalls, erlaubt aber alle Versionen einschließlich späterer Hauptversionen wie 2.0.0. Composers Stabilitätseinstellungen bestimmen weiterhin, ob Vorabversionen infrage kommen. Eine exakte Vorgabe wie "1.0.0" hält diese Version fest, bis du die Vorgabe änderst. Allein durch die Versionsvorgabe werden keine Updates automatisch installiert.

Aktualisieren

composer update el-choco/error-analyzer --update-no-dev --minimal-changes --no-scripts --no-interaction
php flarum cache:clear --force

Dieselben Benutzer-, Verzeichnis- und Container-Einstellungen wie bei der Installation verwenden, einschließlich extension sync bei CrazyMax. Falls OPcache alten Code hält, PHP-FPM neu laden und anschließend den Adminbereich aktualisieren.

Bei einem Wechsel von einer lokalen Path-Installation zunächst deren Repository-Eintrag entfernen oder aktualisieren: Ein kanonisches lokales Repository kann die Auswahl der Packagist-Version verhindern. Lokale Quellen erst entfernen, wenn Composer nicht mehr darauf verweist. Den Repository-Eintrag in der Konfiguration entfernen, in der er angelegt wurde (Projekt oder global). Danach den Installationsbefehl oben mit "^1.0" ausführen, um eine festgelegte Alpha-Version zu ersetzen. Ein einfaches composer update ändert diese Versionsvorgabe nicht.

Quellcode und Fehlerberichte · Packagist

Funktionen

  • Analyse direkt unter Administration → Erweiterungen → Error Analyzer.
  • Mehrzeilige Flarum-/Monolog-Logs und zeilenweise Monolog-JSON-Logs lesen.
  • Wiederkehrende Meldungen nach Schweregrad, bereinigter Meldung, ersten Aufrufstellen und erkannten Paketen gruppieren. Zahlenwerte werden für die Gruppierung vereinheitlicht.
  • Häufigkeit sowie erstes und letztes Vorkommen innerhalb des gelesenen Ausschnitts zeigen.
  • Nach Meldung oder Paket suchen, nach Paket filtern und nach Häufigkeit oder letztem Auftreten sortieren.
  • Paketpfade mit Composers installed.json abgleichen. Die angezeigten Versionen stammen aus dem aktuell installierten Paketstand.
  • Bekannte Log-Präfixe zuordnen und die Grundlage am Paket sowie im Supportbericht anzeigen. [depot] verweist auf das installierte ernestdefoe/depot. Präfixe mit einem vollständigen installierten Composer-Paketnamen, beispielsweise [fof/upload], werden ebenfalls erkannt.
  • Erweiterungen, Flarum-Kern und Bibliotheken unterscheiden. Lokale Composer-Pakete können über install-path zugeordnet werden.
  • Einen Supportbericht mit Problembeschreibung, Flarum-Version, Web-PHP-Version, Fehlerauszug und beteiligten Paketen vorbereiten.
  • Optional die komplette Liste installierter Erweiterungen mit Aktivierungsstatus aufnehmen.
  • Den Bericht vor dem Teilen bearbeiten, kopieren oder als Textdatei herunterladen.
  • Deutsche und englische Oberfläche.

So verwendest du die Erweiterung

  1. Öffne Error Analyzer im Adminbereich und klicke Logs analysieren.
  2. Wähle eine Fehlergruppe. Die Paketliste zeigt, welche Pakete in den erfassten Aufrufstellen vorkommen.
  3. Beschreibe, was passiert ist und wie sich das Problem nachstellen lässt.
  4. Erzeuge den Bericht und prüfe den gesamten Text.
  5. Kopiere ihn in deine Supportanfrage oder speichere ihn als Textdatei.

Bei jeder Paketzuordnung steht Paketpfad im Logauszug oder Hinweis aus Log-Präfix. Treffen beide zu, werden beide angezeigt. Andere kurze Präfixe werden erst nach einer geprüften Zuordnung ergänzt. Die jeweilige Erweiterung muss in Composers Paketmetadaten installiert sein.

Ein zugeordnetes Paket ist ein Anhaltspunkt für die Untersuchung. Seine Nennung belegt keine Fehlerursache. Die Paketversion beschreibt den aktuellen Stand, der vom Stand zum damaligen Fehlerzeitpunkt abweichen kann.

Umfang der Analyse

Die Analyse startet ausschließlich durch den Button. Sie liest reguläre .log-Dateien unter Flarums storage/logs. Standardmäßig werden die fünf zuletzt geänderten Dateien berücksichtigt. Zehn oder zwanzig Dateien sind wählbar.

Pro Datei wird höchstens das letzte MiB gelesen, insgesamt höchstens 8 MiB pro Analyse. Weitere Grenzen sind 2.500 erkannte Einträge, 200 Fehlergruppen und 2.000 Verzeichniseinträge. Erreichte Grenzen und übersprungene Dateien werden angezeigt. Die Häufigkeit ist damit eine Anzahl innerhalb des erfassten Ausschnitts. Große oder alte Einträge können außerhalb liegen.

Fehlerursachen, die erst nach langer Zeit mehrfach auftreten, können in verschiedenen Logrotationen liegen. Die Suche arbeitet nur innerhalb des jeweils geladenen Ergebnisses. Logs ohne Zeitzonenangabe werden als UTC interpretiert. Die Oberfläche zeigt Zeiten in der Zeitzone des Browsers.

Umgang mit vertraulichen Angaben

Der Server erstellt den bereinigten Auszug vor der Antwort an den Browser. Zusätzliche Anfragekontexte und Argumente von Stack-Aufrufen werden ausgelassen. Häufige Passwort-/Token-Felder, bekannte Tokenformate, URLs, E-Mail-Adressen, IP-Adressen, private Schlüssel und lokale Installationspfade werden maskiert. SQL-Anweisungstexte werden aus dem Auszug entfernt.

Die automatische Maskierung kann unbekannte Geheimnisse und persönliche Angaben in frei formulierten Fehlermeldungen übersehen. Prüfe den Bericht vor dem Teilen. Deine eigene Problembeschreibung wird so übernommen, wie du sie eingibst.

Zugriff auf die API haben ausschließlich Administratoren. Antworten erhalten no-store-Header. Die Erweiterung legt keine Fehlerdatenbank an und verändert keine Logdateien. Bericht und Problembeschreibung werden im geöffneten Adminbereich gehalten. Erst Kopieren oder Herunterladen erzeugt eine von dir weiterverwendbare Kopie. Die Erweiterung versendet keine Berichte und ruft keine externen Analysedienste auf.

Voraussetzungen und Grenzen

  • Flarum ^2.0.2 und PHP ^8.3. Diese erste Ausgabe ist für Flarum 2 gebaut.
  • Web-PHP muss die Logdateien und vendor/composer/installed.json lesen können.
  • Standard-Flarum-Logs und Monolog-JSON mit datetime, level_name und message werden erkannt. Andere Formate, systemd-Journale sowie Docker-, Webserver- und PHP-FPM-Logs außerhalb von storage/logs benötigen eine eigene Anbindung.
  • Ein nicht mehr startender Flarum-Adminbereich ist über diese Oberfläche nicht erreichbar.
  • Log Viewer und Admin Console können parallel installiert sein. Error Analyzer benötigt beide nicht.
  • Ein zusätzlicher Worker, Cronjob oder Datenbankmigrationen sind für diese Ausgabe nicht erforderlich.

Entwicklung und Prüfungen

Das installierbare ZIP enthält den gebauten Admin-Bundle. Nur zum Entwickeln wird Node.js benötigt.

cd js
npm ci
npm run build
npm test

Backend-Prüfung mit einem separaten Flarum-2-Autoloader und PHP 8.3 oder neuer durchführen.

php tests/run.php /pfad/zum/testforum/vendor/autoload.php

Die Tests legen eigene temporäre Log- und Paketdateien an. Sie prüfen Gruppierung, Filter, Begrenzungen, Paketzuordnung, Maskierung und Zugriffsschutz mit echten Flarum-Abhängigkeiten. Browserprüfungen verwenden Beispieldaten. Der Betreiber hat die Funktionen einschließlich der Präfixzuordnung mehrfach erfolgreich mit Flarum 2.0.2 und Web-PHP 8.5.12 im CrazyMax-Container getestet. Version 1.0.0 veröffentlicht diesen getesteten Funktionsumfang als erste stabile Ausgabe.