44. Errorlog

Auteur Marc Jeurissen
Aanmaak 18 juni 2008
Oud BVV nr 2231

44.1. Abstract

errorlog is een toolcat-applicatie die allerlei loggings kan verzamelen en via e-mail bijeenbrengen in een roundup issue tracker.

44.2. Delphi-waarden

errorlog-main-dir
De rootdirectory voor alle errorlog identifiers.
errorlog-mailbox
De mailbox waar de berichten naartoe gestuurd worden (bijvoorbeeld errorlog@lib.ua.ac.be). Deze user moet aangemaakt worden op de mailserver.
errorlog-db
Het path van de issue tracker waar de berichten terecht komen. Deze tracker moet aangemaakt worden volgens de informatie in /roundup/application/faq.txt.
errorlog-account
Een username:password combinatie waarmee de errorlog-mailbox kan bevraagd worden.

44.3. Installaties

  • Een roundup issue tracker (zie /roundup/application/faq.txt).
  • Een errorlog-user op de mailserver.

44.4. Workflow

44.4.1. Identifiers

errorlog werkt met identifiers die geconcretiseerd worden door directories in registry.errorlog_main_dir. Elk commando heeft dan ook zo’n identifier als eerste argument. De werkomgeving van een identifier wordt vastgelegd in subdirectories van registry.errorlog_main_dir/identifier (Zie errorlog -create).

44.4.2. Berichten verzamelen

Er zijn 2 manieren om errorlogs te verzamelen:

  • Een reeds bestaande pool kan op regelmatige tijdstippen overlopen worden met errorlog -collect, bijvoorbeeld mumps-fouten. Daarvoor dient een identifier-collector te bestaan, identifier.py, die, vertrekkend van een bepaalde positie, de nieuwe errorberichten verzamelt (Zie errorlog -collect). De laatste positie wordt bijgehouden in registry.errorlog_main_dir/identifier/position en kan altijd aangepast worden via errorlog -mode.
  • Via errorlog -message kan een applicatie onmiddellijk een errorbericht uitsturen (Zie errorlog -message), altijd in de context van een bepaalde identifier.

44.4.3. Beslissingsregels

Een errorlog-identifier beschikt over een combinatie van 2 parameters om te beslissen of een bericht moet doorgestuurd worden naar de errorlog, namelijk hoeveel keer (threshold) is hetzelfde bericht reeds gerapporteerd binnen een bepaalde tijdsspanne (aantal dagen timespan). Beide parameters worden gezet via errorlog -mode en worden bijgehouden in registry.errorlog_main_dir/identifier/threshold en registry.errorlog_main_dir/identifier/timespan.

timespan ligt vast voor elke identifier, de identifier threshold kan per bericht overschreven worden.

Dubbele berichten worden herkend door een checkstring die door de collector of het errorlog -message commando aan een bericht wordt toegekend. Van deze checkstring wordt een md5 berekend die, per dag, opgeslagen worden in registry.errorlog_main_dir/identifier/check.

44.4.4. Keywords

Aan elk te verzenden bericht kunnen keywords toegekend worden (zie errorlog -message) die in de errortracker ook moeten gekend zijn. De verzameling van alle reeds toegekende keywords voor een bepaalde identifier, staat in registry.errorlog_main_dir/identifier/active/keywords. Aan de hand hiervan beslist het systeem of er een commando (= extra e-mail) naar de errortracker moet gestuurd worden voor aanmaak van een nieuw keyword. Deze verzameling kan bewerkt worden via errorlog -mode.

Een keyword moet beginnen met registry.system_name-errorlogidentifier-, dit om groepering in de errortracker te vergemakkelijken. Indien dit niet het geval is, wordt dit prefix er door het systeem voorgeplakt. Indien er geen keyword wordt meegegeven geeft het systeem standaard keyword registry.system_name-errorlogidentifier mee. Bovendien wordt elk - deel omgezet in lowercase met eerste letter in uppercase.

44.4.5. Berichten verzenden

Te verzenden berichten staan in registry.errorlog_main_dir/identifier/messages (objecten) en registry.errorlog_main_dir/identifier/send (tekstversie) en worden verstuurd naar registry.errorlog_mailbox. (Zie errorlog -message en errorlog -send).

44.4.6. Berichten opslaan

websu errorlog -retrieve start het commando roundup-mailgw registry.errorlog_db pop registry.errorlog_account:registry.mailserver op en plaatst de berichten in de errortracker.

Waarschuwing

websu is belangrijk om de juiste owner en group properties te hebben in de tracker omgeving.

44.5. Interface

44.5.1. Identifier aanmaken

Commando

errorlog -create identifier [active=yes|no] [position=x] [threshold=n] [timespan=n]

Verklaring

De omgeving van een nieuwe identifier wordt aangemaakt door middel van een directory structuur onder registry.errorlog_main_dir/identifier.

  • active: bevat alle parameterbestanden
  • check: bevat, per dag, een lijst van reeds verzonden berichten (md5 van de checkstring van de berichten)
  • error
  • log
  • messages: message-objecten van te verzenden berichten
  • send: tekstversie van te verzenden berichten

Een nieuwe identifier kan ook aangemaakt worden via errorlog -message *identifier* *message* create=yes.

Modifiers:

active
yes | no
File registry.errorlog_main_dir/identifier/active/inactive wordt aangemaakt.
position
Positie waarvan de volgende errorlog -collect start.
Wordt bijgehouden in file registry.errorlog_main_dir/identifier/active/position.
threshold
Aantal keer dat een bericht moet voorkomen binnen een tijdsspanne, bepaald door modifier timespan, vooraleer het verstuurd wordt. Dit is een globale waarde voor de identifier die door elk bericht afzonderlijk kan overschreven worden (default=1).
timespan
Tijdsspanne in aantal dagen waarbinnen de thresholds gelden (default=1).

44.5.2. Parameters wijzigen

Commando

errorlog -mode identifier [active=yes|no] [lock=yes|no] [position=x] [keyword=x] [threshold=n] [timespan=n]

Verklaring

Dit commando verandert een aantal parameters die oorspronkelijk door errorlog -create gezet zijn. Indien standaard modifier verbose=yes worden de huidige parameterwaarden uitgeprint.

Modifiers:

active
yes | no
File registry.errorlog_main_dir/identifier/active/inactive wordt aangemaakt.
lock
Bij het opstarten van errorlog -collect identifier wordt identifier gelockt door het plaatsen van file registry.errorlog_main_dir/identifier/active/lock. Moest de unlock om een of andere reden mislukt zijn dan kan dit met lock=no manueel uitgevoerd worden.
keyword

Hiermee kan de verzameling keywords van deze identifier onderhouden worden. In principe is dit enkel nodig bij onregelmatigheden of testen, omdat er anders discrepanties kunnen ontstaan met de door de errortracker gekende trefwoorden. De waarde van deze modifier is een door komma’s gescheiden string van trefwoorden, eventueel voorafgegaan door -. In dat laatste geval wordt het desbetreffende trefwoord geschrapt.

Notitie

Aan elk keyword wordt het prefix registry.system_name-errorlogidentifier- toegevoegd indien niet aanwezig (Zie ook Workflow > Keywords).

position
Positie waarvan de volgende errorlog -collect start.
Wordt bijgehouden in file registry.errorlog_main_dir/identifier/active/position.
threshold
Aantal keer dat een bericht moet voorkomen binnen een tijdsspanne, bepaald door modifier timespan, vooraleer het verstuurd wordt. Dit is een globale waarde voor de identifier die door elk bericht afzonderlijk kan overschreven worden.
timespan
Tijdsspanne in aantal dagen waarbinnen de thresholds gelden.

44.5.3. Bericht klaar zetten voor verzending [en versturen]

Commando

errorlog -message identifier messagestring | filepath [check=x] [send=yes|no] [title=x] [keyword=x] [threshold=n] [create=yes|no]

Verklaring

Dit commando prepareert een bericht voor verzending en, afhankelijk van de waarde van modifier send, stuurt het effectief door naar registry.errorlog_mailbox.

Het bericht in kwestie wordt meegegeven in het 2 e argument en kan een string zijn of een pathnaam van een bestand waarvan de inhoud dient gelezen te worden.

Modifiers:

check
String die gebruikt wordt voor detectie van dubbele berichten (Zie Workflow > Beslissingsregels).
Als check leeg is, wordt modifier title als checkstring genomen.
send
yes = bericht wordt direct verzonden
no = bericht wordt enkel klaar gezet en nadien verzonden met errorlog -send.
title
Titel van het bericht.
Wordt geplaatst in de subject header van het e-mail bericht.
keyword

Door komma’s gescheiden string van trefwoorden.

Notitie

Aan elk keyword wordt het prefix registry.system_name-errorlogidentifier- toegevoegd indien niet aanwezig (Zie ook Workflow > Keywords).

threshold
Aantal keer dat dit bericht moet voorkomen binnen een tijdsspanne, bepaald door errorlogidentifier timespan, vooraleer het verstuurd wordt.
Indien niet gespecificeerd, wordt de standaardwaarde van de errorlogidentifier genomen.
create
yes = indien de omgeving voor de errorlogidentifier nog niet bestaat, wordt ze gecreëerd met defaultwaarden voor de parameters.
Eventuele aanpassingen aan de parameters dienen te gebeuren met errorlog -mode.

44.5.4. Berichten verzenden

Commando

errorlog -send identifier [messageidentifier[,messageidentifier,...]]

Verklaring

Alle klaarstaande berichten of de in het 2 e argument opgegeven berichten worden verzonden naar registry.errorlog_mailbox.

Wachtende berichten staan in directory registry.errorlog_main_dir/identifier/messages en een messageidentifier is gewoon de filenaam.

errorlog -send construeert de door roundup tracker vereiste subject-header syntax en beslist of er extra e-mails moeten uitgestuurd worden voor de aanmaak van keywords.

Dit commando wordt intern ook aangeproken door errorlog -collect en errorlog -message send=yes.

44.5.5. Berichten verzamelen

Commando

errorlog -collect [identifier] [daemon=yes|no]

Verklaring

Sommige foutboodschappen worden al verzameld, bijvoorbeeld mumps softwarefouten, apache errorlog. Om deze pools te overlopen kan errorlog -collect gebruikt worden.

Het commando vertrekt vanaf een bepaalde positie die door de vorige run of door errorlog -mode identifier position=x werd vastgelegd.

Er moet een routine /errorlog/application/identifier.py bestaan met een generator collect(position) die de identifier-specifieke errorlog overloopt en een tuple (position, messagebody, messagetitle, keywords, checkstring, messagethreshold) teruggeeft.

keywords, checkstring en messagethreshold kunnen leeg zijn en worden dan ingevuld met de respectievelijke defaultwaarden registry.system_name-errorlogidentifier, messagetitle, identifier-threshold.

Modifiers:

daemon
yes = proces wordt opgestart als daemon | no (default)

44.5.6. Berichten in errorlog tracker plaatsen

Commando

errorlog -retrieve

Verklaring

Dit commando maakt gebruik van de roundup mailgateway script om via pop de registry.errorlog_mailbox leeg te lezen en de berichten in de errorlog tracker te plaatsen.

Waarschuwing

Gebruik altijd websu errorlog -retrieve om de juiste owner en group properties te hebben in de tracker omgeving!

roundup-mailgw registry.errorlog_main_dir/errorlog pop registry.errorlog_account@registry.mailserver