Python-programmerare använder ofta print() i sin kod som ett snabbt och bekvämt felsökningsverktyg. Att använda loggningsramverket är bara lite mer ansträngande än så, men det är mycket mer elegant och flexibelt. Förutom att vara användbart för felsökning kan loggning också ge dig mer - och bättre strukturerad - information om tillståndet och hälsan i din applikation.
Django använder och utökar Pythons inbyggda modul logging för att utföra systemloggning. Denna modul diskuteras i detalj i Pythons egen dokumentation; detta avsnitt ger en snabb översikt.
En Python-loggningskonfiguration består av fyra delar:
\nämne-loggning-delar-loggare
topic-logging-parts-filter
En logger är ingångspunkten till loggningssystemet. Varje logger är en namngiven hink till vilken meddelanden kan skrivas för bearbetning.
\nEn logger är konfigurerad att ha en loggnivå. Denna loggnivå beskriver allvarlighetsgraden i de meddelanden som loggern kommer att hantera. Python definierar följande loggnivåer:
\nDEBUG: Systeminformation på låg nivå för felsökningsändamål
INFO: Allmän systeminformation
VARNING: Information som beskriver ett mindre problem som har uppstått.
ERROR: Information som beskriver ett större problem som har uppstått.
KRITISK: Information som beskriver ett kritiskt problem som har uppstått.
Varje meddelande som skrivs till loggaren är en loggpost. Varje loggpost har också en loggnivå som anger allvarlighetsgraden för det specifika meddelandet. En loggpost kan också innehålla användbara metadata som beskriver den händelse som loggas. Det kan t.ex. vara en stackspårning eller en felkod.
\nNär ett meddelande skickas till loggern jämförs loggnivån för meddelandet med loggnivån för loggern. Om meddelandets loggnivå är lika med eller högre än loggnivån för loggern själv, kommer meddelandet att behandlas vidare. Om den inte gör det ignoreras meddelandet.
\nNär en logger har bestämt att ett meddelande behöver behandlas skickas det till en Handler.
\nHandlaren är den motor som avgör vad som händer med varje meddelande i en logger. Den beskriver ett visst loggningsbeteende, t.ex. att skriva ett meddelande till skärmen, till en fil eller till ett nätverkssocket.
\nPrecis som loggar har även hanterare en loggnivå. Om loggnivån för en loggpost inte uppfyller eller överstiger nivån för hanteraren, ignorerar hanteraren meddelandet.
\nEn logger kan ha flera hanterare och varje hanterare kan ha olika loggnivåer. På så sätt är det möjligt att tillhandahålla olika former av meddelanden beroende på hur viktigt ett meddelande är. Du kan t.ex. installera en hanterare som vidarebefordrar ERROR- och CRITICAL-meddelanden till en personsökningstjänst, medan en andra hanterare loggar alla meddelanden (inklusive ERROR- och CRITICAL-meddelanden) till en fil för senare analys.
Ett filter används för att ge ytterligare kontroll över vilka loggposter som skickas från logger till hanterare.
\nSom standard hanteras alla loggmeddelanden som uppfyller kraven för loggnivå. Genom att installera ett filter kan du dock lägga till ytterligare kriterier för loggningsprocessen. Du kan t.ex. installera ett filter som bara tillåter att ERROR-meddelanden från en viss källa skickas ut.
Filter kan också användas för att ändra loggposten innan den sänds ut. Du kan t.ex. skriva ett filter som nedgraderar loggposter av typen ERROR till WARNING om en viss uppsättning kriterier uppfylls.
Filter kan installeras på loggrar eller på hanterare; flera filter kan användas i en kedja för att utföra flera filtreringsåtgärder.
\nI slutändan måste en loggpost återges som text. Formaterare beskriver det exakta formatet för den texten. En formaterare består vanligtvis av en Python-formateringssträng som innehåller LogRecord attributes; men du kan också skriva anpassade formaterare för att implementera ett specifikt formateringsbeteende.
\nLoggningssystemet hanterar potentiellt känslig information. Loggposten kan t.ex. innehålla information om en webbförfrågan eller ett stackspår, och en del av de data som du samlar in i dina egna loggar kan också ha säkerhetsimplikationer. Du måste vara säker på att du vet:
\nvilken information som samlas in
var den därefter kommer att förvaras
hur det kommer att överföras
som kan ha tillgång till den.
För att kontrollera insamlingen av känslig information kan du uttryckligen ange att viss känslig information ska filtreras bort från felrapporter – läs mer om hur du filtrerar felrapporter.
\nAdminEmailHandlerLink to this heading#Den inbyggda AdminEmailHandler förtjänar ett omnämnande i säkerhetssammanhang. Om dess alternativ include_html är aktiverat kommer e-postmeddelandet som skickas att innehålla en fullständig spårning, med namn och värden på lokala variabler på varje nivå i stacken, plus värdena på dina Django-inställningar (med andra ord samma detaljnivå som exponeras på en webbsida när DEBUG är True).
Det anses i allmänhet inte vara en bra idé att skicka sådan potentiellt känslig information via e-post. Överväg istället att använda en av de många tredjepartstjänster som detaljerade loggar kan skickas till för att få det bästa av flera världar - den rika informationen från fullständiga spårningar, tydlig hantering av vem som meddelas och har tillgång till informationen, och så vidare.
\nPythons loggningsbibliotek tillhandahåller flera tekniker för att konfigurera loggning, allt från ett programmatiskt gränssnitt till konfigurationsfiler. Som standard använder Django dictConfig-formatet.
\nFör att konfigurera loggning använder du LOGGING för att definiera en ordlista med loggningsinställningar. Dessa inställningar beskriver de loggar, hanterare, filter och formatterare som du vill ha i din loggningskonfiguration, samt de loggnivåer och andra egenskaper som du vill att dessa komponenter ska ha.
Som standard slås inställningen LOGGING samman med Djangos standardkonfiguration för loggning enligt följande schema.
Om nyckeln disable_existing_loggers i dictConfig för LOGGING är inställd på True (vilket är standardvärdet för dictConfig om nyckeln saknas) kommer alla loggar från standardkonfigurationen att inaktiveras. Inaktiverade loggrar är inte samma sak som borttagna; loggern kommer fortfarande att existera, men kommer i tysthet att kasta allt som loggas till den, inte ens sprida poster till en överordnad logger. Du bör därför vara mycket försiktig med att använda 'disable_existing_loggers': True; det är förmodligen inte vad du vill. Istället kan du sätta disable_existing_loggers till False och omdefiniera några eller alla standardloggare; eller så kan du sätta LOGGING_CONFIG till None och handle logging config yourself.
Loggning konfigureras som en del av den allmänna Django setup()-funktionen. Därför kan du vara säker på att loggar alltid är redo att användas i din projektkod.
Den fullständiga dokumentationen för dictConfig format är den bästa källan till information om loggningskonfigurationsordböcker. Men för att ge dig en försmak av vad som är möjligt följer här några exempel.
\nTill att börja med följer här en liten konfiguration som gör att du kan mata ut alla loggmeddelanden till konsolen:
\nsettings.pyimport os\n\nLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "handlers": {\n "console": {\n "class": "logging.StreamHandler",\n },\n },\n "root": {\n "handlers": ["console"],\n "level": "WARNING",\n },\n}\nDetta konfigurerar den överordnade root-loggaren att skicka meddelanden med nivån WARNING och högre till konsolhanteraren. Genom att justera nivån till INFO eller DEBUG kan du visa fler meddelanden. Detta kan vara användbart under utveckling.
Därefter kan vi lägga till mer finkornig loggning. Här är ett exempel på hur man får loggningssystemet att skriva ut fler meddelanden från bara den django som heter logger:
\nsettings.pyimport os\n\nLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "handlers": {\n "console": {\n "class": "logging.StreamHandler",\n },\n },\n "root": {\n "handlers": ["console"],\n "level": "WARNING",\n },\n "loggers": {\n "django": {\n "handlers": ["console"],\n "level": os.getenv("DJANGO_LOG_LEVEL", "INFO"),\n "propagate": False,\n },\n },\n}\nSom standard skickar den här konfigurationen meddelanden från django-loggen på nivå INFO eller högre till konsolen. Detta är samma nivå som Djangos standardkonfiguration för loggning, förutom att standardkonfigurationen endast visar loggposter när DEBUG=True. Django loggar inte många sådana meddelanden på INFO-nivå. Med denna konfiguration kan du dock också ställa in miljövariabeln DJANGO_LOG_LEVEL=DEBUG för att se all Djangos felsökningsloggning som är mycket utförlig eftersom den inkluderar alla databasfrågor.
Du behöver inte logga till konsolen. Här är en konfiguration som skriver all loggning från django med namnet logger till en lokal fil:
\nsettings.pyLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "handlers": {\n "file": {\n "level": "DEBUG",\n "class": "logging.FileHandler",\n "filename": "/path/to/django/debug.log",\n },\n },\n "loggers": {\n "django": {\n "handlers": ["file"],\n "level": "DEBUG",\n "propagate": True,\n },\n },\n}\nOm du använder det här exemplet måste du ändra sökvägen för 'filnamn till en plats som är skrivbar för den användare som kör Django-applikationen.
Slutligen, här är ett exempel på en ganska komplex loggningskonfiguration:
\nsettings.pyLOGGING = {\n "version": 1,\n "disable_existing_loggers": False,\n "formatters": {\n "verbose": {\n "format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",\n "style": "{",\n },\n "simple": {\n "format": "{levelname} {message}",\n "style": "{",\n },\n },\n "filters": {\n "special": {\n "()": "project.logging.SpecialFilter",\n "foo": "bar",\n },\n "require_debug_true": {\n "()": "django.utils.log.RequireDebugTrue",\n },\n },\n "handlers": {\n "console": {\n "level": "INFO",\n "filters": ["require_debug_true"],\n "class": "logging.StreamHandler",\n "formatter": "simple",\n },\n "mail_admins": {\n "level": "ERROR",\n "class": "django.utils.log.AdminEmailHandler",\n "filters": ["special"],\n },\n },\n "loggers": {\n "django": {\n "handlers": ["console"],\n "propagate": True,\n },\n "django.request": {\n "handlers": ["mail_admins"],\n "level": "ERROR",\n "propagate": False,\n },\n "myproject.custom": {\n "handlers": ["console", "mail_admins"],\n "level": "INFO",\n "filters": ["special"],\n },\n },\n}\nDen här loggningskonfigurationen gör följande:
\nIdentifierar konfigurationen som att den är i formatet ”dictConfig version 1”. För närvarande är detta den enda versionen av dictConfig-formatet.
Definierar två formatterare:
\nsimple, som matar ut namnet på loggnivån (t.ex. DEBUG) och loggmeddelandet.
Strängen format är en vanlig Python-formateringssträng som beskriver de detaljer som ska skrivas ut på varje loggningsrad. Den fullständiga listan över detaljer som kan matas ut finns i Formatter Objects.
verbose, som ger ut namnet på loggnivån, loggmeddelandet samt tid, process, tråd och modul som genererar loggmeddelandet.
Definierar två filter:
\nproject.logging.SpecialFilter, med aliaset special. Om det här filtret kräver ytterligare argument kan de anges som ytterligare nycklar i filterkonfigurationsordlistan. I det här fallet kommer argumentet foo att ges värdet bar när SpecialFilter instansieras.
django.utils.log.RequireDebugTrue, som vidarebefordrar poster när DEBUG är True.
Definierar två handläggare:
\nconsole, en StreamHandler`, som skriver ut valfritt INFO (eller högre) meddelande till sys.stderr. Denna hanterare använder utdataformatet simple.
mail_admins, en AdminEmailHandler, som e-postar alla ERROR (eller högre) meddelanden till webbplatsens ADMINS. Denna hanterare använder filtret special.
Konfigurerar tre loggrar:
\ndjango, som skickar alla meddelanden till console-hanteraren.
django.request, som skickar alla ERROR-meddelanden till mail_admins-hanteraren. Dessutom är denna logger markerad för att inte sprida meddelanden. Detta innebär att loggmeddelanden som skrivs till django.request inte kommer att hanteras av loggern django.
myproject.custom, som skickar alla meddelanden på INFO eller högre som också passerar special-filtret till två hanterare – konsolen och mail_admins. Detta innebär att alla meddelanden på INFO-nivå (eller högre) skrivs ut till konsolen; ERROR- och CRITICAL-meddelanden skickas också ut via e-post.
Om du inte vill använda Pythons dictConfig-format för att konfigurera din logger kan du ange ditt eget konfigurationsschema.
\nThe LOGGING_CONFIG setting defines the callable that will\nbe used to configure Django’s loggers. By default, it points at\nPython’s logging.config.dictConfig() function. However, if you want to\nuse a different configuration process, you can use any other callable\nthat takes a single argument. The contents of LOGGING will\nbe provided as the value of that argument when logging is configured.
Om du inte vill konfigurera loggning alls (eller om du vill konfigurera loggning manuellt med din egen metod) kan du ställa in LOGGING_CONFIG till None. Detta kommer att inaktivera konfigurationsprocessen för Djangos standardloggning.
Om du ställer in LOGGING_CONFIG till None betyder det bara att den automatiska konfigurationsprocessen inaktiveras, inte själva loggningen. Om du inaktiverar konfigurationsprocessen kommer Django fortfarande att göra loggningsanrop och falla tillbaka till det standardloggningsbeteende som har definierats.
Här är ett exempel som inaktiverar Djangos loggningskonfiguration och sedan konfigurerar loggning manuellt:
\nsettings.pyLOGGING_CONFIG = None\n\nimport logging.config\n\nlogging.config.dictConfig(...)\nObservera att standardkonfigurationsprocessen anropar LOGGING_CONFIG först när inställningarna är helt laddade. Om du däremot konfigurerar loggningen manuellt i din inställningsfil laddas din loggningskonfiguration omedelbart. Därför måste din loggningskonfiguration visas efter alla inställningar som den är beroende av.