Design/debug_notes

   1                        Stem::Debug Design Notes
   2
   3 Stem modules have a need to report error conditions and trace critical
   4 events while being able to control when, where and how this information
   5 is presented.  The Stem::Debug module provides a way for any Stem module
   6 to create debug/trace subs customized to that module's needs.
   7 Stem::Debug delegates all of this backend filtering, formatting and
   8 distribution of these messages to the Stem::Log subsystem. In effect,
   9 Stem::Debug creates specialized front ends subs to Stem::Log.
  10
  11 Using Stem::Debug is very simple. A module just does a use Stem::Debug
  12 statement with optional key/value parameters. More than one use
  13 statement can be made in a module and each one will create a new debug sub
  14 inside that module's namespace. When you create this sub, you can select
  15 its name, which logical log the message goes to, and the label and severity
  16 levels. Also a command line argument name may be specified for filtering
  17 even before the log entry is generated.
  18
  19 The final design of the Stem::Debug is still in flux. It is not yet
  20 ready to be used by external developers.
  21
  22 This module is only used internally and should not be configured.