Tutorial on use of the ErrorLogger Package

1. Tutorial on use of the ErrorLogger Package With introduction to setting up for “collective” error logging

2. Viewpoints • “User” – the bulk of the code writers • Will explain all the options • Because there isn’t that much to cover! • “Framework” – sets up behavior • There are loads of control options • destinations • thresholds and limits • Will explain the most important ones • Please excuse use of web page/code transparencies

3. Documentation resources • Web pages (from ZOOM page at ---www.fnal.gov/tf/zoom go to releases then ErrorLogger package • Examples in ErrorLogger/Test • BasicUsage • SampleFramework • BasicColl / BasicRecv

4. 3 Key Concepts • ErrorLogger • This is what the “user” sees and uses • Set up by the framework • Normally a global or package-level variable • Conventionally called errlog • Destination(s) • Eladminstrator

5. 3 Key Concepts • ErrorLogger • Destination(s) • Places where the logged output is to go • Can and normally willbe multiple destinations • ELoutput is the ordinary destination • Framework can set up multiple ELoutput dests, with different thresholds for logging messages etc. • ELstatistics is a special statistics-keeping destination • ELadminstrator

6. 3 Key Concepts • ErrorLogger • Destination(s) • ELadminstrator • Framework instantiates this once • “singleton” pattern is used – impossible to have two • Acts as a hook to control overall logging behavior

7. User • #include ErrorLogger/ErrorLog.h • probably done in framework, where errlog is made • Issuing messages • errlog ( severity, id ) << items << endmsg; • severity level • error id (a string) • additional items • anything you can << to an ostream is a valid item • multiple • endmsg • declares the end of a message • if this is omitted, next message will terminate anyway • web pages: How to & severity levels

8. User • setSubroutine(“name”); • Optional • Framework can set subroutine • subroutine name is not required • “@SUBR=name” item in message does the same thing • ERRLOG macro • same syntax as errlog • but inserts line number and file name into message • No other options to learn.

9. Framework • Instantiate an administrator • Make destination(s) • attach each destination to adminstrator • attaching returns a ELdestControl handle. • control thresholds and other destination properties using this handle • (See example)

10. Framework • Set up errlog for each module • by using a different ErrorLog instance, each module can have its name used in messages, incurring no overhead when no messages are issued • Provide Context Supplier • Optional, but normally done • Allows appending run/event number to issued messages, without incurring overhead when no message is issued. • Control abort behavior • logger-> setAbortThreshold (ELhighestSeverity) • Cause statistics destination to output statistics • example output • See SampleFramework example • fairly complete spectrum of what can be done

11. Framework • Thresholds and limits apply to each destination • Thresholds are severity levels, below which a distination won’t react to a message • Limits are by severity or message id for each destination, and can throttle the number of messages of that type displayed • logarithmic backoffs displaying past the limit • Context supplier is a function that returns a string to use when formatting needs a run/event context • logger.setContextSupplier( ELcontextSupplier s); • Follow the “mantra” in BasicFramework.cc example for how to set up the context supplier

12. Collective Error Logging • New ELcollected destination derived from ELouput • So code setting up output destinations needs no superfluous mods • ELcollected captures severity level, id, text of each item, context, module, subroutine • Forms a buffer “data” and supplies to send(nbytes, data) method of a user-supplied ELsender object. • Could have different senders for different ELcollected destinations • send(nbytes, data) must transport the data to the server Server must then do errlog (nbytes, data) << endmsg; • See BasicColl / BasicRecv example