tingea.log(7)							  MISCELLANEOUS 						     tingea.log(7)

  NAME
      tingea.log - How to set the Tingea log parameters

  DESCRIPTION
      The  Tingea  logging framework is part of the Tingea library.  In this context logging means that a pgrogram issues statements about what it
      is doing. It can do so for different purposes and at different levels of verbosity. By default logging statements are written on STDERR.

      Tingea logging provides a quick and easy way for programmers to associate verbosity levels with logging statements.  Only logging statements
      for which the verbosity level does not exceed the user-imposed threshold will be executed.  Users can easily regulate the verbosity level by
      setting the environment variable TINGEA_LOG_TAG.	Alternatively, programs may accept a command line argument.  The format accepted  by  both
      environment  variable  and command line argument is identical.  For the command line the programmer is free in choosing the option name.	It
      is customarily named -q.	The availability of such an option may vary from program to program.  However, any program that makes use  of  the
      Tingea logging facilities can be regulated with the TINGEA_LOG_TAG environment variable.	If a -q type option is present and the environment
      variable is set, then the environment variable is interpreted first followed by the -q argument.

      Tingea logging allows a programmer to assign categories to logging statements. The categories FUNCTION and DATA have a  subdivision  ranging
      from fine-grained to coarse-grained. The categorie MONITORING has a subdivision ranging from low priority to high priority.  The other cate-
      gories are unimodal. These are IO, THREAD, PROCESS, and GAUGE. Three unspecified unimodal categories are SLOT1, SLOT2, and SLOT3.  They  can
      be used to encode program-specific semantics.

      The  programmer  may  assign multiple categories to a single logging statement.  It is unusual for more than two categories to be specified.
      For example, IO and DATA at the LIST level may be combined to indicate a logging statement that provides data summaries  for  a  certain	IO
      related information. In order of granularity the DATA levels are CELL, LIST, and AGGREGRATE. If the user accepts IO logging and accepts DATA
      logging at level CELL or LIST the statement will be executed. If no IO logging is accepted or DATA logging is only accepted  at  the  AGGRE-
      GRATE level, the statement will be skipped.

      By  default,  all  categories  that are specified by the programmer need to pass the threshold specified by the user for that category.  The
      user may relax this requirement so that only one category needs to pass the user threshold. In the above example, the statement  categorized
      as both IO and DATA at LIST level will be accepted if the user specifies IO and DATA at AGGR level with OR semantics.

  SYNTAX
      The syntax of the TINGEA_LOG_TAG environment variable is described by

	 [[189x]]{<[dfgimpstABC][1-9]>*,[V]}

      which  translates to the following. An optional lead tag is followed by a concatenation of units. A unit is either a pair in [dfgimpstABC] x
      [1-9x] or the single character V.  The leading tag semantics are described further below.  The single character  V,  if  present,  specifies
      that OR semantics should be used rather than the default AND semantics. The semantics for the other units are given below.

	 d     DATA
		  1  CELL
		  2  LIST
		  3  AGGR
		  x  turned off

	 f     FUNCTION
		  1  LINE
		  2  FUNCTION
		  3  MODULE
		  4  APPLICATION
		  x  turned off

	 m     MONITORING
		  1  DEBUG
		  2  INFO
		  3  WARNING
		  4  ERROR
		  5  PANIC
		  x  turned off

	 g     GAUGE	|
	 i     IO	|
	 n     NETWORK	|
	 p     PROCESS	|  (Inter Process really)
	 t     THREAD	|______  1 on
			|	 x off
	 A     SLOT1	|
	 B     SLOT2	|
	 C     SLOT3	|

      The  leading  tag  can be used to set levels for all categories at once.	Subsequent units may then alter this intial setting.  The lead tag
      settings and their meaning are these:

	 1     d1f1m1g1i1p1s1t1A1B1C1	  # very yappy
	 9     d3f4m5gxixpxsxtxAxBxCx	  # very terse, only d f m
	 8     d3f4m5g1i1p1s1t1A1B1C1	  # less terse
	 x     dxfxmxgxixpxsxtxAxBxCx	  # silent

      All categories accept values between 1 and 9 in addition to the value x. As seen above, only a few categories contain more  than	one  level
      and no category contains more than five levels.  The rule is that if a level exceeds the maximul level available for a category it is simply
      interpreted as the maximum level.

      The GAUGE category, if set, indicates that a program may write line based progress bars or other output in which a single  line  is  accumu-
      lated  over  multiple  statements.  This	implies that a single GAUGE logging statement may not result in newline-terminated output. This is
      undesirable in case the logging stream is directed to a file that is written to by other applications as well. In that case, turn off GAUGE.
      All other categories are garantueed to result in line-terminated output, by virtue of the programmer contract.

  AUTHOR
      Stijn van Dongen.

  tingea.log 12-068						      8 Mar 2012						       tingea.log(7)