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 isnt 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/zo
  om 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 will be 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 ) ltlt items ltlt endmsg
• severity level
• error id (a string)
• additional items
• anything you can ltlt 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
• _at_SUBRname 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-gt 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 wont 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) ltlt
  endmsg
• See BasicColl / BasicRecv example