Modularer Logbuch-Reader

Ein modular erweiterbarer, performanter Logbuch-Reader mit moderner Benutzeroberfläche (Flet) zur Analyse, Strukturierung und Visualisierung von Logdateien (insb. Java-Applikationslogs und E-Mail-Client-Logs).

Das Tool bietet out-of-the-box Support für mehrzeilige Logs (Stacktraces), hierarchische Trace-ID-Gruppierung und lässt sich nahtlos über ein dynamisches Plugin-System erweitern sowie in den Windows Explorer integrieren.

---

🚀 Features

• Modernes Dark-Theme Layout: Schonend für die Augen mit farblicher Loglevel-Markierung (DEBUG, INFO, WARN, ERROR).
• Multi-line & Stacktrace Support: Erkennt Java-Exceptions und stellt Stacktraces einklappbar (ExpansionTile) in der GUI dar.
• Hierarchische Gruppierung (Trace-IDs): Gruppiert Logs (z.B. Mail-Client-Aktivitäten) nach eindeutigen Trace-IDs in einer interaktiven Sidebar-Filterstruktur.
• Live-Suche & Performance: Filtert Log-Einträge in Echtzeit per Freitextsuche; optimierte Render-Performance (Virtual Scrolling) für große Logdateien.
• Erweiterbares Plugin-System: Auto-Discovery von Parser-Plugins im Ordner parsers/ ohne Codeänderungen am Core.
• Kommandozeilen- & GUI-Modus: Direktes Öffnen von Logdateien via CLI-Parameter, optimal für die Verknüpfung im Betriebssystem.

---

📁 Projektstruktur

logbuchreader/
│
├── core/
│   ├── __init__.py
│   ├── base_parser.py       # Abstrakte Basisklasse für alle Parser-Plugins
│   └── parser_manager.py    # Auto-Discovery und Auswahl des passenden Parsers
│
├── parsers/
│   ├── __init__.py
│   ├── default_parser.py    # Parser für Standard- und Java-Logs (Stacktrace-Kompression)
│   └── mail_parser.py       # Spezial-Parser für Trace-ID-Gruppierung (operation-*.log)
│
├── assets/
│   └── register_log_viewer.reg  # Windows Registry Skript zur Dateiverknüpfung
│
├── samples/                 # Test- und Demonstrations-Logdateien
│   ├── java_exception.log
│   └── operation-email.log
│
├── tests/                   # Automatisierte Unit-Tests (pytest)
│   ├── test_parser_manager.py
│   └── test_parsers.py
│
├── main.py                  # Haupteinstiegspunkt (steuert CLI & GUI)
├── gui.py                   # Grafische Benutzeroberfläche in Flet
├── status.md                # Entwicklungs- und Phasenstatus
├── requirements.txt         # Projektabhängigkeiten
└── README.md                # Projektdokumentation (dieses Dokument)

---

🛠️ Lokales Setup (Entwickler)

1. Repository klonen und vorbereiten

Stelle sicher, dass Python 3.10+ installiert ist.

git clone <repository-url>
cd logbuchreader

2. Virtuelles Python-Environment (venv) anlegen

Erstelle eine isolierte Python-Umgebung im Projektstamm:

# Unter Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

# Unter Windows
python -m venv .venv
.venv\Scripts\activate

3. Abhängigkeiten installieren

pip install -r requirements.txt

---

🎮 Anwendung starten

Das Tool lässt sich flexibel im GUI-Modus oder im CLI-Modus aufrufen:

1. GUI-Modus (Standard)

Startet die grafische Oberfläche. Optional kann direkt eine Logdatei beim Start übergeben werden:

# Leere GUI starten
python main.py

# GUI direkt mit einer bestimmten Datei öffnen
python main.py --file samples/java_exception.log

2. CLI-Modus (JSON-Ausgabe)

Parst eine Logdatei und gibt die standardisierte JSON-Struktur direkt im Terminal aus:

python main.py --cli --file samples/operation-email.log

---

🧪 Unit-Tests ausführen

Die gesamte Kern- und Parserfunktionalität wird über Unit-Tests abgesichert. Starte diese mit:

python -m pytest tests/

---

🔌 Neuen Parser hinzufügen (Plugin-System)

Das Tool verfügt über ein automatisches Erkennungssystem für Parser. Um ein neues Log-Format zu unterstützen, muss ausschließlich eine neue Python-Datei im Verzeichnis parsers/ abgelegt werden:

1. Erstelle eine neue Datei in parsers/ (z. B. my_custom_parser.py).
2. Erbe von BaseParser aus core.base_parser.
3. Implementiere die Methoden can_handle und parse.

Code-Beispiel:

from typing import Any, Dict, List
from core.base_parser import BaseParser

class MyCustomParser(BaseParser):
    def can_handle(self, filepath: str, sample_lines: List[str]) -> bool:
        # Entscheide anhand des Dateinamens oder der ersten Zeilen,
        # ob dieser Parser zuständig ist.
        return filepath.endswith(".custom") or "MY-SYSTEM" in "".join(sample_lines)

    def parse(self, filepath: str) -> Dict[str, Any]:
        # Analysiere die Datei und gib eine standardisierte flache
        # oder hierarchische Datenstruktur zurück.
        entries = []
        with open(filepath, "r", encoding="utf-8", errors="replace") as f:
            for line in f:
                entries.append({
                    "timestamp": "2026-07-09 12:00:00", # Beispiel extrahiert
                    "level": "INFO",
                    "message": line.strip(),
                    "is_stacktrace": False
                })
                
        return {
            "mode": "flat",
            "entries": entries
        }

Beim nächsten Start der Anwendung wird dein neuer Parser automatisch geladen und verwendet!

---

📦 Deployment & Windows-Explorer-Integration

1. Kompilierung als eigenständige Windows-Anwendung (.exe)

Verwende PyInstaller, um die Anwendung in eine portable .exe zu kompilieren. Führe dazu folgendes im Terminal (auf einem Windows-System im aktivierten venv) aus:

pip install pyinstaller
pyinstaller --onefile --windowed main.py

Die fertige ausführbare Datei befindet sich danach im Ordner dist/main.exe (kann in logviewer.exe umbenannt werden).

2. Doppelklick-Verknüpfung für .log-Dateien

Um Logdateien direkt per Doppelklick im Logbuch-Reader zu öffnen, stellt das Projekt eine .reg-Konfiguration bereit:

1. Öffne die Datei assets/register_log_viewer.reg im Texteditor.
2. Ersetze C:\\Pfad\\zu\\logviewer.exe durch den tatsächlichen, absoluten Pfad zu deiner kompilierten Exe-Datei (wichtig: Backslashes doppelt schreiben!).
3. Speichere die Datei und führe sie per Doppelklick aus, um die Einträge in die Windows-Registrierungsdatenbank zu übernehmen.
4. Fertig! Künftig öffnet ein Doppelklick auf eine .log Datei direkt unseren Logbuch-Reader.