4.4. The <logs> section

The logs section contains <log> elements at arbitrary depths. A log requires several attributes to be useful:

name

"name" this must me unique. Several names have meaning within the product. If you match that name, you control how that information is logged.

type

"type" this specified ths underlying log writing implementation. Valid options are "file" (the default if unspecified), "jlog" which is the a binary 'auto-rotating', consumable, multi-subscriber log format.

path

"path" the path to the log (interpreted by the "type" implementation).

debug

"debug" (boolean: <true|false>, default false) that dictates whether or not the file:line number of the callee will be included in the log output. This only applies loggers that have write operations (like files and jlogs).

disabled

"disabled" (boolean: <true|false>, default false) that dictates whether the log implmenation will actually write anything. If set to true, the log will be silences and will not propagate input to any attached outlets.

timestamps

"debug" (boolean: <true|false>, default false) that dictates whether or not a microsecond granular time will be included in the log output. This only applies loggers that have write operations (like files and jlogs).

rotate_seconds

"rotate_seconds" (integer: default unset, minimum 600) that specifies how many seconds of data the given log file should contain. Every "rotate_seconds" seconds (aligned with UNIX epoch), the log will be rotated to a file of the same name with the current UNIX timestamp dot-appended. This can be used in combination with "rotate_bytes" for rather interesting results.

rotate_bytes

"rotate_bytes" (integer: default unset, minimum 102400) that specifies the maximum number of bytes the file may contain before rotation is applied. This is not enforced after each write, but instead the file size is monitored "frequently" and rotation applied. This can mean that the file can grow slightly larger than the specified amount. This can be used in combination with "rotate_seconds" for rather interesting results.

Within a <log> element, zero, one or many <outlet> elements may be present. The outlet element must contain a "name" attribute (this attribute is not inherited) that matches a *previously* declared <log> by its "name" attribute. Foreach <outlet> tag, a sink is created so that any input sent to the containing <log> will additionally be propagated to the <outlet>.

There is an implicit log named "stderr" that is attached to file descriptor 2 that has timestamps enabled.

4.4.1. Special log names

stderr

opened to file descriptor two during log initialization.

error

destination for error messages.

debug

destination for debugging output.

check

When a check is altered in any way (including creation), the identifying attributes, including the uuid, are logged to this facility.

   'C' TIMESTAMP UUID TARGET MODULE NAME
   

status

When a check status changes (either availability or state) and neither the new state nor the old state are "unknown", it is considered a state change for the check. The new availability and new state are logged to this facility.

   'S' TIMESTAMP UUID STATE AVAILABILITY DURATION STATUS_MESSAGE
   

metrics

Each time a check is completed, the various metrics that were observed by the check are logged to this facility. The VALUE is always a string or [[null]] (never binary encoded/packed). The TYPE indicates the datatype the check intended when it was observed.

   'M' TIMESTAMP UUID NAME TYPE VALUE
   

NAME

is the name of the metric and the encouraged format for this is "name`subname`subsubname`etc"

TYPE
i

INT32

I

UINT32

l

INT64

L

UINT64

n

DOUBLE

s

STRING

Example 4.4. Sample configuration for the log section

  <logs>
    <console>
      <outlet name="stderr" />
      <log name="error" />
      <log name="debug" disabled="true" />
    </console>
    <log name="feed" type="jlog" path="/var/log/noitd.feed" />
    <feeds>
      <outlet name="feed" />
      <log name="check" />
      <log name="metrics" />
      <log name="status">
        <outlet name="error" />
      </log>
    </feeds>
  </logs>

In the above example:

  • a <console> metagroup is created for the purpose of inheriting the "stderr" outlet. The logs named "error" and "debug" are instantiated and inherit the "stderr" outlet. However, "debug" is disabled, so no input to the "debug" log will be written anywhere.

  • a log named "feed" is created of type "jlog" writing to the "/var/log/noitd.feed" directory (jlogs paths are directories, whereas "file" paths are filenames).

  • a <feeds> metagroup is created for the purpose of inheriting the "feed" outlet. The logs "check," "metrics," and "status" are instantiated and will log via the "feed" outlet (all writing to the same jlog). Additionally, the "status" feed is given an additional outlet named "error" so we will see inputs to status in both the "feed" jlog and on the console ("stderr").