logging.handlers — Loggningshanterare

Källkod: Lib/logging/handlers.py

Important

Denna sida innehåller endast referensinformation. För handledning, se

• Grundläggande handledning

• Avancerad handledning

• Loggningskokbok

---

Följande användbara hanterare finns i paketet. Observera att tre av hanterarna (StreamHandler, FileHandler och NullHandler) egentligen är definierade i själva modulen logging, men har dokumenterats här tillsammans med de andra hanterarna.

StreamHandler

Klassen StreamHandler, som finns i kärnpaketet logging, skickar loggningsutdata till strömmar som sys.stdout, sys.stderr eller något filliknande objekt (eller, mer exakt, något objekt som stöder metoderna write() och flush()).

class logging.StreamHandler(stream=None)

Returnerar en ny instans av StreamHandler-klassen. Om stream anges kommer instansen att använda den för loggning av utdata, annars kommer sys.stderr att användas.

emit(record)

Om en formaterare anges används den för att formatera posten. Posten skrivs sedan till flödet följt av terminator. Om det finns information om undantag formateras den med traceback.print_exception() och läggs till i strömmen.

flush()

Spolar strömmen genom att anropa dess flush()-metod. Observera att metoden close() ärvs från Handler och därför inte ger någon utdata, så ett explicit anrop av flush() kan ibland behövas.

setStream(stream)

Ställer in instansens stream till det angivna värdet, om det är annorlunda. Den gamla strömmen spolas innan den nya strömmen sätts.

Parametrar:

stream – Den ström som hanteraren ska använda.

Returer:

den gamla strömmen, om strömmen ändrades, eller None om den inte ändrades.

Tillagd i version 3.7.

terminator

Sträng som används som terminator när en formaterad post skrivs till en ström. Standardvärdet är '\n'.

Om du inte vill ha en newline-avslutning kan du ställa in hanterarinstansens attribut terminator till den tomma strängen.

I tidigare versioner var terminatorn hårdkodad som '\n'.

Tillagd i version 3.2.

FileHandler

Klassen FileHandler, som finns i kärnpaketet logging, skickar loggningsutdata till en diskfil. Den ärver utdatafunktionaliteten från StreamHandler.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returnerar en ny instans av FileHandler-klassen. Den angivna filen öppnas och används som ström för loggning. Om mode inte specificeras används 'a'. Om encoding inte är None, används den för att öppna filen med den kodningen. Om delay är true, skjuts filöppningen upp till det första anropet till emit(). Som standard växer filen på obestämd tid. Om errors anges används det för att bestämma hur kodningsfel ska hanteras.

Ändrad i version 3.6: Förutom strängvärden accepteras även Path-objekt för argumentet filnamn.

Ändrad i version 3.9: Parametern errors har lagts till.

close()

Stänger filen.

emit(record)

Skickar ut posten till filen.

Observera att om filen stängdes på grund av loggning vid avslutning och filläget är ’w’, kommer posten inte att skickas ut (se bpo-42378).

NullHandler

Tillagd i version 3.1.

Klassen NullHandler, som finns i kärnpaketet logging, gör ingen formatering eller utmatning. Det är i huvudsak en ”no-op”-hanterare som kan användas av biblioteksutvecklare.

class logging.NullHandler

Returnerar en ny instans av NullHandler-klassen.

emit(record)

Den här metoden gör ingenting.

handle(record)

Den här metoden gör ingenting.

createLock()

Denna metod returnerar None för låset, eftersom det inte finns någon underliggande I/O som åtkomst behöver serialiseras till.

Se Konfigurera loggning för ett bibliotek för mer information om hur du använder NullHandler.

WatchedFileHandler

Klassen WatchedFileHandler, som finns i modulen logging.handlers, är en FileHandler som övervakar filen den loggar till. Om filen ändras stängs den och öppnas igen med hjälp av filnamnet.

En filändring kan ske på grund av användning av program som newsyslog och logrotate som utför loggfilsrotation. Denna hanterare, som är avsedd att användas under Unix/Linux, övervakar filen för att se om den har ändrats sedan den senaste emitten. (En fil anses ha ändrats om dess enhet eller inode har ändrats.) Om filen har ändrats stängs det gamla filflödet och filen öppnas för att få ett nytt flöde.

Denna hanterare är inte lämplig att använda under Windows, eftersom öppna loggfiler inte kan flyttas eller döpas om under Windows - loggning öppnar filerna med exklusiva lås - och det finns därför inget behov av en sådan hanterare. Dessutom stöds inte ST_INO under Windows; stat() returnerar alltid noll för detta värde.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returnerar en ny instans av WatchedFileHandler-klassen. Den angivna filen öppnas och används som ström för loggning. Om mode inte specificeras används 'a'. Om encoding inte är None, används den för att öppna filen med den kodningen. Om delay är true, skjuts filöppningen upp till det första anropet till emit(). Som standard växer filen på obestämd tid. Om errors anges, avgör det hur kodningsfel ska hanteras.

Ändrad i version 3.6: Förutom strängvärden accepteras även Path-objekt för argumentet filnamn.

Ändrad i version 3.9: Parametern errors har lagts till.

reopenIfNeeded()

Kontrollerar om filen har ändrats. Om så är fallet spolas och stängs den befintliga strömmen och filen öppnas igen, vanligtvis som en föregångare till utmatningen av posten till filen.

Tillagd i version 3.6.

emit(record)

Skickar ut posten till filen, men anropar först reopenIfNeeded() för att öppna filen igen om den har ändrats.

BaseRotatingHandler

Klassen BaseRotatingHandler, som finns i modulen logging.handlers, är basklassen för de roterande filhanterarna RotatingFileHandler och TimedRotatingFileHandler. Du ska inte behöva instansiera den här klassen, men den har attribut och metoder som du kan behöva åsidosätta.

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

Parametrarna är desamma som för FileHandler. Attributen är:

namer

Om detta attribut är inställt på en anropsbarhet, delegeras metoden rotation_filename() till denna anropsbarhet. De parametrar som skickas till anropsbarheten är de som skickas till rotation_filename().

Anteckning

Namer-funktionen anropas ganska många gånger under rollover, så den bör vara så enkel och snabb som möjligt. Den bör också returnera samma utdata varje gång för en given indata, annars kanske rollover-beteendet inte fungerar som förväntat.

Det är också värt att notera att man bör vara försiktig när man använder en namngivare för att bevara vissa attribut i filnamnet som används under rotationen. Till exempel förväntar sig RotatingFileHandler att ha en uppsättning loggfiler vars namn innehåller successiva heltal, så att rotationen fungerar som förväntat, och TimedRotatingFileHandler raderar gamla loggfiler (baserat på parametern backupCount som skickas till hanterarens initierare) genom att bestämma de äldsta filerna som ska raderas. För att detta ska kunna ske måste filnamnen kunna sorteras med hjälp av datum/tid-delen av filnamnet, och en namnkod måste respektera detta. (Om man vill ha en namngivare som inte följer detta schema måste den användas i en underklass till TimedRotatingFileHandler som åsidosätter metoden getFilesToDelete() för att passa in i det anpassade namngivningsschemat)

Tillagd i version 3.3.

rotator

Om detta attribut anges för en anropsbarhet, delegeras metoden rotate() till denna anropsbarhet. De parametrar som skickas till anropsbarheten är de som skickas till rotate().

Tillagd i version 3.3.

rotation_filename(default_name)

Ändra filnamnet på en loggfil när den roteras.

Detta är till för att ett anpassat filnamn ska kunna anges.

Standardimplementeringen anropar attributet ’namer’ i hanteraren, om det är anropsbart, och skickar standardnamnet till det. Om attributet inte är anropbart (standardvärdet är None) returneras namnet oförändrat.

Parametrar:

default_name – Standardnamnet för loggfilen.

Tillagd i version 3.3.

rotate(source, dest)

När du roterar, rotera den aktuella loggen.

Standardimplementeringen anropar attributet ’rotator’ i hanteraren, om det är anropsbart, och skickar argumenten source och dest till det. Om attributet inte är anropsbart (standard är None), byts källan helt enkelt namn till destinationen.

Parametrar:

• source – Källans filnamn. Detta är normalt basfilnamnet, t.ex. ”test.log”.

• dest – Filnamnet för destinationsfilen. Detta är normalt det som källan roteras till, t.ex. ”test.log.1”.

Tillagd i version 3.3.

Anledningen till att attributen finns är för att du ska slippa subklassa - du kan använda samma anropbara filer för instanser av RotatingFileHandler och TimedRotatingFileHandler. Om antingen namer- eller rotator-kallelsen ger upphov till ett undantag, kommer detta att hanteras på samma sätt som alla andra undantag under ett emit()-anrop, dvs. via handleError()-metoden i hanteraren.

Om du behöver göra mer betydande ändringar i rotationsbehandlingen kan du åsidosätta metoderna.

För ett exempel, se Använda en rotator och en namer för att anpassa bearbetningen av loggrotation.

RotatingFileHandler

Klassen RotatingFileHandler, som finns i modulen logging.handlers, stöder rotation av diskloggfiler.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

Returnerar en ny instans av RotatingFileHandler-klassen. Den angivna filen öppnas och används som ström för loggning. Om mode inte specificeras används 'a'. Om encoding inte är None, används den för att öppna filen med den kodningen. Om delay är true, skjuts filöppningen upp till det första anropet till emit(). Som standard växer filen på obestämd tid. Om errors anges, avgör det hur kodningsfel ska hanteras.

Du kan använda värdena maxBytes och backupCount för att låta filen rollover ha en förutbestämd storlek. När storleken är på väg att överskridas stängs filen och en ny fil öppnas tyst för utdata. Rollover inträffar när den aktuella loggfilen är nästan maxBytes lång; men om antingen maxBytes eller backupCount är noll inträffar aldrig rollover, så du vill i allmänhet sätta backupCount till minst 1 och ha en maxBytes som inte är noll. När backupCount inte är noll kommer systemet att spara gamla loggfiler genom att lägga till tillägget ’.1’, ’.2’ etc. till filnamnet. Om du till exempel har backupCount på 5 och ett basfilnamn på app.log, får du app.log, app.log.1, app.log.2, upp till app.log.5. Den fil som skrivs till är alltid app.log. När den här filen är fylld stängs den och byter namn till app.log.1, och om filerna app.log.1, app.log.2, etc. finns, byter de namn till app.log.2, app.log.3 etc.

Ändrad i version 3.6: Förutom strängvärden accepteras även Path-objekt för argumentet filnamn.

Ändrad i version 3.9: Parametern errors har lagts till.

doRollover()

Gör en vältning, enligt beskrivningen ovan.

emit(record)

Skickar ut posten till filen och tar hand om rollover enligt tidigare beskrivning.

shouldRollover(record)

Se om den medföljande posten skulle leda till att filen överskrider den konfigurerade storleksgränsen.

TimedRotatingFileHandler

Klassen TimedRotatingFileHandler, som finns i modulen logging.handlers, stöder rotation av diskloggfiler med vissa tidsbestämda intervall.

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

Returnerar en ny instans av klassen TimedRotatingFileHandler. Den angivna filen öppnas och används som ström för loggning. Vid rotation sätts även filnamnsuffixet. Rotationen sker baserat på produkten av when och interval.

Du kan använda when för att ange typen av interval. Listan över möjliga värden finns nedan. Observera att de inte är skiftlägeskänsliga.

Värde	Typ av intervall	Om/hur atTime används
'S'	Sekunder	Ignorerad
'M'	Minuter	Ignorerad
'H'	Timmar	Ignorerad
'D'	Dagar	Ignorerad
'W0'-'W6'	Veckodag (0=Måndag)	Används för att beräkna initial rollover-tid
'midnight'	Rullar över vid midnatt, om atTime inte anges, annars vid tidpunkt atTime	Används för att beräkna initial rollover-tid

När du använder veckodagsbaserad rotation anger du ”W0” för måndag, ”W1” för tisdag och så vidare upp till ”W6” för söndag. I det här fallet används inte värdet som anges för interval.

Systemet sparar gamla loggfiler genom att lägga till tillägg till filnamnet. Tilläggen är datum- och tidsbaserade och använder strftime-formatet %Y-%m-%d_%H-%M-%S eller en inledande del av detta, beroende på rollover-intervallet.

När nästa rollover-tid beräknas för första gången (när hanteraren skapas), används den senaste modifieringstiden för en befintlig loggfil, eller den aktuella tiden, för att beräkna när nästa rotation kommer att ske.

Om argumentet utc är sant används tider i UTC, annars används lokal tid.

Om backupCount inte är noll sparas högst backupCount filer, och om fler skulle skapas när rollover inträffar raderas den äldsta filen. Raderingslogiken använder intervallet för att avgöra vilka filer som ska raderas, så om du ändrar intervallet kan gamla filer bli liggande kvar.

Om delay är true, skjuts filöppningen upp till det första anropet till emit().

Om atTime inte är None, måste det vara en datetime.time-instans som anger den tid på dagen då rollover sker, för de fall då rollover är inställd att ske ”vid midnatt” eller ”på en viss veckodag”. Observera att i dessa fall används atTime-värdet för att beräkna den initiala rollovern, och efterföljande rollovers beräknas via den normala intervallberäkningen.

Om errors anges används det för att bestämma hur kodningsfel ska hanteras.

Anteckning

Beräkningen av den första rollover-tiden görs när hanteraren initialiseras. Beräkning av efterföljande rollover-tider görs endast när rollover inträffar, och rollover inträffar endast när utdata sänds ut. Om man inte tänker på detta kan det leda till viss förvirring. Om du t.ex. anger ett intervall på ”varje minut” betyder det inte att du alltid kommer att se loggfiler med tider (i filnamnet) som är åtskilda med en minut; om loggningsutdata genereras oftare än en gång i minuten under programmets exekvering, då kan du förvänta dig att se loggfiler med tider som är åtskilda med en minut. Om loggmeddelanden å andra sidan bara matas ut var femte minut (t.ex.), kommer det att finnas luckor i filtiderna som motsvarar de minuter då ingen utmatning (och därmed ingen rollover) har skett.

Ändrad i version 3.4: atTime-parametern har lagts till.

Ändrad i version 3.6: Förutom strängvärden accepteras även Path-objekt för argumentet filnamn.

Ändrad i version 3.9: Parametern errors har lagts till.

doRollover()

Gör en vältning, enligt beskrivningen ovan.

emit(record)

Skickar ut posten till filen och tar hand om rollover enligt beskrivningen ovan.

getFilesToDelete()

Returnerar en lista med filnamn som ska raderas som en del av rollover. Dessa

shouldRollover(record)

Se om det har gått tillräckligt lång tid för att en rollover ska inträffa och om så är fallet, beräkna nästa rollover-tid.

SocketHandler

Klassen SocketHandler, som finns i modulen logging.handlers, skickar loggningsutdata till ett nätverkssocket. Basklassen använder ett TCP-socket.

class logging.handlers.SocketHandler(host, port)

Returnerar en ny instans av SocketHandler-klassen avsedd att kommunicera med en fjärrmaskin vars adress anges av host och port.

Ändrad i version 3.4: Om port anges som None skapas ett Unix-domänuttag med hjälp av värdet i host - i annat fall skapas ett TCP-uttag.

close()

Stänger uttaget.

emit()

Plockar upp postens attributordbok och skriver den till sockeln i binärt format. Om det uppstår ett fel med sockeln släpps paketet i tysthet. Om anslutningen tidigare har förlorats återupprättas anslutningen. För att avpickla posten i mottagaränden till en LogRecord, använd funktionen makeLogRecord().

handleError()

Hanterar ett fel som har inträffat under emit(). Den mest troliga orsaken är en förlorad anslutning. Stänger sockeln så att vi kan försöka igen vid nästa händelse.

makeSocket()

Detta är en fabriksmetod som gör det möjligt för underklasser att definiera exakt vilken typ av socket de vill ha. Standardimplementeringen skapar ett TCP-socket (socket.SOCK_STREAM).

makePickle(record)

Plockar upp postens attributordbok i binärt format med ett längdprefix och returnerar den klar för överföring via sockeln. Detaljerna för denna operation är likvärdiga med:

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
returnera datalen + data

Observera att pickles inte är helt säkra. Om du är orolig för säkerheten kanske du vill åsidosätta den här metoden för att implementera en säkrare mekanism. Du kan t.ex. signera pickles med HMAC och sedan verifiera dem i den mottagande änden, eller så kan du inaktivera unpickling av globala objekt i den mottagande änden.

send(packet)

Skicka en picklad byte-sträng packet till sockeln. Formatet på den skickade byte-strängen är som beskrivs i dokumentationen för makePickle().

Denna funktion möjliggör partiella sändningar, vilket kan inträffa när nätverket är upptaget.

createSocket()

Försöker skapa ett uttag; om det misslyckas används en exponentiell back-off-algoritm. Vid ett första misslyckande kommer hanteraren att släppa meddelandet som den försökte skicka. När efterföljande meddelanden hanteras av samma instans kommer den inte att försöka ansluta förrän en viss tid har gått. Standardparametrarna är sådana att den första fördröjningen är en sekund, och om anslutningen fortfarande inte kan upprättas efter denna fördröjning kommer hanteraren att dubbla fördröjningen varje gång upp till maximalt 30 sekunder.

Detta beteende styrs av följande hanterarattribut:

• retryStart (initial fördröjning, standardvärde 1,0 sekunder).

• retryFactor (multiplikator, standardvärde 2,0).

• retryMax (maximal fördröjning, standardvärde 30,0 sekunder).

Det innebär att om fjärrlyssnaren startar efter att hanteraren har använts kan du förlora meddelanden (eftersom hanteraren inte ens försöker upprätta en anslutning förrän fördröjningen har gått ut, utan bara tyst släpper meddelanden under fördröjningsperioden).

DatagramHanterare

Klassen DatagramHandler, som finns i modulen logging.handlers, ärver från SocketHandler för att stödja sändning av loggmeddelanden via UDP-sockets.

class logging.handlers.DatagramHandler(host, port)

Returnerar en ny instans av klassen DatagramHandler som är avsedd att kommunicera med en fjärrmaskin vars adress anges av host och port.

Anteckning

Eftersom UDP inte är ett streamingprotokoll finns det ingen beständig anslutning mellan en instans av den här hanteraren och host. Därför kan en DNS-uppslagning behöva göras varje gång en händelse loggas när ett nätverksuttag används, vilket kan medföra viss fördröjning i systemet. Om detta påverkar dig kan du göra en sökning själv och initiera den här hanteraren med hjälp av den sökta IP-adressen i stället för värdnamnet.

Ändrad i version 3.4: Om port anges som None skapas ett Unix-domänuttag med hjälp av värdet i host - annars skapas ett UDP-uttag.

emit()

Plockar upp postens attributordbok och skriver den till sockeln i binärt format. Om det uppstår ett fel med sockeln släpps paketet i tysthet. För att avpickla posten i mottagaränden till en LogRecord, använd funktionen makeLogRecord().

makeSocket()

Fabriksmetoden för SocketHandler åsidosätts här för att skapa en UDP-socket (socket.SOCK_DGRAM).

send(s)

Skicka en picklad byte-sträng till en socket. Formatet på den skickade byte-strängen är som beskrivet i dokumentationen för SocketHandler.makePickle().

SysLogHandler

Klassen SysLogHandler, som finns i modulen logging.handlers, stöder sändning av loggmeddelanden till en fjärrstyrd eller lokal Unix syslog.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM, timeout=None)

Returnerar en ny instans av klassen SysLogHandler som är avsedd att kommunicera med en Unix-fjärrmaskin vars adress anges av address i form av en (host, port)-tupel. Om address inte anges används ('localhost', 514). Adressen används för att öppna ett uttag. Ett alternativ till att tillhandahålla en (host, port)-tupel är att tillhandahålla en adress som en sträng, till exempel ’/dev/log’. I det här fallet används ett Unix-domänuttag för att skicka meddelandet till syslog. Om facility inte specificeras används LOG_USER. Vilken typ av socket som öppnas beror på argumentet socktype, som i standardfallet är socket.SOCK_DGRAM och därmed öppnar ett UDP-socket. Om du vill öppna ett TCP-socket (för användning med nyare syslog-daemons som rsyslog) anger du värdet socket.SOCK_STREAM. Om timeout specificeras anges en timeout (i sekunder) för socket-operationerna. Detta kan hjälpa till att förhindra att programmet hänger sig på obestämd tid om syslog-servern inte går att nå. Som standard är timeout None, vilket innebär att ingen timeout tillämpas.

Observera att om din server inte lyssnar på UDP-port 514 kan det hända att SysLogHandler inte fungerar. Kontrollera i så fall vilken adress du ska använda för ett domänuttag - det är systemberoende. På Linux är det t.ex. vanligtvis ’/dev/log’ men på OS/X är det ’/var/run/syslog’. Du måste kontrollera din plattform och använda rätt adress (du kan behöva göra den här kontrollen vid körning om din applikation behöver köras på flera plattformar). På Windows måste du i stort sett använda UDP-alternativet.

Anteckning

På macOS 12.x (Monterey) har Apple ändrat beteendet hos sin syslog-daemon - den lyssnar inte längre på ett domänuttag. Därför kan du inte förvänta dig att SysLogHandler ska fungera på detta system.

Se gh-91070 för mer information.

Ändrad i version 3.2: socktype lades till.

Ändrad i version 3.14: timeout har lagts till.

close()

Stänger kontakten till fjärrvärden.

createSocket()

Försöker skapa ett uttag och, om det inte är ett datagramuttag, ansluta det till den andra änden. Denna metod anropas under initialiseringen av hanteraren, men det betraktas inte som ett fel om den andra änden inte lyssnar vid denna tidpunkt - metoden kommer att anropas igen när en händelse sänds ut, om det inte finns någon socket vid den tidpunkten.

Tillagd i version 3.11.

emit(record)

Posten formateras och skickas sedan till syslog-servern. Om det finns information om undantag skickas den inte till servern.

Ändrad i version 3.2.1: (Se: bpo-12168.) I tidigare versioner avslutades meddelandet som skickades till syslog-daemonerna alltid med en NUL-byte, eftersom tidiga versioner av dessa daemoner förväntade sig ett NUL-avslutat meddelande - trots att det inte finns med i den relevanta specifikationen (RFC 5424). Nyare versioner av dessa daemoner förväntar sig inte NUL-byten utan tar bort den om den finns där, och ännu nyare daemoner (som följer RFC 5424 mer noggrant) skickar NUL-byten vidare som en del av meddelandet.

För att göra det lättare att hantera syslog-meddelanden trots alla dessa olika daemonbeteenden har tillägget av NUL-byte gjorts konfigurerbart genom att använda ett attribut på klassnivå, append_nul. Detta är som standard inställt på True (bevarar det befintliga beteendet) men kan sättas till False på en SysLogHandler-instans för att den instansen inte ska lägga till NUL-terminatorn.

Ändrad i version 3.3: (Se: bpo-12419.) I tidigare versioner fanns det ingen möjlighet att använda prefixet ”ident” eller ”tag” för att identifiera källan till meddelandet. Detta kan nu specificeras med hjälp av ett attribut på klassnivå, med "" som standard för att bevara befintligt beteende, men som kan åsidosättas för en SysLogHandler-instans så att den instansen lägger till ident till varje meddelande som hanteras. Observera att den angivna identen måste vara text, inte bytes, och läggs till meddelandet precis som det är.

encodePriority(facility, priority)

Kodar faciliteten och prioriteten till ett heltal. Du kan skicka in strängar eller heltal - om strängar skickas in används interna mappningsordböcker för att konvertera dem till heltal.

De symboliska LOG_-värdena definieras i SysLogHandler och speglar de värden som definieras i header-filen sys/syslog.h.

Prioriteringar

Namn (sträng)	Symboliskt värde
alert	LOG_ALERT
crit eller critical	LOG_CRIT
debug	LOG_DEBUG
emerg eller panic	LOG_EMERG
err eller error	LOG_ERR
info	LOG_INFO
notice	LOG_NOTICE
warn eller warning	LOG_WARNING

Faciliteter

Namn (sträng)	Symboliskt värde
auth	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
daemon	LOG_DAEMON
ftp	LOG_FTP
kern	LOG_KERN
lpr	LOG_LPR
mail	LOG_MAIL
news	LOG_NEWS
syslog	LOG_SYSLOG
user	LOG_USER
uucp	LOG_UUCP
local0	LOG_LOCAL0
local1	LOG_LOCAL1
local2	LOG_LOCAL2
local3	LOG_LOCAL3
local4	LOG_LOCAL4
local5	LOG_LOCAL5
local6	LOG_LOCAL6
local7	LOG_LOCAL7

mapPriority(levelname)

Mappar ett namn på en loggningsnivå till ett namn på en syslog-prioritet. Du kan behöva åsidosätta detta om du använder anpassade nivåer eller om standardalgoritmen inte är lämplig för dina behov. Standardalgoritmen mappar DEBUG, INFO, WARNING, ERROR och CRITICAL till motsvarande syslog-namn, och alla andra nivånamn till ’warning’.

NTEventLogHandler

Klassen NTEventLogHandler, som finns i modulen logging.handlers, stöder sändning av loggmeddelanden till en lokal händelselogg i Windows NT, Windows 2000 eller Windows XP. Innan du kan använda den måste du ha Mark Hammonds Win32 extensions for Python installerat.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

Returnerar en ny instans av NTEventLogHandler-klassen. appname används för att definiera programnamnet så som det visas i händelseloggen. En lämplig registerpost skapas med hjälp av detta namn. dllname bör ange det fullständiga sökvägsnamnet för en .dll- eller .exe-fil som innehåller meddelandedefinitioner som ska sparas i loggen (om inget anges används 'win32service.pyd' - denna installeras med Win32-tilläggen och innehåller några grundläggande platshållare för meddelandedefinitioner. Observera att om du använder dessa platshållare blir dina händelseloggar stora, eftersom hela meddelandekällan sparas i loggen. Om du vill ha mindre loggar måste du ange namnet på din egen .dll- eller .exe-fil som innehåller de meddelandedefinitioner som du vill använda i händelseloggen.) loggtyp är en av 'Application', 'System' eller 'Security', och standardvärdet är 'Application'.

close()

Nu kan du ta bort programnamnet från registret som en källa till händelseloggposter. Om du gör detta kommer du dock inte att kunna se händelserna som du tänkt dig i Loggboken - den måste kunna komma åt registret för att hämta .dll-namnet. Den nuvarande versionen gör inte detta.

emit(record)

Fastställer meddelandets ID, händelsekategori och händelsetyp och loggar sedan meddelandet i NT:s händelselogg.

getEventCategory(record)

Returnerar händelsekategorin för posten. Åsidosätt detta om du vill ange dina egna kategorier. Denna version returnerar 0.

getEventType(record)

Returnerar händelsetypen för posten. Åsidosätt detta om du vill ange dina egna typer. Denna version gör en mappning med hjälp av hanterarens typemap-attribut, som konfigureras i __init__() till en ordbok som innehåller mappningar för DEBUG, INFO, WARNING, ERROR och CRITICAL. Om du använder dina egna nivåer måste du antingen åsidosätta den här metoden eller placera en lämplig ordbok i hanterarens typemap-attribut.

getMessageID(record)

Returnerar meddelandets ID för posten. Om du använder dina egna meddelanden kan du göra detta genom att låta msg som skickas till loggern vara ett ID snarare än en formatsträng. Här kan du sedan använda en ordboksuppslagning för att få fram meddelandets ID. Den här versionen returnerar 1, vilket är basmeddelandets ID i win32service.pyd.

SMTPHandler

Klassen SMTPHandler, som finns i modulen logging.handlers, stöder sändning av loggade meddelanden till en e-postadress via SMTP.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Returnerar en ny instans av SMTPHandler-klassen. Instansen initieras med från- och till-adresserna och ämnesraden för e-postmeddelandet. toaddrs bör vara en lista med strängar. Om du vill ange en SMTP-port som inte är standard använder du tuple-formatet (host, port) för mailhost-argumentet. Om du använder en sträng används standard SMTP-port. Om din SMTP-server kräver autentisering kan du ange en tuple (användarnamn, lösenord) för argumentet credentials.

Om du vill ange att ett säkert protokoll (TLS) ska användas, skickar du in en tupel till argumentet secure. Detta kommer endast att användas när autentiseringsuppgifter anges. Tupeln ska antingen vara en tom tupel, eller en tupel med ett värde med namnet på en nyckelfil, eller en tupel med två värden med namnen på nyckelfilen och certifikatfilen. (Denna tupel skickas till metoden smtplib.SMTP.starttls())

En timeout kan anges för kommunikationen med SMTP-servern med argumentet timeout.

Ändrad i version 3.3: Parametern timeout har lagts till.

emit(record)

Formaterar posten och skickar den till de angivna adressaterna.

getSubject(record)

Om du vill ange en ämnesrad som är beroende av posten åsidosätter du den här metoden.

MemoryHandler

Klassen MemoryHandler, som finns i modulen logging.handlers, stöder buffring av loggningsposter i minnet och periodisk överföring av dem till en target-hanterare. Flushing sker när bufferten är full eller när en händelse av en viss allvarlighetsgrad eller större inträffar.

MemoryHandler är en subklass av den mer generella BufferingHandler, som är en abstrakt klass. Denna buffrar loggningsposter i minnet. När varje post läggs till i bufferten görs en kontroll genom att anropa shouldFlush() för att se om bufferten ska tömmas. Om så är fallet förväntas flush() utföra rensningen.

class logging.handlers.BufferingHandler(capacity)

Initialiserar hanteraren med en buffert med den angivna kapaciteten. Här betyder kapacitet det antal loggningsposter som buffras.

emit(record)

Lägger till posten till bufferten. Om shouldFlush() returnerar true, anropa flush() för att bearbeta bufferten.

flush()

För en BufferingHandler-instans innebär flushing att den sätter bufferten till en tom lista. Denna metod kan skrivas över för att implementera ett mer användbart spolningsbeteende.

shouldFlush(record)

Returnerar True om bufferten har full kapacitet. Denna metod kan åsidosättas för att implementera anpassade spolningsstrategier.

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Returnerar en ny instans av MemoryHandler-klassen. Instansen initialiseras med en buffertstorlek på capacity (antal poster som buffras). Om flushLevel inte anges används ERROR. Om inget target anges måste målet anges med setTarget() innan den här hanteraren gör något användbart. Om flushOnClose anges som False, så spolas bufferten inte när hanteraren stängs. Om den inte specificeras eller specificeras som True, kommer det tidigare beteendet att spola bufferten att inträffa när hanteraren stängs.

Ändrad i version 3.6: Parametern flushOnClose har lagts till.

close()

Anropar flush(), sätter målet till None och tömmer bufferten.

flush()

För en instans av MemoryHandler innebär flushing att de buffrade posterna bara skickas till målet, om det finns ett sådant. Bufferten rensas också när buffrade poster skickas till målet. Åsidosätt om du vill ha ett annat beteende.

setTarget(target)

Ställer in målhanteraren för denna hanterare.

shouldFlush(record)

Kontrollerar om bufferten är full eller om det finns en post på flushLevel eller högre.

HTTHANDLER

Klassen HTTPHandler, som finns i modulen logging.handlers, stöder sändning av loggmeddelanden till en webbserver, antingen med semantiken GET eller POST.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

Returnerar en ny instans av HTTPHandler-klassen. host kan vara av formen host:port, om du behöver använda ett specifikt portnummer. Om ingen method anges används GET. Om secure är true kommer en HTTPS-anslutning att användas. Parametern context kan sättas till en ssl.SSLContext-instans för att konfigurera SSL-inställningarna som används för HTTPS-anslutningen. Om credentials anges bör det vara en 2-tupel bestående av userid och password, som placeras i ett HTTP ’Authorization’-huvud med Basic-autentisering. Om du anger credentials bör du också ange secure=True så att ditt userid och lösenord inte skickas i klartext över kabeln.

Ändrad i version 3.5: Parametern context har lagts till.

mapLogRecord(record)

Tillhandahåller en ordbok, baserad på record, som ska URL-kodas och skickas till webbservern. Standardimplementeringen returnerar bara record.__dict__. Denna metod kan åsidosättas om t.ex. endast en delmängd av LogRecord ska skickas till webbservern, eller om mer specifik anpassning av vad som skickas till servern krävs.

emit(record)

Skickar posten till webbservern som en URL-kodad ordbok. Metoden mapLogRecord() används för att konvertera posten till den ordbok som ska skickas.

Anteckning

Eftersom förberedelse av en post för att skicka den till en webbserver inte är samma sak som en generisk formateringsoperation, har det ingen effekt att använda setFormatter() för att ange en Formatter för en HTTPHandler. Istället för att anropa format() anropar denna hanterare mapLogRecord() och sedan urllib.parse.urlencode() för att koda ordlistan i en form som är lämplig att skicka till en webbserver.

Köhanterare

Tillagd i version 3.2.

Klassen QueueHandler, som finns i modulen logging.handlers, stöder sändning av loggade meddelanden till en kö, t.ex. de som implementeras i modulerna queue eller multiprocessing.

Tillsammans med klassen QueueListener kan QueueHandler användas för att låta hanterare utföra sitt arbete på en separat tråd från den som utför loggningen. Detta är viktigt i webbapplikationer och även andra tjänsteapplikationer där trådar som betjänar klienter måste svara så snabbt som möjligt, medan alla potentiellt långsamma operationer (som att skicka ett e-postmeddelande via SMTPHandler) görs på en separat tråd.

class logging.handlers.QueueHandler(queue)

Returnerar en ny instans av QueueHandler-klassen. Instansen initialiseras med den kö som meddelanden ska skickas till. Kön kan vara vilket köliknande objekt som helst; den används som den är av enqueue()-metoden, som behöver veta hur man skickar meddelanden till den. Det är inte krävt att kön har API:et för uppgiftsspårning, vilket innebär att du kan använda SimpleQueue-instanser för queue.

Anteckning

Om du använder multiprocessing bör du undvika att använda SimpleQueue och istället använda multiprocessing.Queue.

Varning

Modulen multiprocessing använder en intern logger som skapas och nås via get_logger(). multiprocessing.Queue kommer att logga meddelanden på DEBUG-nivå när objekt köas. Om dessa loggmeddelanden behandlas av en QueueHandler som använder samma multiprocessing.Queue-instans, kommer det att orsaka ett dödläge eller oändlig rekursion.

emit(record)

Ställer resultatet av förberedelsen av LogRecord i kö. Om ett undantag inträffar (t.ex. för att en begränsad kö har fyllts upp), anropas metoden handleError() för att hantera felet. Detta kan resultera i att posten tyst släpps (om logging.raiseExceptions är False) eller ett meddelande skrivs ut till sys.stderr (om logging.raiseExceptions är True).

prepare(record)

Förbereder en post för köbildning. Det objekt som returneras av denna metod köas.

Basimplementeringen formaterar posten för att sammanfoga meddelandet, argumenten, undantaget och stackinformationen, om sådan finns. Den tar också bort icke-picklebara objekt från posten på plats. Specifikt skriver den över postens attribut msg och message med det sammanslagna meddelandet (som erhålls genom att anropa hanterarens metod format()), och sätter attributen args, exc_info och exc_text till None.

Du kanske vill åsidosätta den här metoden om du vill konvertera posten till en dict- eller JSON-sträng, eller skicka en modifierad kopia av posten medan originalet förblir intakt.

Anteckning

Basimplementationen formaterar meddelandet med argument, sätter attributen message och msg till det formaterade meddelandet och sätter attributen args och exc_text till None för att tillåta pickling och för att förhindra ytterligare försök till formatering. Detta innebär att en hanterare på QueueListener-sidan inte kommer att ha informationen för att göra anpassad formatering, t.ex. av undantag. Du kanske vill underklassa QueueHandler och åsidosätta denna metod för att t.ex. undvika att sätta exc_text till None. Observera att message / msg / args ändringarna är relaterade till att säkerställa att posten är pickleable, och du kanske eller kanske inte kan undvika att göra det beroende på om din args är pickleable. (Observera att du kan behöva överväga inte bara din egen kod utan också kod i alla bibliotek som du använder)

enqueue(record)

Lägger in posten i kön med hjälp av put_nowait(); du kanske vill åsidosätta detta om du vill använda blockeringsbeteende, en timeout eller en anpassad köimplementering.

listener

När detta attribut skapas via konfiguration med dictConfig(), kommer det att innehålla en QueueListener-instans för användning med denna hanterare. Annars kommer det att vara None.

Tillagd i version 3.12.

QueueListener

Tillagd i version 3.2.

Klassen QueueListener, som finns i modulen logging.handlers, stöder mottagning av loggmeddelanden från en kö, t.ex. de som implementeras i modulerna queue eller multiprocessing. Meddelandena tas emot från en kö i en intern tråd och skickas, i samma tråd, till en eller flera hanterare för bearbetning. Även om QueueListener i sig inte är en hanterare, dokumenteras den här eftersom den fungerar tillsammans med QueueHandler.

Tillsammans med klassen QueueHandler kan QueueListener användas för att låta hanterare utföra sitt arbete på en separat tråd från den som utför loggningen. Detta är viktigt i webbapplikationer och även andra tjänsteapplikationer där trådar som betjänar klienter måste svara så snabbt som möjligt, medan alla potentiellt långsamma operationer (som att skicka ett e-postmeddelande via SMTPHandler) görs på en separat tråd.

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

Returnerar en ny instans av QueueListener-klassen. Instansen initialiseras med den kö som meddelanden ska skickas till och en lista över hanterare som ska hantera poster som placeras i kön. Kön kan vara vilket köliknande objekt som helst; den skickas som den är till dequeue()-metoden, som måste veta hur man hämtar meddelanden från den. Det är inte krävt att kön har API för uppgiftsspårning (även om det används om det finns tillgängligt), vilket innebär att du kan använda SimpleQueue-instanser för queue.

Anteckning

Om du använder multiprocessing bör du undvika att använda SimpleQueue och istället använda multiprocessing.Queue.

Om respect_handler_level är True, respekteras en hanterares nivå (jämfört med nivån för meddelandet) när man bestämmer om meddelanden ska skickas till den hanteraren; annars är beteendet som i tidigare Python-versioner - att alltid skicka varje meddelande till varje hanterare.

Ändrad i version 3.5: Argumentet respect_handler_level har lagts till.

Ändrad i version 3.14: QueueListener kan nu användas som en kontexthanterare via with. När du går in i kontexten startas lyssnaren. När kontexten lämnas stoppas lyssnaren. __enter__() returnerar objektet QueueListener.

dequeue(block)

Avköper en post och returnerar den, eventuellt med blockering.

Basimplementeringen använder get(). Du kanske vill åsidosätta den här metoden om du vill använda timeouts eller arbeta med anpassade köimplementeringar.

prepare(record)

Förbered en post för hantering.

Denna implementation returnerar bara den överlämnade posten. Du kanske vill åsidosätta den här metoden om du behöver göra någon anpassad marshalling eller manipulation av posten innan du skickar den till hanterarna.

handle(record)

Hantera en post.

Detta är bara en loop genom hanterarna som erbjuder dem en post att hantera. Det faktiska objektet som skickas till hanterarna är det som returneras från prepare().

start()

Startar lyssnaren.

Detta startar en bakgrundstråd som övervakar kön för LogRecords som ska behandlas.

Ändrad i version 3.14: Utlöser RuntimeError om den anropas och lyssnaren redan är igång.

stop()

Stoppar lyssnaren.

Detta ber tråden att avslutas och väntar sedan på att den ska göra det. Observera att om du inte anropar detta innan programmet avslutas, kan det finnas några poster kvar i kön som inte kommer att behandlas.

enqueue_sentinel()

Skriver en sentinel till kön för att tala om för lyssnaren att den ska sluta. Den här implementationen använder put_nowait(). Du kanske vill åsidosätta den här metoden om du vill använda timeouts eller arbeta med anpassade köimplementeringar.

Tillagd i version 3.3.

Se även

Modul logging

API-referens för loggningsmodulen.

Modul logging.config

Konfigurations-API för loggningsmodulen.