


  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  associ-
      ate  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 set-
      ting the environment variable TINGEA_LOG_TAG.   Alternatively,  programs
      may  accept  a command line argument.  The format accepted by both envi-
      ronment variable and command line argument is identical.  For  the  com-
      mand  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 sub-
      division 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 state-
      ment.  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 AGGREGRATE  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]}




  tingea.log 1.008, 09-308    4 Nov 2009                          1





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


      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  set-
      tings 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  inter-
      preted as the maximum level.

      The  GAUGE  category,  if  set,  indicates that a program may write line



  tingea.log 1.008, 09-308    4 Nov 2009                          2





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


      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  undesir-
      able 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 1.008, 09-308    4 Nov 2009                          3


