/usr/share/doc/mcl/html/tingea.log.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (c) 2014 Stijn van Dongen -->
<head>
<meta name="keywords" content="manual">
<style type="text/css">
/* START aephea.base.css */
body
{ text-align: justify;
margin-left: 0%;
margin-right: 0%;
}
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.verbatim
{ font-family: monospace;
margin-top: 1em;
margin-bottom: 1em;
font-size: 10pt;
margin-left: 2em;
white-space: pre;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
.right { text-align: right; }
.left { text-align: left; }
.nowrap { white-space: nowrap; }
.item_leader
{ position: relative;
margin-left: 8%;
}
.item_compact { position: absolute; vertical-align: baseline; }
.item_cascade { position: relative; }
.item_leftalign { text-align: left; }
.item_rightalign
{ width: 2em;
text-align: right;
}
.item_compact .item_rightalign
{ position: absolute;
width: 52em;
right: -2em;
text-align: right;
}
.item_text
{ position: relative;
margin-left: 3em;
}
.smallcaps { font-size: smaller; text-transform: uppercase }
/* END aephea.base.css */
body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
body
{ text-align: justify;
margin-left: 8%;
margin-right: 8%;
}
</style>
<title>How to set the Tingea log parameters</title>
</head>
<body>
<p style="text-align:right">
16 May 2014&nbsp;&nbsp;&nbsp;
<a class="local" href="tingea.log.ps"><b>tingea.log</b></a>
14-137
</p>

<a name="name"></a>
<h2>NAME</h2>
<p style="margin-bottom:0" class="asd_par">
tingea.log &mdash; How to set the Tingea log parameters</p>

<a name="description"></a>
<h2>DESCRIPTION</h2>
<p style="margin-top:0em; margin-bottom:0em">
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.</p>
<p style="margin-bottom:0" class="asd_par">
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 <b>-q</b>.
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 <b>-q</b> type option is present and the environment variable
is set, then the environment variable is interpreted first followed
by the <b>-q</b> argument.</p>
<p style="margin-bottom:0" class="asd_par">
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 categories 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.</p>
<p style="margin-bottom:0" class="asd_par">
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 AGGREGRATE level, the statement will be skipped.</p>
<p style="margin-bottom:0" class="asd_par">
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.</p>

<a name="syntax"></a>
<h2>SYNTAX</h2>
<p style="margin-top:0em; margin-bottom:0em">
The syntax of the TINGEA_LOG_TAG environment variable is described by</p>
<div class="verbatim">   [[189x]]{&lt;[dfgimpstABC][1-9]&gt;*,[V]}</div>
<p style="margin-top:0em; margin-bottom:0em">
which translates to the following. An optional lead tag is followed
by a concatenation of units. A unit is either a pair in
<tt>[dfgimpstABC] x [1-9x]</tt> or the single character <tt>V</tt>.
The leading tag semantics are described further below.
The single character <tt>V</tt>, if present, specifies that OR semantics
should be used rather than the default AND semantics. The semantics
for the other units are given below.</p>
<div class="verbatim">   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    |</div>
<p style="margin-top:0em; margin-bottom:0em">
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:</p>
<div class="verbatim">   1     d1f1m1g1i1p1s1t1A1B1C1     # very yappy
   9     d3f4m5gxixpxsxtxAxBxCx     # very terse, only d f m
   8     d3f4m5g1i1p1s1t1A1B1C1     # less terse
   x     dxfxmxgxixpxsxtxAxBxCx     # silent</div>
<p style="margin-top:0em; margin-bottom:0em">
All categories accept values between <tt>1</tt> and <tt>9</tt> in addition to the
value <tt>x</tt>. 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.</p>
<p style="margin-bottom:0" class="asd_par">
The GAUGE category, if set, indicates that a program may write line based
progress bars or other output in which a single line is accumulated 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.</p>

<a name="author"></a>
<h2>AUTHOR</h2>
<p style="margin-top:0em; margin-bottom:0em">
Stijn van Dongen.</p>
</body>
</html>
mcl-doc 1:14-137-1 / usr / share / doc / mcl / html / tingea.log.html
