Company logoOpen Ticket AI

Logging System

Developer guide for using the logging system in Open Ticket AI with abstract interfaces and dependency injection.

Logging System

Open Ticket AI verwendet eine abstrakte Logging-Interface, die Entwickler ermöglicht, das Logging-Verhalten zu konfigurieren, ohne den Anwendungscode zu ändern. Die aktuelle Implementierung basiert vollständig auf Python’s Standardbibliothek logging Modul.

Übersicht

Das Logging-System bietet:

  • Abstrakte Interfaces: AppLogger und LoggerFactory Protokolle
  • Standardbibliothek-Implementierung: StdlibLoggerFactory
  • Dependency Injection: AppModule stellt LoggerFactory für automatische Setup bereit
  • Kontext-Bindung: Strukturierten Kontext zu Log-Messages anhängen mit der Logger API

Schnellstart

Verwenden mit Dependency Injection

Services können die LoggerFactory injizieren und verwenden, um Loggers mit gebundenem Kontext zu erstellen. Die Factory gibt Instanzen von StdlibLogger zurück, die zu logging.getLogger proxy.

Direkte Nutzung (ohne DI)

Der Standardbibliothek-Adapter kann direkt konfiguriert und verwendet werden, ohne den Dependency Injection Container. Konfigurieren Sie das Logging-System beim Anwendungsstart und erstellen Sie Loggers wie benötigt.

from open_ticket_ai.core.logging.logging_models import LoggingConfig
from open_ticket_ai.core.logging.stdlib_logging_adapter import (
    StdlibLoggerFactory,
    create_logger_factory,
)

config = LoggingConfig(level="INFO")
factory = create_logger_factory(config)

logger = factory.create("my_module")
logger.info("Application started")

Konfiguration

Runtime Konfiguration

Das Logging-System wird durch die Anwendung’s YAML Konfigurationsdatei unter dem infrastructure.logging Abschnitt konfiguriert, welcher durch das AppModule während des Dependency Injection Setup geladen wird.

LoggingConfig Felder

LoggingConfig definiert die unterstützte Runtime Konfiguration:

FeldTypDefaultBeschreibung
levelLiteral["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]"INFO"Minimum Severity Level, welches von Handlers aufgezeichnet wird.
log_to_fileboolFalseAktiviert das Schreiben von Log-Output zu einem File Handler.
log_file_pathstr | NoneNoneAbsolute oder relative Pfad für File Logging. Erforderlich wenn log_to_file True ist.
format.message_formatstr"%(asctime)s - %(name)s - %(levelname)s - %(message)s"Format String, welcher zu logging.Formatter gegeben wird.
format.date_formatstr"%Y-%m-%d %H:%M:%S"Timestamp Format, welcher vom Formatter verwendet wird.

Logging Implementierung

Stdlib (Python Standardbibliothek)

Der Standardbibliothek-Adapter wrappt Python’s eingebautes logging Modul.

Features:

  • Bekannte API für Python Entwickler
  • Kompatibel mit existierenden Logging Konfigurationen
  • Respektiert die LoggingConfig Optionen für Format, Level und optionalen File Output

Beispiel Output:

2025-10-11 00:21:14 - my_module - INFO - Application started

Handler Wiring

create_logger_factory bereitet den globalen Logging State vor:

  1. Hole den Root Logger und setze sein Level von LoggingConfig.level.
  2. Entferne alle vorher registrierten Handlers, um duplicate Messages zu vermeiden.
  3. Erstelle einen logging.Formatter mit log_format und date_format.
  4. Füge einen StreamHandler hinzu, welcher zu sys.stdout schreibt, konfiguriert mit dem gewählten Level und Formatter.
  5. Optional füge einen FileHandler hinzu, wenn log_to_file True ist und log_file_path gegeben ist.
  6. Gib eine StdlibLoggerFactory zurück, welche StdlibLogger Instanzen erstellt, gebunden zu named Loggers.

Kontext Bindung

Kontext Bindung ermöglicht Ihnen, strukturierte Daten zu Log-Messages anzuhängen. Erstellen Sie einen Base Logger mit Service Kontext, dann binden Sie request-spezifischen Kontext. Alle folgenden Log-Messages von diesem Logger werden den gebunden Kontext automatisch enthalten.

Logger Methoden

Das AppLogger Protokoll definiert die folgenden Methoden:

  • **bind(**kwargs)**: Erstellen einen neuen Logger mit zusätzlichen Kontext
  • **debug(message, **kwargs)**: Log Debug Information
  • **info(message, **kwargs)**: Log Informational Messages
  • **warning(message, **kwargs)**: Log Warnings
  • **error(message, **kwargs)**: Log Errors
  • **exception(message, **kwargs)**: Log Exceptions mit Traceback

Best Practices

1. Verwenden Dependency Injection

Injizieren Sie immer die LoggerFactory statt Loggers direkt zu erstellen. Dies ermöglicht einfachere Testing und Konfigurationsmanagement.

2. Bind Kontext früh

Erstellen Sie scoped Loggers mit gebunden Kontext für besser Traceability. Bind Kontext Daten wie Request IDs, User IDs oder Operation Namen früh, sodass alle folgenden Logs diese Information enthalten.

3. Verwenden angemessene Log Levels

  • DEBUG: Detailierte Diagnose Information
  • INFO: Allgemeine Informational Messages
  • WARNING: Warning Messages für potentiell schädliche Situationen
  • ERROR: Error Events, welche die App möglicherweise weiterlaufen lassen
  • EXCEPTION: Wie ERROR aber beinhaltet Exception Traceback

4. Beinhalten relevanten Kontext

Fügen Sie Kontext hinzu, welches hilft mit Debugging und Monitoring, wie:

  • Query Execution Time
  • Anzahl von rows affected
  • Table oder Resource Namen
  • Operation Identifiers

5. Log nicht sensitive Daten

Log niemals Passwörter, Tokens oder persönliche Information. Log immer Identifiers statt sensitive Werte.

Testing mit Logging

Wenn Sie Tests schreiben, können Sie Logging Behavior verifizieren, indem Sie Log Output capture und auf die Messages und Kontext Daten assert.

Migration Guide

Von direkt logging.getLogger()

Ersetzen Sie direkte Nutzung von Python’s Logging Modul mit Dependency Injection der LoggerFactory. Dies ermöglicht, die Logging Implementierung zu swap ohne Code Änderungen.

Von AppConfig.get_logger()

Ersetzen Sie Nutzungen von legacy Factory Helpers mit Dependency-Injected Instanzen von LoggerFactory erstellt durch create_logger_factory.

Future Roadmap

Die Logging Abstraktion ermöglicht, alternative Adapters (wie Structlog oder OpenTelemetry Exporters) in der Zukunft einzuführen. Diese Integrations sind aktuell unter Evaluation und noch nicht verfügbar. Diese Seite wird updated, wenn neue Implementations hinzugefügt werden, sodass Leser sie confidently adoptieren können.