-
Notifications
You must be signed in to change notification settings - Fork 18
Ghid pentru logging
Logarea ne deschide o fereastra spre comportamentul unui sistem. Scopul acestui document e sa ofere un ghid simplu pentru logare in componentele CZL.
Mesajele de logging sunt in text simplu, cu un mesaj pe linie. Fiecare mesaj trebuie sa aiba acelasi prefix, compus din cateva elemente descrise in tabelul de mai jos.
| Element | Format | Exemplu | Observatii |
|---|---|---|---|
| timestamp | ISO-8601 in standard UTC | 2017-04-04T15:57:26,270Z | |
| id-ul componentei | vezi sub-sectiunea urmatoare | czl-scrape-comunicatii | |
| numele procesului sau al firului de executie | alfanumeric | main | e de preferat numele firului de executie pentru un proces cu multiple fire de executie |
| nivelul de logare | unul din ERROR, WARN, INFO sau DEBUG | INFO | |
| numele complet al modulului, clasei sau functiei | alfanumeric | ro.code4.czl.scrape.ScraperComunicatii | e de preferat o informatie cat mai completa, fara a face insa un compromis la nivel de complexitate sau performanta |
Un exemplu de mesaj pentru scraperul de la comunicatii:
2017-04-04T15:57:26,270Z srv="czl-scrape-comunicatii" [main] INFO ro.code4.czl.scrape.ScraperComunicatii Parsing complete url="https://www.comunicatii.gov.ro/?page_id=3517"
Datele de interes din mesaje trebuie scrise in format cheie-valoare, iar valorile sa fie intotdeauna intre ghilimele. Asta va ajuta la cautari si la extragerea de informatii din mesaje.
Un element din prefixul mesajelor este id-ul componentei. Valoarea id-ului este:
- czl-api pentru API-ul CZL
- czl-scrape-minister> pentru scrapere, unde minister este numele simplu al ministerului pentru care este scris scraperul. De exemplu, id-ul scraperului pentru Ministerul Comunicatiilor va fi czl-scrape-comunicatii
Este irelevant unde ajung si cum sunt stocate mesajele. Singurul lucru important este ca toate mesajele de logging sa fie scrise in stderr. De acolo mesajele vor fi directionate in functie de mediul de executie, posibil agregate intr-un sistem comun.
Fiecare mesaj ar trebui logat la nivelul potrivit. Cateva reguli de bun simt:
- Nivelul ERROR trebuie folosit pentru erorile critice din care aplicatia nu isi poate reveni si care trebuie investigate imediat. Stiva exceptiilor trebuie obligatoriu logata.
- Nivelul WARN trebuie folosit pentru erorile din care aplicatia isi poate reveni sau pentru a semnala eventuale probleme. Daca e vorba de o exceptie, stiva ei trebuie obligatoriu logata. Daca e vorba de o problema pe care aplicatia o poate trata fara interventie manuala, ar trebui insotit de un mesaj care sa descrie problema.
- Nivelul INFO trebuie folosit pentru a marca operatiile sau procesele care se executa cu succes, alaturi de schimbari in starea aplicatiei. De exemplu, cand un scraper a parsat cu succes o pagina.
- Nivelul DEBUG trebuie folosit doar pentru mesaje care ajuta la debugging. Cateva exemple sunt in sectiunile urmatoare.
Majoritatea sistemelor de logging au suport pentru notiunea de date de context care sunt atasate fiecarui mesaj. In general acest context de diagnostic este implementat la nivel de fir de executie, dar asta nu este o regula. Indiferent cum este implementat, contextul de diagnostic este extrem de util intr-o investigatie a unei probleme. Este deci recomandat ca acest context de diagnostic sa fie populat cu date care ulterior sunt automat logate alaturi de fiecare mesaj.
Bugurile care apar in timpul dezvoltarii pot fi investigate folosind un debugger. Din pacate asta nu se aplica si intr-un mediu de productie; acolo ne putem insa folosi, printre altele, de loguri. Un mod de a face logurile cat mai utile in cazul asta este sa logam argumentele unei metode cat si valorile de raspuns. Cum se implementeaza asta e un detaliu care tine de platforma pe care este construita aplicatia, de tehnologiile folosite si asa mai departe. Ce trebuie retinut insa este ca pentru acest gen de logare trebuie folosit nivelul DEBUG.
Cand aplicatia comunica cu o alta componenta sau un sistem extern, e foarte util sa logam datele de intrare si de iesire. Asta ajuta la diagnosticarea problemelor care apar intre componente care comunica dupa un contract bine definit.
E posibil ca uneori cantitatea de date care circula intre componente sa fie atat de mare incat logarea datelor sa fie problematica. Pentru acest gen de logare trebuie folosit nivelul DEBUG.