.\" Copyright (c) 2022 Stijn van Dongen
.TH "tingea\&.log" 7 "9 Oct 2022" "tingea\&.log 22-282" "MISCELLANEOUS "
.po 2m
.de ZI
.\" Zoem Indent/Itemize macro I.
.br
'in +\\$1
.nr xa 0
.nr xa -\\$1
.nr xb \\$1
.nr xb -\\w'\\$2'
\h'|\\n(xau'\\$2\h'\\n(xbu'\\
..
.de ZJ
.br
.\" Zoem Indent/Itemize macro II.
'in +\\$1
'in +\\$2
.nr xa 0
.nr xa -\\$2
.nr xa -\\w'\\$3'
.nr xb \\$2
\h'|\\n(xau'\\$3\h'\\n(xbu'\\
..
.if n .ll -2m
.am SH
.ie n .in 4m
.el .in 8m
..
.SH NAME
tingea\&.log \- How to set the Tingea log parameters
.SH 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 \fB-q\fP\&.
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 \fB-q\fP type option is present and the environment variable
is set, then the environment variable is interpreted first followed
by the \fB-q\fP 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 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\&.

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\&.

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\&.
.SH SYNTAX
The syntax of the TINGEA_LOG_TAG environment variable is described by

.di ZV
.in 0
.nf \fC
   [[189x]]{<[dfgimpstABC][1-9]>*,[V]}
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

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

.di ZV
.in 0
.nf \fC
   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    |
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

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

.di ZV
.in 0
.nf \fC
   1     d1f1m1g1i1p1s1t1A1B1C1     # very yappy
   9     d3f4m5gxixpxsxtxAxBxCx     # very terse, only d f m
   8     d3f4m5g1i1p1s1t1A1B1C1     # less terse
   x     dxfxmxgxixpxsxtxAxBxCx     # silent
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

All categories accept values between \fC1\fP and \fC9\fP in addition to the
value \fCx\fP\&. 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 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\&.
.SH AUTHOR
Stijn van Dongen\&.