Logarea este prezentă universal în proiectele software și are multe forme, cerințe și arome diferite.

Înregistrarea este peste tot, de la startup-uri mici de 1 persoană până la întreprinderi mari. Chiar și o simplă întrebare de programare algoritmică implică unele înregistrări de-a lungul drumului.

Ne bazăm atât de mult pe jurnalizare pentru a dezvolta, întreține și menține programele noastre în funcțiune. Cu toate acestea, nu s-a acordat prea multă atenție modului de proiectare a înregistrării în sistemele noastre.

De multe ori, jurnalizarea este tratată ca un al doilea gând – este presărată doar în codul sursă la implementare, cum ar fi o pulbere magică care ajută la ușurarea abisului operațional de zi cu zi din sistemele noastre.

Pentru a va conecta sau a nu va inregistra
Suntem cu toții log baes?

La fel cum orice bucată de cod scrisă va deveni în cele din urmă o datorie tehnică – un proces pe care îl putem încetini doar cu o mare disciplină – jurnalistii putrezesc cu o viteză incredibilă. După un timp, ne găsim rezolvarea problemelor cauzate de jurnalisti mai des decât ne oferă informațiile utile.

Deci, cum putem gestiona această mizerie cu jurnalisti și să îi transformăm într-unul dintre aliații noștri, în loc de fantome moștenite care ne bântuie din greșelile de dezvoltare din trecut?

“De ultimă oră”

Înainte să mă adânc în soluția propusă, să definim o afirmație concretă a problemei pe baza observațiilor mele.

Deci, ce anume este jurnalizarea? Iată o linie interesantă și on-line pe care am găsit-o Articolul lui Colin Eberhardt:

Înregistrarea este procesul de înregistrare a acțiunilor și stării aplicației pe o interfață secundară.

Exact așa se înregistrează logarea în sisteme. Se pare că toți suntem de acord în mod inconștient că jurnalistii nu aparțin niciunui strat anume al sistemelor noastre. În schimb, le considerăm a fi la nivel de aplicație și partajate între diferite componente.

Pentru a va conecta sau a nu va inregistra
Un răspuns mult aprobat pe StackOverflow

O diagramă simplă în care înregistrarea logistică a fost încadrată într-un sistem proiectat cu arhitectură curată ar arăta cam așa:

1611074527 868 Pentru a va conecta sau a nu va inregistra

Putem spune în siguranță că înregistrarea în sine este un subsistem în cadrul aplicației noastre. Și putem spune în siguranță că, fără o analiză atentă, deseori scapă de sub control mai repede decât credem.

În timp ce proiectarea înregistrării în jurnal pentru a fi un subsistem în cadrul aplicațiilor noastre nu este greșită, percepția tradițională a înregistrării (cu 4 până la 6 niveluri de info, warn, error, debug, și așa mai departe) îi face adesea pe dezvoltatori să se concentreze asupra lucrului greșit. Ne face să ne concentrăm mai degrabă pe format decât pe scopul real al motivului pentru care scriem jurnale.

Acesta este unul dintre motivele pentru care deconectăm erorile fără să ne gândim de două ori la modul de gestionare a acestora. Este, de asemenea, motivul pentru care ne conectăm la fiecare pas al codului nostru, în timp ce în mod ironic nu putem să depanăm eficient dacă există o problemă de producție.

Acesta este motivul pentru care propun un cadru alternativ pentru logare și, la rândul său, modul în care putem proiecta logarea în sistemele noastre în mod fiabil.

Cel bun cel rau si cel urat

Acesta este un cadru pentru modul în care cred că ar trebui să ne strategizăm exploatarea forestieră. Are trei – și doar trei – categorii sau preocupări pentru jurnalele noastre.

Prima regulă de înregistrare: Nu vă conectați

Suprasolicitarea este în detrimentul productivității și capacității echipelor noastre de a gestiona operațiunile obișnuite.

Există o mulțime de motive pentru care nu ar trebui „să ne conectăm ori de câte ori puteți”, așa cum recomandă unele fanfare de observabilitate. Înregistrarea înseamnă mai mult cod de întreținut, implică cheltuieli în ceea ce privește performanța sistemului și mai multă jurnalizare ne supune mai multor audituri de reglementare a confidențialității datelor.

Dacă aveți nevoie de mai multe motive pentru a vă abține de la conectare, verificați acest post de Nikita Sobolev sau acest post de Jeff Atwood.

Cu toate acestea, nu vă sfătuiesc să eliminați complet jurnalele. Cred că jurnalizarea, utilizată corect, ne poate ajuta în mod semnificativ să menținem sistemele noastre funcționale în mod fiabil.

Propun doar să începem fără a ne loga și să ne îndreptăm spre identificarea locurilor în care trebuie să ne conectăm, mai degrabă decât „să ne conectăm peste tot în timp ce noi ar putea trebuie să le privim ”.

Regula mea generală pentru adăugarea unei linii de înregistrare este „dacă nu putem stabili un motiv exact sau un scenariu când vom analiza jurnalul, nu te loga“.

Acestea fiind spuse, cum putem introduce în siguranță jurnalizarea atunci când este absolut necesar? Cum ar trebui să ne structurăm jurnalele și să le formatăm conținutul? Ce informații sunt necesare pentru a include în jurnale?

Urâtul

Acestea sunt primul tip de jurnale pe care vreau să le descriu și sunt, de asemenea, cele pe care le găsesc cel mai puțin frecvent. (Dacă le găsim prea des, s-ar putea să avem probleme mai mari în sistemele noastre!)

„Urâtul” este genul de jurnal în scenarii catastrofale sau neașteptate care necesită acțiuni imediate (cum ar fi erorile catastrofale care necesită repornirea aplicației). Putem argumenta că, în aceste condiții, este mai logic să folosiți instrumente de alertă precum Sentry.

Cu toate acestea, un jurnal de erori ar putea fi în continuare util pentru a ne oferi mai mult context în jurul acestor erori care nu sunt disponibile în urmărirea stivei lor. Dar ar putea ajuta la reproducerea acestor erori, cum ar fi intrările utilizatorului.

La fel ca erorile pe care le însoțesc, aceste jurnale ar trebui menținute la minimum în codul nostru și plasate într-o singură locație. Acestea ar trebui, de asemenea, să fie proiectate / documentate în specificații ca un comportament de sistem necesar pentru gestionarea erorilor. De asemenea, acestea ar trebui să fie țesute în codul sursă în jurul locului în care are loc tratarea erorilor.

În timp ce formatul și nivelul pentru jurnalele „Urâte” sunt complet preferențiale de la echipă la echipă, aș recomanda utilizarea log.error sau log.fatal înainte de o închidere grațioasă și repornirea aplicației. De asemenea, ar trebui să atașați urmărirea completă a stivei de erori și funcția sau datele de intrare ale solicitărilor pentru reproducere, dacă este necesar.

Răul

„Rău” este tipul de jurnale care abordează erorile așteptate, gestionate, cum ar fi problemele de rețea și validarea intrărilor utilizatorului. Acest tip de jurnal necesită atenția dezvoltatorilor numai dacă există o anomalie cu ei.

Împreună cu un monitor configurat pentru a alerta dezvoltatorii cu privire la o eroare, aceste jurnale sunt la îndemână pentru a atenua potențialele probleme de infrastructură sau de securitate.

Acest tip de jurnal ar trebui să fie specificat și în interiorul cerințelor tehnice de gestionare a erorilor și poate fi de fapt inclus dacă gestionăm erori așteptate și neașteptate în aceeași locație de cod.

Pe baza naturii a ceea ce fac „vizibile” pentru dezvoltatori, log.warn sau log.error poate fi folosit pentru jurnalele „Rău”, având în vedere convenția unei echipe.

Binele

Nu în ultimul rând, „Bunul” este tipul de jurnal care ar trebui să apară cel mai adesea în codul nostru sursă – dar este adesea cel mai dificil de corectat. Jurnalele „Bine” sunt cele asociate cu pașii „fericiți” ai aplicațiilor noastre, indicând succesul operațiunilor.

Chiar pentru natura sa de a indica operațiuni de pornire / execuție reușite în sistemul nostru, „The Good” este adesea abuzat de dezvoltatorii care sunt seduși de mantra „Doar încă un pic de date în jurnal, s-ar putea să avem nevoie de ele”.

Din nou, m-aș întoarce la prima noastră regulă de înregistrare: „Nu vă conectați decât dacă trebuie absolut”. Pentru a preveni apariția acestui tip de supra-exploatare, ar trebui să documentăm „Bunul” ca parte a cerințelor noastre tehnice, care completează logica principală de afaceri.

În plus, pentru fiecare dintre jurnalele „Bine” care se află în specificațiile noastre tehnice, trebuie să treacă testul de turnesol: există circumstanțe în care ne-am uita la jurnal (fie că este o cerere de asistență pentru clienți, o anchetă a unui auditor extern)? Doar așa va fi log.info să nu fie o moștenire temută care ascunde viziunea dezvoltatorilor în aplicațiile noastre.

Restul (Ce trebuie să știți)

Până acum presupun că ați observat că tema generală a strategiei mele de înregistrare propuse se învârte în jurul documentării clare și specifice a scopului jurnalului. Este important să tratăm înregistrarea ca parte a cerințelor noastre și să fim specifici cu privire la cuvintele cheie și mesajele pe care dorim să le etichetăm în contextul fiecărui jurnal pentru ca acestea să fie indexate în mod eficient.

Doar făcând asta putem fi conștienți de fiecare jurnal pe care îl producem și, la rândul său, putem avea o viziune clară asupra sistemelor noastre.

Deoarece jurnalele sunt actualizate la cetățeni de primă clasă cu cerințe tehnice concrete în specificațiile noastre, implicațiile sunt că acestea ar trebui să fie:

  • menținută și actualizată pe măsură ce evoluează cerințele tehnice și de afaceri
  • acoperite de teste unitare și de integrare

S-ar putea să pară multă muncă suplimentară pentru a ne corecta jurnalele. Cu toate acestea, susțin că acesta este genul de atenție și eforturi pe care le merită, astfel încât să poată fi util.

Serviți-ne buștenii și vom fi recompensați splendid!

Un ghid practic de migrație

Cred că nu este utilă o nouă strategie de înregistrare (sau alte strategii / cadre în acest sens) pentru proiectele vechi, dacă nu există nicio modalitate de a le muta din starea lor dezordonată la idealul propus.

Așadar, am un plan general în trei pași pentru oricine este frustrat de jurnalele sistemului și este dispus să investească timpul pentru a se conecta mai eficient.

Identificați suspecții obișnuiți

Deoarece ideea este de a reduce jurnalele de gunoi, primul nostru pas este să identificăm unde se ascund infractorii. Cu editorii de text puternici și IDE-urile pe care le avem în zilele noastre (sau grep dacă citiți acest lucru în trecut printr-o fereastră către viitor), toate aparițiile înregistrării pot fi ușor identificate.

Un document (sau o foaie de calcul dacă doriți să fiți organizat) care să documenteze toate aceste apariții de înregistrare poate fi necesar dacă există prea multe dintre acestea.

Condamnați-i pe actori răi!

După identificarea tuturor suspecților, este timpul să scoatem merele rele. Jurnalele duplicate sau inaccesibile sunt fructe cu agățare redusă pe care le putem elimina imediat din codul nostru sursă.

Pentru restul evenimentelor noastre de înregistrare, este timpul să implicăm alți factori interesați, cum ar fi inginerul „inițial” care a început proiectul (dacă este posibil), manageri de produse, asistență pentru clienți sau oameni de conformitate pentru a răspunde la întrebarea: Avem nevoie de fiecare dintre aceste jurnale și, dacă da, pentru ce sunt folosite?

Lumina la capătul tunelului

Acum că avem o listă restrânsă de jurnale absolut necesare, transformarea lor în cerințe tehnice cu scop documentat pentru fiecare dintre ele este esențială pentru a încheia un contract (sau îl putem numi specificație) pentru subsistemul nostru de înregistrare. Întrebați-vă ce să faceți când a log.error și cine suntem noi log.info-cum pentru?

După aceasta, este doar o chestiune de disciplină în același mod în care scriem și întreținem software-ul în general. Să lucrăm cu toții împreună și să facem exploatarea forestieră minunată!

Poti contactează-mă pe Twitter cu orice întrebări sau comentarii.