logging — Logging-Einrichtung für Python

Quellcode: Lib/logging/__init__.py

Wichtig

Diese Seite enthält die API-Referenzinformationen. Für Tutorial-Informationen und Diskussionen über fortgeschrittenere Themen siehe

• Grundlegendes Tutorial

• Fortgeschrittenes Tutorial

• Logging Cookbook

---

Dieses Modul definiert Funktionen und Klassen, die ein flexibles Ereignisprotokollierungssystem für Anwendungen und Bibliotheken implementieren.

Der Hauptvorteil der Bereitstellung der Logging-API durch ein Standardmodul der Bibliothek ist, dass alle Python-Module an der Protokollierung teilnehmen können, sodass Ihr Anwendungslog Ihre eigenen Meldungen integriert mit Meldungen von Drittanbietermodulen enthalten kann.

Hier ist ein einfaches Beispiel für idiomatisches Vorgehen

# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')

if __name__ == '__main__':
    main()

# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')

Wenn Sie myapp.py ausführen, sollten Sie dies in myapp.log sehen

INFO:__main__:Started
INFO:mylib:Doing something
INFO:__main__:Finished

Das Hauptmerkmal dieses idiomatischen Vorgehens ist, dass der Großteil des Codes einfach einen Logger auf Modulebene mit getLogger(__name__) erstellt und diesen Logger verwendet, um jegliche erforderliche Protokollierung durchzuführen. Dies ist prägnant und ermöglicht dennoch eine feingranulare Steuerung für nachfolgenden Code, falls erforderlich. Protokollierte Meldungen an den Logger auf Modulebene werden an Handler von Loggern in Modulen höherer Ebenen weitergeleitet, bis hin zum Logger der höchsten Ebene, dem sogenannten Root-Logger; dieser Ansatz wird als hierarchische Protokollierung bezeichnet.

Damit die Protokollierung nützlich ist, muss sie konfiguriert werden: Festlegen der Ebenen und Ziele für jeden Logger, möglicherweise Ändern der Protokollierung bestimmter Module, oft basierend auf Befehlszeilenargumenten oder Anwendungszielen. In den meisten Fällen, wie im obigen Beispiel, muss nur der Root-Logger konfiguriert werden, da alle Logger niedrigerer Ebenen auf Modulebene ihre Meldungen schließlich an seine Handler weiterleiten. basicConfig() bietet eine schnelle Möglichkeit, den Root-Logger zu konfigurieren, der viele Anwendungsfälle abdeckt.

Das Modul bietet viel Funktionalität und Flexibilität. Wenn Sie mit der Protokollierung nicht vertraut sind, ist der beste Weg, sich damit vertraut zu machen, die Tutorials anzusehen (siehe die Links oben und rechts).

Die vom Modul definierten Grundklassen sowie ihre Attribute und Methoden sind in den folgenden Abschnitten aufgeführt.

• Logger stellen die Schnittstelle bereit, die der Anwendungscode direkt verwendet.

• Handler senden die Protokolldatensätze (erstellt von Loggern) an das entsprechende Ziel.

• Filter bieten eine feingranulare Möglichkeit, zu bestimmen, welche Protokolldatensätze ausgegeben werden sollen.

• Formatter geben das Layout von Protokolldatensätzen in der endgültigen Ausgabe an.

Logger-Objekte

Logger haben die folgenden Attribute und Methoden. Beachten Sie, dass Logger NIEMALS direkt instanziiert werden sollten, sondern immer über die Funktion logging.getLogger(name) auf Modulebene. Mehrere Aufrufe von getLogger() mit demselben Namen geben immer eine Referenz auf dasselbe Logger-Objekt zurück.

Der name ist potenziell ein durch Punkte getrennter hierarchischer Wert, wie z. B. foo.bar.baz (obwohl es auch nur ein einfacher foo sein könnte). Logger, die weiter unten in der hierarchischen Liste stehen, sind Kinder von Loggern, die weiter oben in der Liste stehen. Wenn Sie beispielsweise einen Logger mit dem Namen foo haben, sind Logger mit den Namen foo.bar, foo.bar.baz und foo.bam alle Nachkommen von foo. Zusätzlich sind alle Logger Nachkommen des Root-Loggers. Die Logger-Namenshierarchie ist analog zur Python-Pakethierarchie und identisch mit ihr, wenn Sie Ihre Logger pro Modul basis mit der empfohlenen Konstruktion logging.getLogger(__name__) organisieren. Das liegt daran, dass in einem Modul __name__ der Name des Moduls im Python-Paketnamensraum ist.

class logging.Logger

name

Dies ist der Name des Loggers und der Wert, der an getLogger() übergeben wurde, um den Logger zu erhalten.

Hinweis

Dieses Attribut sollte als schreibgeschützt behandelt werden.

level

Die Schwelle dieses Loggers, wie sie durch die Methode setLevel() festgelegt wurde.

Hinweis

Setzen Sie dieses Attribut nicht direkt – verwenden Sie immer setLevel(), das Prüfungen für die übergebene Ebene enthält.

parent

Der übergeordnete Logger dieses Loggers. Er kann sich aufgrund späterer Instanziierung von Loggern ändern, die sich höher in der Namensraumhierarchie befinden.

Hinweis

Dieser Wert sollte als schreibgeschützt behandelt werden.

propagate

Wenn dieses Attribut als wahr ausgewertet wird, werden Ereignisse, die an diesen Logger protokolliert werden, zusätzlich zu allen an diesen Logger angehängten Handlern an die Handler von übergeordneten (Vorfahren-)Loggern weitergeleitet. Meldungen werden direkt an die Handler der Vorfahren-Logger weitergegeben – weder die Ebene noch die Filter der betreffenden Vorfahren-Logger werden berücksichtigt.

Wenn dies als falsch ausgewertet wird, werden Protokollmeldungen nicht an die Handler von Vorfahren-Loggern weitergegeben.

Ausgeschrieben mit einem Beispiel: Wenn das Attribut propagate des Loggers mit dem Namen A.B.C als wahr ausgewertet wird, wird jedes an A.B.C über einen Methodenaufruf wie logging.getLogger('A.B.C').error(...) protokollierte Ereignis [vorbehaltlich der Prüfung der Ebene und Filter dieses Loggers] nacheinander an alle Handler übergeben, die an die Logger mit den Namen A.B, A und den Root-Logger angehängt sind, nachdem es zuerst an alle an A.B.C angehängten Handler übergeben wurde. Wenn ein Logger in der Kette A.B.C, A.B, A sein propagate-Attribut auf falsch gesetzt hat, dann ist dies der letzte Logger, dessen Handler das Ereignis zur Bearbeitung angeboten werden, und die Weiterleitung stoppt an dieser Stelle.

Der Konstruktor setzt dieses Attribut auf True.

Hinweis

Wenn Sie einen Handler an einen Logger und einen oder mehrere seiner Vorfahren anhängen, kann derselbe Datensatz mehrmals ausgegeben werden. Im Allgemeinen sollten Sie einen Handler nicht an mehr als einen Logger anhängen müssen – wenn Sie ihn einfach an den entsprechenden Logger anhängen, der sich am höchsten in der Logger-Hierarchie befindet, wird er alle von allen untergeordneten Loggern protokollierten Ereignisse sehen, vorausgesetzt, ihre propagate-Einstellung bleibt auf True gesetzt. Ein häufiges Szenario ist, Handler nur an den Root-Logger anzuhängen und die Weiterleitung den Rest erledigen zu lassen.

handlers

Die Liste der Handler, die direkt an diese Logger-Instanz angehängt sind.

Hinweis

Dieses Attribut sollte als schreibgeschützt behandelt werden; es wird normalerweise über die Methoden addHandler() und removeHandler() geändert, die Sperren verwenden, um einen threadsicheren Betrieb zu gewährleisten.

disabled

Dieses Attribut deaktiviert die Verarbeitung aller Ereignisse. Es wird im Initialisierer auf False gesetzt und nur von der Logging-Konfigurationslogik geändert.

Hinweis

Dieses Attribut sollte als schreibgeschützt behandelt werden.

setLevel(level)

Setzt die Schwelle für diesen Logger auf level. Protokollmeldungen, die weniger schwerwiegend sind als level, werden ignoriert; Protokollmeldungen, die die Schweregradstufe level oder höher haben, werden von den Handlern, die diesen Logger bedienen, ausgegeben, es sei denn, die Ebene eines Handlers wurde auf eine höhere Schweregradstufe als level gesetzt.

Wenn ein Logger erstellt wird, wird die Ebene auf NOTSET gesetzt (was dazu führt, dass alle Meldungen verarbeitet werden, wenn der Logger der Root-Logger ist, oder die Delegation an den übergeordneten Logger erfolgt, wenn der Logger kein Root-Logger ist). Beachten Sie, dass der Root-Logger mit der Ebene WARNING erstellt wird.

Der Begriff „Delegation an den übergeordneten Logger“ bedeutet, dass, wenn ein Logger die Ebene NOTSET hat, seine Kette von übergeordneten Loggern durchlaufen wird, bis entweder ein übergeordneter Logger mit einer anderen Ebene als NOTSET gefunden wird oder der Root-Logger erreicht ist.

Wenn ein übergeordneter Logger gefunden wird, dessen Ebene von NOTSET abweicht, wird diese Ebene als effektive Ebene des Loggers behandelt, bei dem die Suche nach übergeordneten Loggern begann, und zur Bestimmung der Verarbeitung eines Protokollereignisses verwendet.

Wenn der Root-Logger erreicht wird und seine Ebene NOTSET ist, werden alle Meldungen verarbeitet. Andernfalls wird die Ebene des Root-Loggers als effektive Ebene verwendet.

Siehe Logging Levels für eine Liste der Ebenen.

Geändert in Version 3.2: Der Parameter level akzeptiert jetzt eine String-Darstellung der Ebene, z. B. ‚INFO‘, als Alternative zu den Integer-Konstanten wie INFO. Beachten Sie jedoch, dass Ebenen intern als ganze Zahlen gespeichert werden und Methoden wie z. B. getEffectiveLevel() und isEnabledFor() ganze Zahlen zurückgeben/erwarten.

isEnabledFor(level)

Zeigt an, ob eine Meldung mit dem Schweregrad level von diesem Logger verarbeitet würde. Diese Methode prüft zuerst die auf Modulebene gesetzte Ebene durch logging.disable(level) und dann die effektive Ebene des Loggers, wie durch getEffectiveLevel() bestimmt.

getEffectiveLevel()

Zeigt die effektive Ebene für diesen Logger an. Wenn mit setLevel() ein Wert ungleich NOTSET gesetzt wurde, wird dieser zurückgegeben. Andernfalls wird die Hierarchie in Richtung des Root-Loggers durchlaufen, bis ein Wert ungleich NOTSET gefunden wird, und dieser Wert wird zurückgegeben. Der zurückgegebene Wert ist eine ganze Zahl, typischerweise einer von logging.DEBUG, logging.INFO usw.

getChild(suffix)

Gibt einen Logger zurück, der ein Nachkomme dieses Loggers ist, wie durch den Suffix bestimmt. Somit würde logging.getLogger('abc').getChild('def.ghi') denselben Logger zurückgeben wie logging.getLogger('abc.def.ghi'). Dies ist eine Hilfsmethode, nützlich, wenn der übergeordnete Logger z. B. mit __name__ anstelle einer Literalzeichenkette benannt ist.

Hinzugefügt in Version 3.2.

getChildren()

Gibt eine Menge von Loggern zurück, die unmittelbare Kinder dieses Loggers sind. So könnte z. B. logging.getLogger().getChildren() eine Menge zurückgeben, die die Logger foo und bar enthält, aber ein Logger namens foo.bar wäre nicht in der Menge enthalten. Ebenso könnte logging.getLogger('foo').getChildren() eine Menge zurückgeben, die einen Logger namens foo.bar enthält, aber keinen namens foo.bar.baz.

Hinzugefügt in Version 3.12.

debug(msg, *args, **kwargs)

Protokolliert eine Meldung mit dem Pegel DEBUG in diesem Logger. msg ist die Meldungsformatzeichenkette und args sind die Argumente, die in msg unter Verwendung des String-Formatierungsoperators zusammengeführt werden. (Beachten Sie, dass dies bedeutet, dass Sie Schlüsselwörter in der Formatzeichenkette zusammen mit einem einzelnen Dictionary-Argument verwenden können.) Es wird kein %-Formatierungsoperator auf msg angewendet, wenn keine args angegeben sind.

Es gibt vier Schlüsselwortargumente in kwargs, die untersucht werden: exc_info, stack_info, stacklevel und extra.

Wenn exc_info nicht als falsch ausgewertet wird, werden Ausnahmeinformationen zur Protokollmeldung hinzugefügt. Wenn ein Ausnahme-Tupel (im Format, das von sys.exc_info() zurückgegeben wird) oder eine Ausnahmeinstanz bereitgestellt wird, wird diese verwendet; andernfalls wird sys.exc_info() aufgerufen, um die Ausnahmeinformationen zu erhalten.

Das zweite optionale Schlüsselwortargument ist stack_info, das standardmäßig auf False gesetzt ist. Wenn wahr, werden Stapelinformationen zur Protokollmeldung hinzugefügt, einschließlich des eigentlichen Protokollaufrufs. Beachten Sie, dass dies nicht dieselben Stapelinformationen sind wie die, die durch Angabe von exc_info angezeigt werden: Erstere sind Stapelrahmen vom unteren Ende des Stapels bis zum Protokollaufruf im aktuellen Thread, während letztere Informationen über Stapelrahmen sind, die nach einer Ausnahme beim Suchen nach Ausnahmehandlern entrollt wurden.

Sie können stack_info unabhängig von exc_info angeben, z. B. um nur zu zeigen, wie Sie zu einem bestimmten Punkt in Ihrem Code gelangt sind, auch wenn keine Ausnahmen ausgelöst wurden. Die Stapelrahmen werden nach einer Kopfzeile gedruckt, die besagt

Stack (most recent call last):

Dies imitiert die Traceback (most recent call last):, die beim Anzeigen von Ausnahme-Frames verwendet wird.

Das dritte optionale Schlüsselwortargument ist stacklevel, das standardmäßig auf 1 gesetzt ist. Wenn es größer als 1 ist, werden die entsprechenden Stapelrahmen übersprungen, wenn die Zeilennummer und der Funktionsname im für das Protokollereignis erstellten LogRecord ermittelt werden. Dies kann in Protokollhilfefunktionen verwendet werden, damit die im Ereignisprotokoll aufgezeichneten Informationen nicht die Informationen für die Hilfs-/Wrapper-Funktion/-Methode sind, sondern die des Aufrufers. Der Name dieses Parameters spiegelt den gleichnamigen Parameter im Modul warnings.

Das vierte Schlüsselwortargument ist extra, das verwendet werden kann, um ein Dictionary zu übergeben, das zum Befüllen des __dict__ des für das Protokollereignis erstellten LogRecord mit benutzerdefinierten Attributen verwendet wird. Diese benutzerdefinierten Attribute können dann beliebig verwendet werden. Sie könnten beispielsweise in protokollierte Meldungen integriert werden. Zum Beispiel

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

würde etwas wie das Folgende ausgeben

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

Die Schlüssel im Dictionary, das in extra übergeben wird, sollten nicht mit den vom Logging-System verwendeten Schlüsseln kollidieren. (Siehe den Abschnitt über LogRecord attributes für weitere Informationen darüber, welche Schlüssel vom Logging-System verwendet werden.)

Wenn Sie diese Attribute in protokollierten Meldungen verwenden möchten, müssen Sie vorsichtig sein. Im obigen Beispiel wurde der Formatter mit einer Formatzeichenkette eingerichtet, die ‚clientip‘ und ‚user‘ im Attribut-Dictionary des LogRecord erwartet. Wenn diese fehlen, wird die Meldung nicht protokolliert, da ein String-Formatierungsfehler auftritt. In diesem Fall müssen Sie also immer das extra-Dictionary mit diesen Schlüsseln übergeben.

Obwohl dies ärgerlich sein kann, ist diese Funktion für die Verwendung in spezialisierten Umständen gedacht, wie z. B. Multi-Thread-Servern, bei denen derselbe Code in vielen Kontexten ausgeführt wird und interessante Bedingungen, die auftreten, von diesem Kontext abhängen (wie die IP-Adresse des Remote-Clients und der Name des authentifizierten Benutzers im obigen Beispiel). In solchen Fällen werden wahrscheinlich spezialisierte Formatter mit bestimmten Handlern verwendet.

Wenn kein Handler an diesen Logger angehängt ist (oder an einen seiner Vorfahren, unter Berücksichtigung der relevanten Logger.propagate-Attribute), wird die Meldung an den auf lastResort gesetzten Handler gesendet.

Geändert in Version 3.2: Der Parameter stack_info wurde hinzugefügt.

Geändert in Version 3.5: Der Parameter exc_info kann jetzt Ausnahmeinstanzen akzeptieren.

Geändert in Version 3.8: Der Parameter stacklevel wurde hinzugefügt.

info(msg, *args, **kwargs)

Protokolliert eine Meldung mit dem Pegel INFO in diesem Logger. Die Argumente werden wie für debug() interpretiert.

warning(msg, *args, **kwargs)

Protokolliert eine Meldung mit dem Pegel WARNING in diesem Logger. Die Argumente werden wie für debug() interpretiert.

Hinweis

Es gibt eine veraltete Methode warn, die funktional identisch mit warning ist. Da warn veraltet ist, verwenden Sie sie bitte nicht – verwenden Sie stattdessen warning.

error(msg, *args, **kwargs)

Protokolliert eine Meldung mit dem Pegel ERROR in diesem Logger. Die Argumente werden wie für debug() interpretiert.

critical(msg, *args, **kwargs)

Protokolliert eine Meldung mit dem Pegel CRITICAL in diesem Logger. Die Argumente werden wie für debug() interpretiert.

log(level, msg, *args, **kwargs)

Protokolliert eine Meldung mit dem ganzzahligen Pegel level in diesem Logger. Die anderen Argumente werden wie für debug() interpretiert.

exception(msg, *args, **kwargs)

Protokolliert eine Meldung mit dem Pegel ERROR in diesem Logger. Die Argumente werden wie für debug() interpretiert. Ausnahmeinformationen werden zur Protokollmeldung hinzugefügt. Diese Methode sollte nur von einem Ausnahmebehandler aufgerufen werden.

addFilter(filter)

Fügt den angegebenen Filter filter diesem Logger hinzu.

removeFilter(filter)

Entfernt den angegebenen Filter filter von diesem Logger.

filter(record)

Wendet die Filter dieses Loggers auf den Datensatz an und gibt True zurück, wenn der Datensatz verarbeitet werden soll. Die Filter werden nacheinander konsultiert, bis einer von ihnen einen falschen Wert zurückgibt. Wenn keiner von ihnen einen falschen Wert zurückgibt, wird der Datensatz verarbeitet (an Handler weitergeleitet). Wenn einer einen falschen Wert zurückgibt, erfolgt keine weitere Verarbeitung des Datensatzes.

addHandler(hdlr)

Fügt den angegebenen Handler hdlr diesem Logger hinzu.

removeHandler(hdlr)

Entfernt den angegebenen Handler hdlr von diesem Logger.

findCaller(stack_info=False, stacklevel=1)

Findet den Quellcode-Dateinamen und die Zeilennummer des Aufrufers. Gibt den Dateinamen, die Zeilennummer, den Funktionsnamen und Stapelinformationen als 4-Element-Tupel zurück. Die Stapelinformationen werden als None zurückgegeben, es sei denn, stack_info ist True.

Der Parameter stacklevel wird von Code übergeben, der die APIs debug() und andere APIs aufruft. Wenn er größer als 1 ist, wird der Überschuss verwendet, um Stapelrahmen zu überspringen, bevor die zurückzugebenden Werte ermittelt werden. Dies ist im Allgemeinen nützlich, wenn Logging-APIs aus Hilfs-/Wrapper-Code aufgerufen werden, sodass sich die im Ereignisprotokoll aufgezeichneten Informationen nicht auf den Hilfs-/Wrapper-Code beziehen, sondern auf den Code, der ihn aufruft.

handle(record)

Verarbeitet einen Datensatz, indem er ihn an alle Handler weiterleitet, die diesem Logger und seinen Vorfahren zugeordnet sind (bis ein falscher Wert von propagate gefunden wird). Diese Methode wird für ungepackte Datensätze verwendet, die von einem Socket empfangen werden, sowie für lokal erstellte Datensätze. Die Filterung auf Logger-Ebene erfolgt mithilfe von filter().

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

Dies ist eine Factory-Methode, die in Unterklassen überschrieben werden kann, um spezialisierte LogRecord-Instanzen zu erstellen.

hasHandlers()

Prüft, ob für diesen Logger Handler konfiguriert sind. Dies geschieht durch die Suche nach Handlern in diesem Logger und seinen Eltern in der Logger-Hierarchie. Gibt True zurück, wenn ein Handler gefunden wurde, andernfalls False. Die Methode stoppt die Suche in der Hierarchie, sobald ein Logger mit dem auf False gesetzten Attribut 'propagate' gefunden wird - dies ist der letzte Logger, der auf Handler-Existenz geprüft wird.

Hinzugefügt in Version 3.2.

Geändert in Version 3.7: Logger können jetzt gepickelt und entpickelt werden.

Logging-Level

Die numerischen Werte der Logging-Level sind in der folgenden Tabelle angegeben. Diese sind hauptsächlich von Interesse, wenn Sie Ihre eigenen Level definieren möchten und diese spezifische Werte relativ zu den vordefinierten Leveln haben sollen. Wenn Sie einen Level mit demselben numerischen Wert definieren, überschreibt er den vordefinierten Wert; der vordefinierte Name geht verloren.

Level	Numerischer Wert	Was es bedeutet / Wann man es benutzt
logging.NOTSET	0	Wenn auf einem Logger gesetzt, zeigt dies an, dass Vorfahren-Logger konsultiert werden sollen, um den effektiven Level zu bestimmen. Wenn dies immer noch auf NOTSET aufgelöst wird, werden alle Ereignisse geloggt. Wenn auf einem Handler gesetzt, werden alle Ereignisse behandelt.
logging.DEBUG	10	Detaillierte Informationen, die normalerweise nur für einen Entwickler von Interesse sind, der versucht, ein Problem zu diagnostizieren.
logging.INFO	20	Bestätigung, dass die Dinge wie erwartet funktionieren.
logging.WARNING	30	Ein Hinweis darauf, dass etwas Unerwartetes passiert ist oder dass in naher Zukunft ein Problem auftreten könnte (z.B. „Festplattenspeicher gering“). Die Software funktioniert weiterhin wie erwartet.
logging.ERROR	40	Aufgrund eines schwerwiegenderen Problems konnte die Software eine Funktion nicht ausführen.
logging.CRITICAL	50	Ein schwerwiegender Fehler, der darauf hinweist, dass das Programm selbst möglicherweise nicht mehr weiterlaufen kann.

Handler-Objekte

Handler haben die folgenden Attribute und Methoden. Beachten Sie, dass Handler nie direkt instanziiert wird; diese Klasse dient als Basis für nützlichere Unterklassen. Die Methode __init__() in Unterklassen muss jedoch Handler.__init__() aufrufen.

class logging.Handler

__init__(level=NOTSET)

Initialisiert die Handler-Instanz, indem ihr Level gesetzt, die Liste der Filter auf die leere Liste gesetzt und eine Sperre (mittels createLock()) zur Serialisierung des Zugriffs auf einen I/O-Mechanismus erstellt wird.

createLock()

Initialisiert eine Thread-Sperre, die verwendet werden kann, um den Zugriff auf zugrunde liegende I/O-Funktionalitäten zu serialisieren, die möglicherweise nicht threadsicher sind.

acquire()

Erwirbt die mit createLock() erstellte Thread-Sperre.

release()

Gibt die mit acquire() erworbene Thread-Sperre frei.

setLevel(level)

Setzt die Schwelle für diesen Handler auf level. Logging-Nachrichten, die weniger schwerwiegend sind als level, werden ignoriert. Wenn ein Handler erstellt wird, wird der Level auf NOTSET gesetzt (was bewirkt, dass alle Nachrichten verarbeitet werden).

Siehe Logging Levels für eine Liste der Ebenen.

Geändert in Version 3.2: Der Parameter level akzeptiert jetzt eine Zeichenkettendarstellung des Levels wie z.B. 'INFO' als Alternative zu den ganzzahligen Konstanten wie INFO.

setFormatter(fmt)

Setzt den Formatter für diesen Handler auf fmt. Das Argument fmt muss eine Formatter-Instanz oder None sein.

addFilter(filter)

Fügt den angegebenen Filter filter zu diesem Handler hinzu.

removeFilter(filter)

Entfernt den angegebenen Filter filter von diesem Handler.

filter(record)

Wendet die Filter dieses Handlers auf den Record an und gibt True zurück, wenn der Record verarbeitet werden soll. Die Filter werden nacheinander geprüft, bis einer von ihnen einen falschen Wert zurückgibt. Wenn keiner von ihnen einen falschen Wert zurückgibt, wird der Record ausgegeben. Wenn einer einen falschen Wert zurückgibt, gibt der Handler den Record nicht aus.

flush()

Stellt sicher, dass alle Logging-Ausgaben geleert wurden. Diese Version tut nichts und ist dazu bestimmt, von Unterklassen implementiert zu werden.

close()

Bereinigt alle von dem Handler verwendeten Ressourcen. Diese Version erzeugt keine Ausgabe, entfernt den Handler aber aus einer internen Map von Handlern, die für die Handler-Suche nach Namen verwendet wird.

Unterklassen sollten sicherstellen, dass dies aus überschriebenen close()-Methoden aufgerufen wird.

handle(record)

Gibt den angegebenen Logging-Record bedingt aus, abhängig von Filtern, die dem Handler möglicherweise hinzugefügt wurden. Die tatsächliche Ausgabe des Records wird mit dem Erwerb/Freigeben der I/O-Thread-Sperre umschlossen.

handleError(record)

Diese Methode sollte von Handlern aufgerufen werden, wenn bei einem emit()-Aufruf eine Ausnahme auftritt. Wenn das Modulattribut raiseExceptions auf False gesetzt ist, werden Ausnahmen stillschweigend ignoriert. Dies ist für ein Logging-System meist erwünscht - die meisten Benutzer interessieren sich nicht für Fehler im Logging-System, sondern mehr für Anwendungsfehler. Sie können dies jedoch durch einen benutzerdefinierten Handler ersetzen, wenn Sie möchten. Der angegebene Record ist derjenige, der während des Auftretens der Ausnahme verarbeitet wurde. (Der Standardwert von raiseExceptions ist True, da dies während der Entwicklung nützlicher ist).

format(record)

Formatiert einen Record - wenn ein Formatter gesetzt ist, wird dieser verwendet. Andernfalls wird der Standardformatter des Moduls verwendet.

emit(record)

Führt alles aus, was notwendig ist, um den angegebenen Logging-Record tatsächlich zu loggen. Diese Version ist dazu bestimmt, von Unterklassen implementiert zu werden und löst daher eine NotImplementedError aus.

Warnung

Diese Methode wird aufgerufen, nachdem eine Handler-spezifische Sperre erworben wurde, die nach der Rückgabe dieser Methode wieder freigegeben wird. Wenn Sie diese Methode überschreiben, beachten Sie, dass Sie vorsichtig sein sollten, wenn Sie etwas aufrufen, das andere Teile der Logging-API aufruft, die Sperren verwenden könnten, da dies zu einer Todesschleife führen könnte. Insbesondere

• Logging-Konfigurations-APIs erwerben die Modul-weite Sperre und dann individuelle Handler-spezifische Sperren, während diese Handler konfiguriert werden.

• Viele Logging-APIs sperren die Modul-weite Sperre. Wenn eine solche API aus dieser Methode aufgerufen wird, kann dies zu einer Todesschleife führen, wenn ein Konfigurationsaufruf auf einem anderen Thread erfolgt, da dieser Thread versucht, die Modul-weite Sperre zu erwerben, *bevor* die Handler-spezifische Sperre erworben wird, während dieser Thread versucht, die Modul-weite Sperre zu erwerben, *nachdem* die Handler-spezifische Sperre erworben wurde (da in dieser Methode die Handler-spezifische Sperre bereits erworben wurde).

Eine Liste der standardmäßig enthaltenen Handler finden Sie unter logging.handlers.

Formatter-Objekte

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Verantwortlich für die Umwandlung eines LogRecord in eine Ausgabenzeichenkette, die von einem Menschen oder einem externen System interpretiert werden kann.

Parameter:

• fmt (str) – Eine Formatzeichenkette im angegebenen style für die gesamte geloggte Ausgabe. Die möglichen Schlüssel sind aus den LogRecord-Attributen des Objekts entnommen (LogRecord-Attribute). Wenn nicht angegeben, wird '%(message)s' verwendet, was nur die geloggte Nachricht ist.

• datefmt (str) – Eine Formatzeichenkette für den Datums-/Zeitanteil der geloggten Ausgabe. Wenn nicht angegeben, wird die in formatTime() beschriebene Standardformatierung verwendet.

• style (str) – Kann einer von '%', { oder '$' sein und bestimmt, wie die Formatzeichenkette mit ihren Daten zusammengeführt wird: mittels printf-style String Formatting (%), str.format() ({) oder string.Template ($). Dies gilt nur für fmt (z.B. '%(message)s' im Gegensatz zu '{message}') und nicht für die eigentlichen Log-Nachrichten, die an die Logging-Methoden übergeben werden. Es gibt jedoch andere Möglichkeiten, {- und $-Formatierung für Log-Nachrichten zu verwenden.

• validate (bool) – Wenn True (Standard), lösen ungültige oder nicht übereinstimmende fmt und style einen ValueError aus; z.B. logging.Formatter('%(asctime)s - %(message)s', style='{').

• defaults (dict[str, Any]) – Ein Wörterbuch mit Standardwerten, die für benutzerdefinierte Felder verwendet werden. Zum Beispiel: logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

Geändert in Version 3.2: Der Parameter style wurde hinzugefügt.

Geändert in Version 3.8: Der Parameter validate wurde hinzugefügt.

Geändert in Version 3.10: Der Parameter defaults wurde hinzugefügt.

format(record)

Das Attributwörterbuch des Records wird als Operand für eine String-Formatierungsoperation verwendet. Gibt die resultierende Zeichenkette zurück. Bevor das Wörterbuch formatiert wird, werden einige vorbereitende Schritte durchgeführt. Das Attribut message des Records wird mithilfe von msg % args berechnet. Wenn die Formatierungszeichenkette '(asctime)' enthält, wird formatTime() aufgerufen, um die Zeit des Ereignisses zu formatieren. Wenn Ausnahmeinformationen vorhanden sind, werden diese mit formatException() formatiert und an die Nachricht angehängt. Beachten Sie, dass die formatierten Ausnahmeinformationen im Attribut exc_text zwischengespeichert werden. Dies ist nützlich, da die Ausnahmeinformationen gepickelt und über das Netzwerk gesendet werden können. Sie sollten jedoch vorsichtig sein, wenn Sie mehr als eine Formatter-Unterklasse haben, die die Formatierung von Ausnahmeinformationen anpasst. In diesem Fall müssen Sie den zwischengespeicherten Wert löschen (indem Sie das Attribut exc_text auf None setzen), nachdem ein Formatter seine Formatierung durchgeführt hat, damit der nächste Formatter, der das Ereignis bearbeitet, nicht den zwischengespeicherten Wert verwendet, sondern ihn neu berechnet.

Wenn Stack-Informationen verfügbar sind, werden diese nach den Ausnahmeinformationen angehängt, wobei formatStack() verwendet wird, um sie bei Bedarf zu transformieren.

formatTime(record, datefmt=None)

Diese Methode sollte von format() durch einen Formatter aufgerufen werden, der die formatierte Zeit nutzen möchte. Diese Methode kann in Formattern überschrieben werden, um spezifische Anforderungen zu erfüllen, aber das grundlegende Verhalten ist wie folgt: Wenn datefmt (eine Zeichenkette) angegeben ist, wird sie mit time.strftime() verwendet, um die Erzeugungszeit des Records zu formatieren. Andernfalls wird das Format „%Y-%m-%d %H:%M:%S,uuu“ verwendet, wobei uuu ein Millisekundenwert ist und die anderen Buchstaben gemäß der Dokumentation von time.strftime() sind. Ein Beispiel für eine Zeit in diesem Format ist 2003-01-23 00:29:50,411. Die resultierende Zeichenkette wird zurückgegeben.

Diese Funktion verwendet eine vom Benutzer konfigurierbare Funktion, um die Erzeugungszeit in ein Tupel umzuwandeln. Standardmäßig wird time.localtime() verwendet; um dies für eine bestimmte Formatter-Instanz zu ändern, setzen Sie das Attribut converter auf eine Funktion mit derselben Signatur wie time.localtime() oder time.gmtime(). Um es für alle Formatierer zu ändern, z.B. wenn alle Logging-Zeiten in GMT angezeigt werden sollen, setzen Sie das Attribut converter in der Klasse Formatter.

Geändert in Version 3.3: Zuvor war das Standardformat wie in diesem Beispiel hartkodiert: 2010-09-06 22:38:15,292, wobei der Teil vor dem Komma von einer strptime-Formatzeichenkette ('%Y-%m-%d %H:%M:%S') und der Teil nach dem Komma ein Millisekundenwert behandelt wird. Da strptime keinen Formatplatzhalter für Millisekunden hat, wird der Millisekundenwert mit einer anderen Formatzeichenkette, '%s,%03d', angehängt - und beide dieser Formatzeichenketten waren in dieser Methode hartkodiert. Mit der Änderung werden diese Zeichenketten als klassenweite Attribute definiert, die bei Bedarf auf Instanzebene überschrieben werden können. Die Namen der Attribute sind default_time_format (für die strptime-Formatzeichenkette) und default_msec_format (für das Anhängen des Millisekundenwerts).

Geändert in Version 3.9: default_msec_format kann None sein.

formatException(exc_info)

Formatiert die angegebenen Ausnahmeinformationen (ein standardmäßiges Ausnahme-Tupel wie von sys.exc_info() zurückgegeben) als Zeichenkette. Diese Standardimplementierung verwendet nur traceback.print_exception(). Die resultierende Zeichenkette wird zurückgegeben.

formatStack(stack_info)

Formatiert die angegebenen Stack-Informationen (eine Zeichenkette wie von traceback.print_stack() zurückgegeben, aber mit entferntem letzten Zeilenumbruch) als Zeichenkette. Diese Standardimplementierung gibt einfach den Eingabewert zurück.

class logging.BufferingFormatter(linefmt=None)

Eine Basis-Formatterklasse, die sich zum Ableiten eignet, wenn eine Anzahl von Records formatiert werden soll. Sie können eine Formatter-Instanz übergeben, die Sie zum Formatieren jeder Zeile (die einem einzelnen Record entspricht) verwenden möchten. Wenn nicht angegeben, wird der Standardformatter (der nur die Nachricht des Ereignisses ausgibt) als Zeilenformatter verwendet.

formatHeader(records)

Gibt eine Kopfzeile für eine Liste von records zurück. Die Basisimplementierung gibt einfach die leere Zeichenkette zurück. Sie müssen diese Methode überschreiben, wenn Sie spezifisches Verhalten wünschen, z.B. die Anzahl der Records, einen Titel oder eine Trennlinie anzuzeigen.

formatFooter(records)

Gibt eine Fußzeile für eine Liste von records zurück. Die Basisimplementierung gibt einfach die leere Zeichenkette zurück. Sie müssen diese Methode überschreiben, wenn Sie spezifisches Verhalten wünschen, z.B. die Anzahl der Records oder eine Trennlinie anzuzeigen.

format(records)

Gibt formatierten Text für eine Liste von records zurück. Die Basisimplementierung gibt einfach die leere Zeichenkette zurück, wenn keine Records vorhanden sind; andernfalls gibt sie die Verkettung der Kopfzeile, jedes mit dem Zeilenformatter formatierten Records und der Fußzeile zurück.

Filter-Objekte

Filter (Filter) können von Handler (Handler) und Logger (Logger) für anspruchsvollere Filterungen als die durch Level bereitgestellte verwendet werden. Die Basisklasse Filter erlaubt nur Ereignisse, die sich unterhalb eines bestimmten Punktes in der Logger-Hierarchie befinden. Zum Beispiel erlaubt ein mit 'A.B' initialisierter Filter Ereignisse, die von den Loggern 'A.B', 'A.B.C', 'A.B.C.D', 'A.B.D' usw. protokolliert werden, aber nicht 'A.BB', 'B.A.B' usw. Wenn er mit einem leeren String initialisiert wird, werden alle Ereignisse durchgelassen.

class logging.Filter(name='')

Gibt eine Instanz der Klasse Filter zurück. Wenn name angegeben ist, benennt er einen Logger, der zusammen mit seinen Kindern seine Ereignisse durch den Filter lassen wird. Wenn name der leere String ist, werden alle Ereignisse zugelassen.

filter(record)

Soll der angegebene Datensatz protokolliert werden? Gibt falsch für nein, wahr für ja zurück. Filter können Log-Datensätze entweder direkt modifizieren oder eine komplett andere Datensatzinstanz zurückgeben, die den ursprünglichen Log-Datensatz bei der weiteren Verarbeitung des Ereignisses ersetzt.

Beachten Sie, dass Filter, die an Handler angehängt sind, konsultiert werden, bevor ein Ereignis vom Handler ausgegeben wird, während Filter, die an Logger angehängt sind, konsultiert werden, wann immer ein Ereignis protokolliert wird (mittels debug(), info() usw.), bevor ein Ereignis an die Handler gesendet wird. Das bedeutet, dass Ereignisse, die von absteigenden Loggern generiert wurden, nicht durch die Filter-Einstellung eines Loggers gefiltert werden, es sei denn, der Filter wurde auch auf diese absteigenden Logger angewendet.

Sie müssen Filter nicht tatsächlich unterklassifizieren: Sie können jede Instanz übergeben, die eine filter Methode mit denselben Semantiken hat.

Geändert in Version 3.2: Sie müssen keine spezialisierten Filter-Klassen erstellen oder andere Klassen mit einer filter-Methode verwenden: Sie können eine Funktion (oder einen anderen aufrufbaren) als Filter verwenden. Die Filterlogik prüft, ob das Filterobjekt ein filter Attribut hat: wenn ja, wird angenommen, dass es sich um einen Filter handelt und seine filter()-Methode wird aufgerufen. Andernfalls wird angenommen, dass es sich um ein aufrufbares Objekt handelt und mit dem Datensatz als einzigem Parameter aufgerufen wird. Der Rückgabewert sollte mit dem von filter() übereinstimmen.

Geändert in Version 3.12: Sie können jetzt eine LogRecord-Instanz von Filtern zurückgeben, um den Log-Datensatz zu ersetzen, anstatt ihn direkt zu modifizieren. Dies ermöglicht es Filtern, die an einen Handler angehängt sind, den Log-Datensatz zu ändern, bevor er ausgegeben wird, ohne Nebeneffekte auf andere Handler zu haben.

Obwohl Filter hauptsächlich dazu verwendet werden, Datensätze anhand ausgefeilterer Kriterien als Level zu filtern, sehen sie jeden Datensatz, der vom Handler oder Logger, an den sie angehängt sind, verarbeitet wird: Dies kann nützlich sein, wenn Sie beispielsweise zählen möchten, wie viele Datensätze von einem bestimmten Logger oder Handler verarbeitet wurden, oder Attribute im verarbeiteten LogRecord hinzufügen, ändern oder entfernen möchten. Offensichtlich muss die Änderung des LogRecord mit Vorsicht erfolgen, aber sie ermöglicht die Einspeisung von kontextuellen Informationen in Logs (siehe Filter zur Vermittlung kontextbezogener Informationen verwenden).

LogRecord-Objekte

LogRecord-Instanzen werden automatisch von jedem Logger erstellt, wenn etwas protokolliert wird, und können manuell über makeLogRecord() erstellt werden (z. B. aus einem über das Netzwerk empfangenen picklierten Ereignis).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

Enthält alle Informationen, die für das protokollierte Ereignis relevant sind.

Die primären Informationen werden in msg und args übergeben, die mittels msg % args kombiniert werden, um das message Attribut des Datensatzes zu erstellen.

Parameter:

• name (str) – Der Name des Loggers, der zum Protokollieren des von diesem LogRecord dargestellten Ereignisses verwendet wurde. Beachten Sie, dass der Logger-Name im LogRecord immer diesen Wert haben wird, auch wenn er von einem an einen anderen (übergeordneten) Logger angehängten Handler ausgegeben wird.

• level (int) – Das numerische Level des Logging-Ereignisses (z. B. 10 für DEBUG, 20 für INFO usw.). Beachten Sie, dass dies in *zwei* Attribute des LogRecord konvertiert wird: levelno für den numerischen Wert und levelname für den entsprechenden Levelnamen.

• pathname (str) – Der vollständige Pfad zur Quelldatei, in der der Logging-Aufruf getätigt wurde.

• lineno (int) – Die Zeilennummer in der Quelldatei, in der der Logging-Aufruf getätigt wurde.

• msg (Any) – Die Ereignisbeschreibung, die eine %-Formatzeichenkette mit Platzhaltern für variable Daten oder ein beliebiges Objekt sein kann (siehe Verwendung beliebiger Objekte als Nachrichten).

• args (tuple | dict[str, Any]) – Variable Daten, die in das msg-Argument eingefügt werden, um die Ereignisbeschreibung zu erhalten.

• exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) – Ein Ausnahme-Tupel mit den aktuellen Ausnahmeinformationen, wie von sys.exc_info() zurückgegeben, oder None, wenn keine Ausnahmeinformationen verfügbar sind.

• func (str | None) – Der Name der Funktion oder Methode, von der der Logging-Aufruf aufgerufen wurde.

• sinfo (str | None) – Eine Textzeichenkette, die Stapelinformationen vom unteren Ende des Stapels im aktuellen Thread bis zum Logging-Aufruf darstellt.

getMessage()

Gibt die Nachricht für diese LogRecord-Instanz zurück, nachdem benutzerdefinierte Argumente mit der Nachricht zusammengeführt wurden. Wenn das vom Benutzer bereitgestellte Nachrichtenargument für den Logging-Aufruf keine Zeichenkette ist, wird str() darauf angewendet, um es in eine Zeichenkette zu konvertieren. Dies ermöglicht die Verwendung von benutzerdefinierten Klassen als Nachrichten, deren __str__-Methode die tatsächliche Formatzeichenkette zurückgeben kann, die verwendet werden soll.

Geändert in Version 3.2: Die Erstellung eines LogRecord wurde konfigurierbarer gemacht, indem eine Factory zur Verfügung gestellt wurde, die zur Erstellung des Datensatzes verwendet wird. Die Factory kann über getLogRecordFactory() und setLogRecordFactory() gesetzt werden (siehe dort für die Signatur der Factory).

Diese Funktionalität kann verwendet werden, um eigene Werte zur Erstellungszeit in einen LogRecord einzufügen. Sie können das folgende Muster verwenden

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

Mit diesem Muster könnten mehrere Factories verkettet werden, und solange sie keine Attribute überschreiben oder unbeabsichtigt die oben aufgeführten Standardattribute überschreiben, sollte es keine Überraschungen geben.

LogRecord-Attribute

Der LogRecord hat eine Reihe von Attributen, von denen die meisten aus den Parametern des Konstruktors abgeleitet werden. (Beachten Sie, dass die Namen zwischen den Parametern des LogRecord-Konstruktors und den LogRecord-Attributen nicht immer exakt übereinstimmen.) Diese Attribute können verwendet werden, um Daten aus dem Datensatz in die Formatzeichenkette zu integrieren. Die folgende Tabelle listet (in alphabetischer Reihenfolge) die Attributnamen, ihre Bedeutungen und den entsprechenden Platzhalter in einer %-Stil-Formatzeichenkette auf.

Wenn Sie {}-Formatierung verwenden (str.format()), können Sie {attrname} als Platzhalter in der Formatzeichenkette verwenden. Wenn Sie $-Formatierung verwenden (string.Template), verwenden Sie die Form ${attrname}. In beiden Fällen ersetzen Sie natürlich attrname durch den tatsächlichen Attributnamen, den Sie verwenden möchten.

Bei der {}-Formatierung können Sie Formatierungsflags angeben, indem Sie sie nach dem Attributnamen platzieren, getrennt durch einen Doppelpunkt. Zum Beispiel: Ein Platzhalter von {msecs:03.0f} würde einen Millisekundenwert von 4 als 004 formatieren. Weitere Informationen zu den verfügbaren Optionen finden Sie in der Dokumentation zu str.format().

Attributname	Format	Beschreibung
args	Sie müssen dies nicht selbst formatieren.	Das Tupel von Argumenten, die in msg eingefügt wurden, um message zu erzeugen, oder ein Dictionary, dessen Werte für die Zusammenführung verwendet werden (wenn nur ein Argument vorhanden ist und es sich um ein Dictionary handelt).
asctime	%(asctime)s	Menschenlesbare Zeit, zu der der LogRecord erstellt wurde. Standardmäßig hat dies die Form '2003-07-08 16:49:45,896' (die Zahlen nach dem Komma sind der Millisekundenanteil der Zeit).
created	%(created)f	Zeit, zu der der LogRecord erstellt wurde (wie von time.time_ns() / 1e9 zurückgegeben).
exc_info	Sie müssen dies nicht selbst formatieren.	Ausnahme-Tupel (ähnlich wie bei sys.exc_info) oder, wenn keine Ausnahme aufgetreten ist, None.
filename	%(filename)s	Dateiname von pathname.
funcName	%(funcName)s	Name der Funktion, die den Logging-Aufruf enthält.
levelname	%(levelname)s	Textuelles Logging-Level für die Nachricht ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
levelno	%(levelno)s	Numerisches Logging-Level für die Nachricht (DEBUG, INFO, WARNING, ERROR, CRITICAL).
lineno	%(lineno)d	Quellcode-Zeilennummer, an der der Logging-Aufruf ausgegeben wurde (falls verfügbar).
message	%(message)s	Die protokollierte Nachricht, berechnet als msg % args. Dies wird gesetzt, wenn Formatter.format() aufgerufen wird.
Modul	%(module)s	Modul (Namensbestandteil von filename).
msecs	%(msecs)d	Millisekundenanteil der Zeit, zu der der LogRecord erstellt wurde.
msg	Sie müssen dies nicht selbst formatieren.	Die im ursprünglichen Logging-Aufruf übergebene Formatzeichenkette. Zusammengeführt mit args zur Erzeugung von message, oder ein beliebiges Objekt (siehe Verwendung beliebiger Objekte als Nachrichten).
Name	%(name)s	Name des Loggers, der zum Protokollieren des Aufrufs verwendet wurde.
pathname	%(pathname)s	Vollständiger Pfad zur Quelldatei, in der der Logging-Aufruf ausgegeben wurde (falls verfügbar).
process	%(process)d	Prozess-ID (falls verfügbar).
processName	%(processName)s	Prozessname (falls verfügbar).
relativeCreated	%(relativeCreated)d	Zeit in Millisekunden, zu der der LogRecord erstellt wurde, relativ zur Ladezeit des Logging-Moduls.
stack_info	Sie müssen dies nicht selbst formatieren.	Stapelrahmeninformationen (wo verfügbar) vom unteren Ende des Stapels im aktuellen Thread bis einschließlich des Stapelrahmens des Logging-Aufrufs, der zur Erstellung dieses Datensatzes geführt hat.
thread	%(thread)d	Thread-ID (falls verfügbar).
threadName	%(threadName)s	Thread-Name (falls verfügbar).
taskName	%(taskName)s	Name der asyncio.Task (falls verfügbar).

Geändert in Version 3.1: processName wurde hinzugefügt.

Geändert in Version 3.12: taskName wurde hinzugefügt.

LoggerAdapter-Objekte

LoggerAdapter-Instanzen werden verwendet, um kontextbezogene Informationen bequem in Logging-Aufrufe zu übergeben. Ein Anwendungsbeispiel finden Sie im Abschnitt über das Hinzufügen von kontextbezogenen Informationen zu Ihrer Logging-Ausgabe.

class logging.LoggerAdapter(logger, extra, merge_extra=False)

Gibt eine Instanz von LoggerAdapter zurück, die mit einer zugrunde liegenden Logger-Instanz, einem diktähnlichen Objekt (extra) und einem booleschen Wert (merge_extra) initialisiert ist, der angibt, ob das extra-Argument einzelner Log-Aufrufe mit dem LoggerAdapter-Extra zusammengeführt werden soll oder nicht. Das Standardverhalten ist, das extra-Argument einzelner Log-Aufrufe zu ignorieren und nur das der LoggerAdapter-Instanz zu verwenden.

process(msg, kwargs)

Modifiziert die Nachricht und/oder die Schlüsselwortargumente, die an einen Logging-Aufruf übergeben werden, um kontextbezogene Informationen einzufügen. Diese Implementierung nimmt das Objekt, das als extra an den Konstruktor übergeben wird, und fügt es mit dem Schlüssel 'extra' zu kwargs hinzu. Der Rückgabewert ist ein (msg, kwargs)-Tupel, das die (möglicherweise modifizierten) Versionen der übergebenen Argumente enthält.

manager

Delegiert an den zugrunde liegenden manager von logger.

_log

Delegiert an die zugrunde liegende Methode _log() von logger.

Zusätzlich zu den oben genannten unterstützt LoggerAdapter die folgenden Methoden von Logger: debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel() und hasHandlers(). Diese Methoden haben dieselben Signaturen wie ihre Gegenstücke in Logger, sodass Sie die beiden Instanztypen austauschbar verwenden können.

Geändert in Version 3.2: Die Methoden isEnabledFor(), getEffectiveLevel(), setLevel() und hasHandlers() wurden zu LoggerAdapter hinzugefügt. Diese Methoden delegieren an den zugrunde liegenden Logger.

Geändert in Version 3.6: Das Attribut manager und die Methode _log() wurden hinzugefügt, die an den zugrunde liegenden Logger delegieren und es ermöglichen, Adapter zu verschachteln.

Geändert in Version 3.13: Das Argument merge_extra wurde hinzugefügt.

Threadsicherheit

Das Logging-Modul soll threadsicher sein, ohne dass seine Clients spezielle Arbeiten leisten müssen. Dies wird durch die Verwendung von Threading-Locks erreicht; es gibt ein Lock, um den Zugriff auf die gemeinsamen Daten des Moduls zu serialisieren, und jeder Handler erstellt ebenfalls ein Lock, um den Zugriff auf seine zugrunde liegende I/O zu serialisieren.

Wenn Sie asynchrone Signalhandler mit dem signal-Modul implementieren, können Sie möglicherweise nicht aus solchen Signalhandlern heraus protokollieren. Dies liegt daran, dass Implementierungen von Locks im threading-Modul nicht immer wiederaufrufbar sind und daher nicht aus solchen Signalhandlern aufgerufen werden können.

Modul-Level-Funktionen

Zusätzlich zu den oben beschriebenen Klassen gibt es eine Reihe von Modul-Level-Funktionen.

logging.getLogger(name=None)

Gibt einen Logger mit dem angegebenen Namen zurück oder, wenn name None ist, den Root-Logger der Hierarchie zurück. Wenn angegeben, ist der Name typischerweise ein Punkt-getrennter hierarchischer Name wie ‘a’, ‘a.b’ oder ‘a.b.c.d’. Die Wahl dieser Namen liegt vollständig beim Entwickler, der Logging verwendet, obwohl empfohlen wird, __name__ zu verwenden, es sei denn, Sie haben einen besonderen Grund, dies nicht zu tun, wie in Logger-Objekte erwähnt.

Alle Aufrufe dieser Funktion mit einem bestimmten Namen geben dieselbe Logger-Instanz zurück. Das bedeutet, dass Logger-Instanzen nicht zwischen verschiedenen Teilen einer Anwendung übergeben werden müssen.

logging.getLoggerClass()

Gibt entweder die Standardklasse Logger zurück, oder die letzte Klasse, die an setLoggerClass() übergeben wurde. Diese Funktion kann innerhalb einer neuen Klassendefinition aufgerufen werden, um sicherzustellen, dass die Installation einer benutzerdefinierten Logger-Klasse bereits von anderem Code angewendete Anpassungen nicht rückgängig macht. Zum Beispiel

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()

Gibt eine aufrufbare Funktion zurück, die zum Erstellen eines LogRecord verwendet wird.

Hinzugefügt in Version 3.2: Diese Funktion wird zusammen mit setLogRecordFactory() bereitgestellt, um Entwicklern mehr Kontrolle darüber zu geben, wie der LogRecord, der ein Logging-Ereignis darstellt, konstruiert wird.

Weitere Informationen zur Aufrufweise der Factory finden Sie unter setLogRecordFactory().

logging.debug(msg, *args, **kwargs)

Dies ist eine praktische Funktion, die Logger.debug() für den Root-Logger aufruft. Die Handhabung der Argumente ist in jeder Hinsicht identisch mit der in dieser Methode beschriebenen.

Der einzige Unterschied besteht darin, dass, wenn der Root-Logger keine Handler hat, basicConfig() aufgerufen wird, bevor debug auf dem Root-Logger aufgerufen wird.

Für sehr kurze Skripte oder schnelle Demonstrationen von logging-Einrichtungen können debug und die anderen Funktionen auf Modulebene praktisch sein. Die meisten Programme möchten jedoch die Logging-Konfiguration sorgfältig und explizit steuern und sollten daher die Erstellung eines Loggers auf Modulebene und den Aufruf von Logger.debug() (oder anderen level-spezifischen Methoden) darauf bevorzugen, wie zu Beginn dieser Dokumentation beschrieben.

logging.info(msg, *args, **kwargs)

Protokolliert eine Nachricht mit dem Level INFO im Root-Logger. Die Argumente und das Verhalten sind ansonsten identisch mit denen von debug().

logging.warning(msg, *args, **kwargs)

Protokolliert eine Nachricht mit dem Level WARNING im Root-Logger. Die Argumente und das Verhalten sind ansonsten identisch mit denen von debug().

Hinweis

Es gibt eine veraltete Funktion warn, die funktional identisch mit warning ist. Da warn veraltet ist, bitte nicht verwenden – stattdessen warning verwenden.

logging.error(msg, *args, **kwargs)

Protokolliert eine Nachricht mit dem Level ERROR im Root-Logger. Die Argumente und das Verhalten sind ansonsten identisch mit denen von debug().

logging.critical(msg, *args, **kwargs)

Protokolliert eine Nachricht mit dem Level CRITICAL im Root-Logger. Die Argumente und das Verhalten sind ansonsten identisch mit denen von debug().

logging.exception(msg, *args, **kwargs)

Protokolliert eine Nachricht mit dem Level ERROR im Root-Logger. Die Argumente und das Verhalten sind ansonsten identisch mit denen von debug(). Ausnahmeinformationen werden zur Logging-Nachricht hinzugefügt. Diese Funktion sollte nur aus einem Ausnahmebehandler aufgerufen werden.

logging.log(level, msg, *args, **kwargs)

Protokolliert eine Nachricht mit dem Level level im Root-Logger. Die Argumente und das Verhalten sind ansonsten identisch mit denen von debug().

logging.disable(level=CRITICAL)

Bietet ein übergeordnetes Level level für alle Logger, das Vorrang vor dem Level des Loggers selbst hat. Wenn die Notwendigkeit besteht, die Logging-Ausgabe in der gesamten Anwendung vorübergehend zu drosseln, kann diese Funktion nützlich sein. Sie hat die Auswirkung, alle Logging-Aufrufe der Schweregradstufe level und darunter zu deaktivieren. Wenn Sie sie also mit dem Wert INFO aufrufen, werden alle INFO- und DEBUG-Ereignisse verworfen, während solche der Schweregradstufe WARNING und höher entsprechend dem effektiven Level des Loggers verarbeitet werden. Wenn logging.disable(logging.NOTSET) aufgerufen wird, wird dieses übergeordnete Level effektiv entfernt, so dass die Logging-Ausgabe wieder von den effektiven Leveln einzelner Logger abhängt.

Beachten Sie, dass, wenn Sie benutzerdefinierte Logging-Level höher als CRITICAL (dies wird nicht empfohlen) definiert haben, Sie sich nicht auf den Standardwert für den Parameter level verlassen können, sondern explizit einen geeigneten Wert angeben müssen.

Geändert in Version 3.7: Der Parameter level wurde standardmäßig auf das Level CRITICAL gesetzt. Weitere Informationen zu dieser Änderung finden Sie unter bpo-28524.

logging.addLevelName(level, levelName)

Ordnet dem Level level den Text levelName in einem internen Wörterbuch zu, das verwendet wird, um numerische Level einer textuellen Darstellung zuzuordnen, zum Beispiel wenn ein Formatter eine Nachricht formatiert. Diese Funktion kann auch verwendet werden, um eigene Level zu definieren. Die einzigen Einschränkungen sind, dass alle verwendeten Level über diese Funktion registriert werden müssen, Level positive ganze Zahlen sein müssen und sie in aufsteigender Reihenfolge der Schweregrade ansteigen sollten.

Hinweis

Wenn Sie darüber nachdenken, eigene Level zu definieren, lesen Sie bitte den Abschnitt über Benutzerdefinierte Level.

logging.getLevelNamesMapping()

Gibt eine Zuordnung von Level-Namen zu ihren entsprechenden Logging-Leveln zurück. Zum Beispiel wird die Zeichenkette „CRITICAL“ zu CRITICAL zugeordnet. Die zurückgegebene Zuordnung wird bei jedem Aufruf dieser Funktion aus einer internen Zuordnung kopiert.

Hinzugefügt in Version 3.11.

logging.getLevelName(level)

Gibt die textuelle oder numerische Darstellung des Logging-Levels level zurück.

Wenn level eines der vordefinierten Level CRITICAL, ERROR, WARNING, INFO oder DEBUG ist, erhalten Sie die entsprechende Zeichenkette. Wenn Sie Level mit Namen über addLevelName() zugeordnet haben, wird der Ihnen zugeordnete Name zurückgegeben. Wenn ein numerischer Wert übergeben wird, der einem der definierten Level entspricht, wird die entsprechende Zeichenkettenrepräsentation zurückgegeben.

Der Parameter level akzeptiert auch eine Zeichenkettenrepräsentation des Levels, z. B. „INFO“. In solchen Fällen gibt diese Funktion den entsprechenden numerischen Wert des Levels zurück.

Wenn kein passender numerischer oder zeichenkettenbasierter Wert übergeben wird, wird die Zeichenkette „Level %s“ % level zurückgegeben.

Hinweis

Level sind intern ganze Zahlen (da sie in der Logging-Logik verglichen werden müssen). Diese Funktion wird verwendet, um zwischen einem Integer-Level und dem im formatierten Log-Output angezeigten Level-Namen mithilfe des Format-Specifiers %(levelname)s (siehe LogRecord-Attribute) zu konvertieren und umgekehrt.

Geändert in Version 3.4: In Python-Versionen vor 3.4 konnte dieser Funktion auch ein Text-Level übergeben werden, und sie gab den entsprechenden numerischen Wert des Levels zurück. Dieses undokumentierte Verhalten wurde als Fehler betrachtet und in Python 3.4 entfernt, aber in 3.4.2 aufgrund der Beibehaltung der Abwärtskompatibilität wiederhergestellt.

logging.getHandlerByName(name)

Gibt einen Handler mit dem angegebenen name zurück oder None, wenn kein Handler mit diesem Namen existiert.

Hinzugefügt in Version 3.12.

logging.getHandlerNames()

Gibt ein unveränderliches Set aller bekannten Handler-Namen zurück.

Hinzugefügt in Version 3.12.

logging.makeLogRecord(attrdict)

Erstellt und gibt eine neue LogRecord-Instanz zurück, deren Attribute durch attrdict definiert sind. Diese Funktion ist nützlich, um ein serialisiertes LogRecord-Attribut-Dictionary, das über eine Socket gesendet wurde, auf der Empfängerseite als LogRecord-Instanz wiederherzustellen.

logging.basicConfig(**kwargs)

Führt eine grundlegende Konfiguration für das Logging-System durch, indem ein StreamHandler mit einem Standard-Formatter erstellt und zu dem Root-Logger hinzugefügt wird. Die Funktionen debug(), info(), warning(), error() und critical() rufen basicConfig() automatisch auf, wenn keine Handler für den Root-Logger definiert sind.

Diese Funktion tut nichts, wenn der Root-Logger bereits konfigurierte Handler hat, es sei denn, das Schlüsselwortargument force ist auf True gesetzt.

Hinweis

Diese Funktion sollte im Hauptthread aufgerufen werden, bevor andere Threads gestartet werden. In Python-Versionen vor 2.7.1 und 3.2 kann es (in seltenen Fällen) vorkommen, dass ein Handler mehr als einmal zum Root-Logger hinzugefügt wird, wenn diese Funktion aus mehreren Threads aufgerufen wird, was zu unerwarteten Ergebnissen wie doppelten Nachrichten im Log führen kann.

Die folgenden Schlüsselwortargumente werden unterstützt.

Format	Beschreibung
filename	Gibt an, dass ein FileHandler mit dem angegebenen Dateinamen anstelle eines StreamHandler erstellt werden soll.
filemode	Wenn filename angegeben ist, wird die Datei in diesem Modus geöffnet. Standardmäßig ist dies 'a'.
format	Verwendet die angegebene Formatzeichenkette für den Handler. Standardmäßig werden die Attribute levelname, name und message durch Doppelpunkte getrennt.
datefmt	Verwendet das angegebene Datums-/Zeitformat, wie es von time.strftime() akzeptiert wird.
style	Wenn format angegeben ist, wird dieser Stil für die Formatzeichenkette verwendet. Einer von '%', '{' oder '$' für printf-Stil, str.format() oder string.Template entsprechend. Standardmäßig ist dies '%'.
level	Setzt den Level des Root-Loggers auf den angegebenen Level.
stream	Verwendet den angegebenen Stream zur Initialisierung des StreamHandler. Beachten Sie, dass dieses Argument mit filename inkompatibel ist – wenn beide vorhanden sind, wird ein ValueError ausgelöst.
handlers	Wenn angegeben, sollte dies ein Iterable von bereits erstellten Handlern sein, die dem Root-Logger hinzugefügt werden sollen. Handler, denen noch kein Formatter zugewiesen wurde, erhalten den Standard-Formatter, der in dieser Funktion erstellt wird. Beachten Sie, dass dieses Argument mit filename oder stream inkompatibel ist – wenn beide vorhanden sind, wird ein ValueError ausgelöst.
force	Wenn dieses Schlüsselwortargument auf wahr gesetzt ist, werden alle vorhandenen Handler, die an den Root-Logger angehängt sind, entfernt und geschlossen, bevor die Konfiguration gemäß den anderen Argumenten durchgeführt wird.
encoding	Wenn dieses Schlüsselwortargument zusammen mit filename angegeben wird, wird sein Wert beim Erstellen des FileHandler verwendet und somit beim Öffnen der Ausgabedatei.
errors	Wenn dieses Schlüsselwortargument zusammen mit filename angegeben wird, wird sein Wert beim Erstellen des FileHandler verwendet und somit beim Öffnen der Ausgabedatei. Wenn es nicht angegeben ist, wird der Wert ‚backslashreplace‘ verwendet. Beachten Sie, dass, wenn None angegeben wird, es als solches an open() übergeben wird, was bedeutet, dass es wie die Übergabe von ‚errors‘ behandelt wird.

Geändert in Version 3.2: Das Argument style wurde hinzugefügt.

Geändert in Version 3.3: Das Argument handlers wurde hinzugefügt. Zusätzliche Prüfungen wurden vorgenommen, um Situationen zu erkennen, in denen inkompatible Argumente angegeben werden (z. B. handlers zusammen mit stream oder filename, oder stream zusammen mit filename).

Geändert in Version 3.8: Das Argument force wurde hinzugefügt.

Geändert in Version 3.9: Die Argumente encoding und errors wurden hinzugefügt.

logging.shutdown()

Informiert das Logging-System, eine ordnungsgemäße Herunterfahren durchzuführen, indem alle Handler geleert und geschlossen werden. Dies sollte beim Beenden der Anwendung aufgerufen werden, und nach diesem Aufruf sollte das Logging-System nicht mehr verwendet werden.

Wenn das Logging-Modul importiert wird, registriert es diese Funktion als Exit-Handler (siehe atexit), so dass dies normalerweise nicht manuell erfolgen muss.

logging.setLoggerClass(klass)

Weist das Logging-System an, die Klasse klass beim Instanziieren eines Loggers zu verwenden. Die Klasse sollte __init__() so definieren, dass nur ein Namensargument erforderlich ist, und __init__() sollte Logger.__init__() aufrufen. Diese Funktion wird typischerweise vor dem Instanziieren von Loggern aufgerufen, die benutzerdefinierte Logger-Verhalten verwenden müssen. Nach diesem Aufruf, wie auch zu jeder anderen Zeit, instanziieren Sie Logger nicht direkt über die Unterklasse: Verwenden Sie weiterhin die API logging.getLogger(), um Ihre Logger zu erhalten.

logging.setLogRecordFactory(factory)

Legt eine aufrufbare Funktion fest, die zum Erstellen eines LogRecord verwendet wird.

Parameter:

factory – Die aufrufbare Factory, die zur Instanziierung eines Log-Records verwendet werden soll.

Hinzugefügt in Version 3.2: Diese Funktion wird zusammen mit getLogRecordFactory() bereitgestellt, um Entwicklern mehr Kontrolle darüber zu geben, wie der LogRecord, der ein Logging-Ereignis darstellt, konstruiert wird.

Die Factory hat die folgende Signatur

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

name:

Der Name des Loggers.

level:

Das Logging-Level (numerisch).

fn:

Der vollständige Pfad zur Datei, in der der Logging-Aufruf erfolgte.

lno:

Die Zeilennummer in der Datei, in der der Logging-Aufruf erfolgte.

msg:

Die Logging-Nachricht.

args:

Die Argumente für die Logging-Nachricht.

exc_info:

Ein Ausnahme-Tupel oder None.

func:

Der Name der Funktion oder Methode, die den Logging-Aufruf aufgerufen hat.

sinfo:

Ein Stack-Traceback, wie er von traceback.print_stack() bereitgestellt wird und die Aufrufhierarchie anzeigt.

kwargs:

Zusätzliche Schlüsselwortargumente.

Modulebene Attribute

logging.lastResort

Ein „Handler letzter Instanz“ ist über dieses Attribut verfügbar. Dies ist ein StreamHandler, der nach sys.stderr mit einem Level von WARNING schreibt und zur Behandlung von Logging-Ereignissen verwendet wird, wenn keine Logging-Konfiguration vorhanden ist. Das Endergebnis ist, dass die Nachricht einfach nach sys.stderr ausgegeben wird. Dies ersetzt die frühere Fehlermeldung „no handlers could be found for logger XYZ“. Wenn Sie das frühere Verhalten aus irgendeinem Grund benötigen, kann lastResort auf None gesetzt werden.

Hinzugefügt in Version 3.2.

logging.raiseExceptions

Wird verwendet, um zu prüfen, ob Ausnahmen während der Verarbeitung weitergegeben werden sollen.

Standard: True.

Wenn raiseExceptions False ist, werden Ausnahmen stillschweigend ignoriert. Das ist es, was für ein Logging-System meistens gewünscht wird – die meisten Benutzer interessieren sich nicht für Fehler im Logging-System, sondern für Anwendungsfehler.

Integration mit dem warnings-Modul

Die Funktion captureWarnings() kann verwendet werden, um logging mit dem warnings-Modul zu integrieren.

logging.captureWarnings(capture)

Diese Funktion wird verwendet, um die Erfassung von Warnungen durch Logging ein- und auszuschalten.

Wenn capture True ist, werden Warnungen, die vom warnings-Modul ausgegeben, an das Logging-System umgeleitet. Insbesondere wird eine Warnung mithilfe von warnings.formatwarning() formatiert und die resultierende Zeichenkette an einen Logger namens 'py.warnings' mit der Schweregradstufe WARNING protokolliert.

Wenn capture False ist, stoppt die Umleitung von Warnungen an das Logging-System, und Warnungen werden an ihre ursprünglichen Ziele umgeleitet (d. h. diejenigen, die vor dem Aufruf von captureWarnings(True) aktiv waren).

Siehe auch

Modul logging.config

Konfigurations-API für das Logging-Modul.

Modul logging.handlers

Nützliche Handler, die im Logging-Modul enthalten sind.

PEP 282 - Ein Logging-System

Der Vorschlag, der dieses Feature für die Aufnahme in die Python-Standardbibliothek beschrieb.

Ursprüngliches Python Logging Package

Dies ist die Originalquelle für das logging-Paket. Die von dieser Website verfügbare Version des Pakets ist für die Verwendung mit Python 1.5.2, 2.1.x und 2.2.x geeignet, die das logging-Paket nicht in der Standardbibliothek enthalten.