From 4dc315dfb78831a268bb1d66935c97e19c83a6f0 Mon Sep 17 00:00:00 2001 From: David Young Date: Tue, 14 Apr 2020 09:04:18 -0500 Subject: Document `hlog` a bit. --- doc/Diagnostic-Logging.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 doc/Diagnostic-Logging.md diff --git a/doc/Diagnostic-Logging.md b/doc/Diagnostic-Logging.md new file mode 100644 index 0000000..e71e737 --- /dev/null +++ b/doc/Diagnostic-Logging.md @@ -0,0 +1,88 @@ +# 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. + -- cgit v0.12