# The Hierarchical Log Library (`hlog`)

A program uses the hierarchical log library, `hlog`, to organize
its diagnostic messages into categories and subcategories and to
turn on and off message categories to produce the most useful
diagnostic trace.

A typical program will define one or more log *outlets*.  An outlet
is a named target for diagnostic messages.  Each outlet has a *state*
(*on*, *off*, or *pass*) and at most one *parent outlet*.  Usually, the
parent-child relationships between outlets form a tree rooted at the
outlet "all", which is supplied by the library.  Outlets may form a
"forest" if a program supplies its own root outlets.

A program sends messages to an outlet using `hlog` API calls.
Messages sent to an outlet that is *on* are copied to the error
stream.  Messages sent to an outlet that is *off* are discarded.
When a message is sent to an outlet in *pass* state, the `hlog`
uses the outlet ancestors to decide what to do with the message.

## Sending messages with `hlog_fast`
 
A program calls `hlog_fast(outlet name, format string, ...)` to
write a formatted message to the named outlet.  `hlog_fast` uses
the outlet state to do decide what to do with the message.  If the
outlet is *on*, then the message is written to the standard error
stream.  If the outlet is *off*, then the message is discarded.
If the outlet is in state *pass*, and the outlet has no parent,
then the message is discarded.  If the outlet does have a parent,
then `hlog_fast` looks at the parent state and decides whether to
discard, write, or recurse.

`hlog_fast` precedes each diagnostic message with a timestamp (decimal
seconds with 9 digits right of the decimal point), a colon, and a single
space.  Each message is followed with a newline ("\n").  The effective
timestamp resolution may be much less than one nanosecond.  Timestamps
increase monotonically.  The timestamp origin is currently unspecified.

## Defining log outlets

`hlog` provides macros for declaring outlets, and for statically
configuring an outlet, its parent, and its initial state.

Use `HLOG_OUTLET_DECL(name)` to declare shared outlets in header
files.  `HLOG_OUTLET_DECL(name)` declares an `extern` symbol.
There must not be any quotation marks on *name*.

Use `HLOG_OUTLET_SHORT_DEFN(name, parent)` to define an outlet with the
given name and parent in state *pass*.  There must not be any quotation
marks on *name*.

Use `HLOG_OUTLET_MEDIUM_DEFN(name, parent, state)` to define an outlet
with the given name, parent, and state.  The state is given by an
`hlog_outlet_state_t`, one of `HLOG_OUTLET_S_ON`, `HLOG_OUTLET_S_OFF`,
or `HLOG_OUTLET_S_PASS`.  There must not be any quotation marks on
*name*.

## Enabling and disabling outlets with the environment

An environment variable, `HLOG`, sets initial outlet states for a
program.  If `HLOG` may be set to the empty string, in which case
outlet states stay at their program defaults.  `HLOG` may also be
set to one or more *outlet name*=*state* pairs, separated by either
whitespace or commas. *state* is one of *pass*, *on*, or *off*,
and *outlet-name* is a string matching `[_a-zA-Z][_a-zA-Z0-9]*`.
For example, to enable the `tick` outlet and `pbrm` outlets while
the program `./vfd_swmr_zoo_writer` runs, you can use this command
in `csh` or Bourne shell:

```
env HLOG="tick=on pbrm=on" ./vfd_swmr_zoo_writer
```

# Implementation notes

`hlog_fast(outlet name, format string, ...)` is implemented as a
macro that only evaluates its format string or other arguments if
it decides to write the message to `stderr`.  `hlog_fast` avoids
repeatedly walking child-parent links by caching its decision to
write or discard in the named outlet.

# Future improvements

The timestamp origin is unspecified, now.  For the user's convenience,
the timestamp probably should be measured from `hlog` library
initialization.  Also, `hlog` should provide a routine for setting
the timestamp origin to the current time.