# ADR-003: Logging mit loguru

**Status:** Akzeptiert
**Datum:** 2025-10-15
**Kontext:** PoC questra-data Python Package

## Kontext und Problemstellung

Das questra-data Package benötigt Logging für Debugging, Monitoring und Fehleranalyse. Die Standardlösung in Python ist das `logging`-Modul aus der Standard-Library. Alternative moderne Logging-Libraries wie `loguru` bieten erweiterte Features und einfachere APIs.

Die Frage ist: Sollten wir beim Standard-Logging bleiben oder auf loguru umsteigen?

## Entscheidung

Wir verwenden **loguru** für Logging in questra-data.

## Begründung

### Pro

- **Zero Configuration:** Sofort einsatzbereit ohne Setup-Boilerplate

  ```python
  from loguru import logger
  logger.info("Ready to use")
  ```

- **Pythonic String-Formatting:** Native Unterstützung für `{}` und f-strings statt `%s`

  ```python
  logger.info("User {} logged in", username)
  logger.info(f"User {username} logged in")  # Auch möglich
  ```

- **Automatisches Exception-Tracking:** Decorator `@logger.catch` für automatisches Traceback-Logging
- **Strukturiertes Logging:** `logger.bind()` und `contextualize()` für kontextbezogene Log-Metadaten

  ```python
  logger = logger.bind(request_id="123", user="admin")
  logger.info("Operation completed")  # Enthält automatisch Kontext
  ```

- **Flexible Output-Konfiguration:** Einfache Rotation, Retention, JSON-Serialisierung

  ```python
  logger.add("questra_data.log", rotation="500 MB", retention="10 days")
  logger.add("errors.json", serialize=True, level="ERROR")
  ```

- **Secret Masking:** Filter für sensible Daten direkt integrierbar
- **Bessere Developer Experience:** Intuitivere API, weniger Boilerplate
- **Colored Output:** Automatisches Syntax-Highlighting in Terminal

### Contra

- **Zusätzliche Dependency:** External Package erforderlich (aber stabil und weit verbreitet, ~10 MB)
- **Infrastruktur-Integration:** Bei Integration in größere Systeme mit Standard-Logging ggf. Adapter erforderlich
- **Lernkurve:** Team muss sich mit loguru-spezifischen Features vertraut machen
- **Less Standard:** Nicht Teil der Python Standard Library
- **Performance Overhead:** Minimal langsamer als Standard-Logging (in den meisten Fällen vernachlässigbar)

## Alternativen

### Standard-Logging (logging)

- **Pro:** Standard-Library, keine Dependency, universell bekannt
- **Contra:** Verbose Setup, umständliche Konfiguration, alte API

### structlog

- **Pro:** Fokus auf strukturiertes Logging, gut für maschinenlesbare Logs
- **Contra:** Noch mehr Setup als Standard-Logging, komplexer

### python-json-logger

- **Pro:** JSON-Output für Standard-Logging
- **Contra:** Löst nur Teilproblem, kein verbessertes API

## Konsequenzen

### Positiv

- Schnellere Entwicklung durch weniger Logging-Boilerplate
- Bessere Debugging-Erfahrung durch strukturierte und farbige Logs
- Einfachere Log-Rotation und Archivierung
- Automatisches Exception-Tracking mit `@logger.catch`
- Secret-Masking für DSGVO/Security-Compliance

### Negativ

- Zusätzliche Dependency im Package
- Bei Integration in Enterprise-Systeme ggf. Adapter zu Standard-Logging erforderlich
- Team muss loguru-Best-Practices lernen

## Implementation

```python
from loguru import logger

# Basic Usage
logger.debug("Debug information")
logger.info("Processing inventory: {}", inventory_name)

# Exception Handling
@logger.catch
def create_inventory(self, ...):
    # Automatisches Exception-Logging
    ...

# Structured Logging
logger = logger.bind(operation="create_item", inventory="Products")
logger.info("Item created successfully")

# Configuration
logger.add(
    "questra_data.log",
    rotation="500 MB",
    retention="10 days",
    level="DEBUG"
)
```

## Notizen

loguru ist ideal für moderne Python-Libraries und PoCs. Die Developer Experience ist deutlich besser als Standard-Logging. Falls später Integration in Enterprise-Systeme erforderlich ist, kann ein Logging-Adapter implementiert werden, der loguru auf Standard-Logging abbildet.

Die Dependency ist vertretbar, da loguru aktiv maintained wird und in der Python-Community weit verbreitet ist (Stand 2025).
