7fd0120946822608dcfd6967ce427df472768ed4mikloshCopyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")

7fd0120946822608dcfd6967ce427df472768ed4mikloshCopyright (C) 1999-2001 Internet Software Consortium.

7fd0120946822608dcfd6967ce427df472768ed4mikloshSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4miklosh$Id: logging,v 1.10 2004/03/05 05:04:46 marka Exp $

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshOVERVIEW

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshThe ISC logging system is designed to provide a flexible, extensible

7fd0120946822608dcfd6967ce427df472768ed4mikloshmethod of writing messages. Messages can be sent to the system's

7fd0120946822608dcfd6967ce427df472768ed4mikloshlogging facility, directly to a file, or into the bitbucket, usually

7fd0120946822608dcfd6967ce427df472768ed4mikloshconfigured per the desires of the users of the program. Each message

7fd0120946822608dcfd6967ce427df472768ed4mikloshis associated with a particular category (eg, "security" or

7fd0120946822608dcfd6967ce427df472768ed4miklosh"database") that reflects its nature, and a particular module (such as

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe library's source file) that reflects its origin. Messages are

7fd0120946822608dcfd6967ce427df472768ed4mikloshalso each assigned a priority level which states how remarkable the

7fd0120946822608dcfd6967ce427df472768ed4mikloshmessage is, so that too can be configured by the program's user to

7fd0120946822608dcfd6967ce427df472768ed4mikloshcontrol how much detail is desired.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshLibraries which use the ISC logging system can be linked against each

7fd0120946822608dcfd6967ce427df472768ed4mikloshother without fear of conflict. A program is able to select which, if

7fd0120946822608dcfd6967ce427df472768ed4mikloshany, libraries will write log messages.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshFUNDAMENTALS

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshThis section describes the basics of how the system works, introduces

7fd0120946822608dcfd6967ce427df472768ed4mikloshterms and defines C preprocessor symbols used in conjuction with

7fd0120946822608dcfd6967ce427df472768ed4mikloshlogging functions. Actual uses of functions are demonstrated in the

7fd0120946822608dcfd6967ce427df472768ed4mikloshfollowing two sections.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshLog messages are associated with three pieces of information that are

7fd0120946822608dcfd6967ce427df472768ed4mikloshused to determine their disposition: a category, a module, and a

7fd0120946822608dcfd6967ce427df472768ed4mikloshlevel (aka "priority").

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshA category describes the conceptual nature of the message, that is,

7fd0120946822608dcfd6967ce427df472768ed4mikloshwhat general aspect of the code it is concerned with. For example,

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe DNS library defines categories that include the workings of the

7fd0120946822608dcfd6967ce427df472768ed4mikloshdatabase as well security issues. Macros for naming categories are

7fd0120946822608dcfd6967ce427df472768ed4mikloshtypically provided in the library's log header file, such as

7fd0120946822608dcfd6967ce427df472768ed4mikloshDNS_LOGCATEGORY_DATABASE and DNS_LOGCATEGORY_SECURITY in <dns/log.h>

7fd0120946822608dcfd6967ce427df472768ed4mikloshfor the two categories in the previous sentence. The special category

7fd0120946822608dcfd6967ce427df472768ed4mikloshISC_LOGCATEGORY_DEFAULT is associated with any message that does not

7fd0120946822608dcfd6967ce427df472768ed4mikloshmatch a particular category (or matches a category but not a module,

7fd0120946822608dcfd6967ce427df472768ed4mikloshas seen in the next paragraph).

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshA module is loosely the origin of a message. Though there not be a

7fd0120946822608dcfd6967ce427df472768ed4mikloshone-to-one correspondence of source files with modules, it is typical

7fd0120946822608dcfd6967ce427df472768ed4mikloshthat a module's name reflect the source file in which it is used. So,

7fd0120946822608dcfd6967ce427df472768ed4mikloshfor example, the module identifier DNS_LOGMODULE_RBT would be used by

7fd0120946822608dcfd6967ce427df472768ed4mikloshmessages coming from within the dns/rbt.c source file.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshThe specification of the combination of a category and a module for a

7fd0120946822608dcfd6967ce427df472768ed4mikloshmessage are called the message's "category/module pair".

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshThe level of a message is an indication of its severity. There are

7fd0120946822608dcfd6967ce427df472768ed4mikloshsix standard logging levels, in order here from most to least severe

7fd0120946822608dcfd6967ce427df472768ed4miklosh(least to most common):

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_CRITICAL -- An error so severe it causes the program to exit.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_ERROR -- A very notable error, but the program can go on.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_WARNING -- Something is probably not as it should be.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_NOTICE -- Notable events that occur while the program runs.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_INFO -- Statistics, typically.

7fd0120946822608dcfd6967ce427df472768ed4mikloshand finally:

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_DEBUG(unsigned int level) -- detailed debugging messages.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshISC_LOG_DEBUG is not quite like the others in that it takes an

7fd0120946822608dcfd6967ce427df472768ed4mikloshargument the defines roughly how detailed the message is; a higher

7fd0120946822608dcfd6967ce427df472768ed4mikloshlevel means more copious detail, so that values near 0 would be used

7fd0120946822608dcfd6967ce427df472768ed4mikloshat places like the entry to major sections of code, while greater

7fd0120946822608dcfd6967ce427df472768ed4mikloshnumbers would be used inside loops.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshSo, ok, technically there are five + at least 4,294,967,296 levels.

7fd0120946822608dcfd6967ce427df472768ed4mikloshPicky picky. In any event, the six levels correspond with similar

7fd0120946822608dcfd6967ce427df472768ed4mikloshlevels used by Unix's syslog, and when messages using one of those

7fd0120946822608dcfd6967ce427df472768ed4mikloshlevels is sent to syslog, the equivalent syslog level is used. (Note

7fd0120946822608dcfd6967ce427df472768ed4mikloshthat this means that any debugging messages go to the singular

7fd0120946822608dcfd6967ce427df472768ed4mikloshLOG_DEBUG priority in syslog, regardless of their level internal to

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe ISC logging system.)

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshThe next building block of the logging system is a channel. A channel

7fd0120946822608dcfd6967ce427df472768ed4mikloshspecifies where a message of a particular priority level should go, as

7fd0120946822608dcfd6967ce427df472768ed4mikloshwell as any special options for that destination. There are four

7fd0120946822608dcfd6967ce427df472768ed4mikloshbasic destinations, as follows:

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_TOSYSLOG -- Send it to syslog.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_TOFILE -- Write to a file.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_TOFILEDESC -- Write to a (previously opened) file descriptor.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_TONULL -- Do not write the message when selected.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshA file destination names a path to a log file. It also specifies the

7fd0120946822608dcfd6967ce427df472768ed4mikloshmaximum allowable byte size of the file before it is closed (where 0

7fd0120946822608dcfd6967ce427df472768ed4mikloshmeans no limit) and the number of versions of a file to keep (where

7fd0120946822608dcfd6967ce427df472768ed4mikloshISC_LOG_ROLLNEVER means the logging system never renames the log file,

7fd0120946822608dcfd6967ce427df472768ed4mikloshand ISC_LOG_ROLLINFINITE means no cap on the number of versions).

7fd0120946822608dcfd6967ce427df472768ed4mikloshVersion control is done just before a file is opened, so a program

7fd0120946822608dcfd6967ce427df472768ed4mikloshthat used it would start with a fresh log file (unless using

7fd0120946822608dcfd6967ce427df472768ed4mikloshISC_LOG_ROLLNEVER) each time it ran. If you want to use an external

7fd0120946822608dcfd6967ce427df472768ed4mikloshrolling method, use ISC_LOG_ROLLNEVER and ensure that your program has

7fd0120946822608dcfd6967ce427df472768ed4miklosha mechanism for calling isc_log_closefilelogs().

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4miklosh(ISC_LOG_ROLLINFINITE is not truly infinite; it will stop at INT_MAX.

7fd0120946822608dcfd6967ce427df472768ed4mikloshOn 32 bit machines that means the logs would need to roll once per

7fd0120946822608dcfd6967ce427df472768ed4mikloshsecond for more than sixty years before exhausting the version number

7fd0120946822608dcfd6967ce427df472768ed4mikloshspace.)

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshA file descriptor destination is simply associated with a previously

7fd0120946822608dcfd6967ce427df472768ed4mikloshopened stdio file descriptor. This is mostly used for associating

7fd0120946822608dcfd6967ce427df472768ed4mikloshstdout or stderr with log messages, but could also be used, for

7fd0120946822608dcfd6967ce427df472768ed4mikloshexample, to send logging messages down a pipe that has been opened by

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe program. File descriptor destinations are never closed, have no

7fd0120946822608dcfd6967ce427df472768ed4mikloshmaximum size limit, and do not do version control.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshSyslog destinations are associated with the standard syslog facilities

7fd0120946822608dcfd6967ce427df472768ed4mikloshavailable on your system. They too have no maximum size limit and do

7fd0120946822608dcfd6967ce427df472768ed4mikloshno version control.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshSince null channels go nowhere, no additional destination

7fd0120946822608dcfd6967ce427df472768ed4mikloshspecification is necessary.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshThe words "destination" and "channel" can be used interchangably in

7fd0120946822608dcfd6967ce427df472768ed4mikloshsome contexts. Referring to a file channel, for example, means a

7fd0120946822608dcfd6967ce427df472768ed4mikloshchannel that has a file destination.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshChannels have string names that are their primary external reference.

7fd0120946822608dcfd6967ce427df472768ed4mikloshThere are four predefined logging channels:

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4miklosh "default_stderr" -- Descriptor channel to stderr at priority ISC_LOG_INFO

7fd0120946822608dcfd6967ce427df472768ed4miklosh "default_debug" -- Descriptor channel to stderr at priority ISC_LOG_DYNAMIC

7fd0120946822608dcfd6967ce427df472768ed4miklosh "default_syslog" -- Syslog channel to LOG_DAEMON at priority ISC_LOG_INFO

7fd0120946822608dcfd6967ce427df472768ed4miklosh "null" -- Null channel

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshWhat's ISC_LOG_DYNAMIC? That's how you tell the logging system that

7fd0120946822608dcfd6967ce427df472768ed4mikloshyou want debugging messages, but only at the current debugging level

7fd0120946822608dcfd6967ce427df472768ed4mikloshof the program. The debugging level is controlled as described near

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe end of the next section. When the debugging level is 0 (turned

7fd0120946822608dcfd6967ce427df472768ed4mikloshoff), then no debugging messages are written to the channel. If the

7fd0120946822608dcfd6967ce427df472768ed4mikloshdebugging level is raised, only debugging messages up to its level are

7fd0120946822608dcfd6967ce427df472768ed4mikloshwritten to the channel.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshYou can reuse a channel name. If you define a channel with the same

7fd0120946822608dcfd6967ce427df472768ed4mikloshname as an existing channel, the new definition is used by all future

7fd0120946822608dcfd6967ce427df472768ed4mikloshreferences to the name. The old definition is still used by anything

7fd0120946822608dcfd6967ce427df472768ed4mikloshthat was pointing to the name before the redefinition. This even

7fd0120946822608dcfd6967ce427df472768ed4mikloshapplies to redefinitions of the predefined channels, with one

7fd0120946822608dcfd6967ce427df472768ed4mikloshexception: redefining default_stderr will change the default

7fd0120946822608dcfd6967ce427df472768ed4mikloshdestination of messages, as explained in more detail in a few paragraphs.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshChannels can additionally have any of five options associated with

7fd0120946822608dcfd6967ce427df472768ed4mikloshthem. The following options are listed in the order which their

7fd0120946822608dcfd6967ce427df472768ed4mikloshcorresponding print strings appear in a log message:

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_PRINTTIME -- The date and time.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_PRINTCATEGORY -- The category name.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_PRINTMODULE -- The module name.

7fd0120946822608dcfd6967ce427df472768ed4miklosh ISC_LOG_PRINTLEVEL -- The level.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshYou can set all four of those options with ISC_LOG_PRINTALL.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshSyslog channels do not need ISC_LOG_PRINTTIME, but it is usally a good

7fd0120946822608dcfd6967ce427df472768ed4mikloshidea for file and file descriptor feeds.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshThe additional option does not affect formatting. It is

7fd0120946822608dcfd6967ce427df472768ed4mikloshISC_LOG_DEBUGONLY, and marks a channel as only being eligible for

7fd0120946822608dcfd6967ce427df472768ed4mikloshmessages when the debugging level is non-zero. It acts like the

7fd0120946822608dcfd6967ce427df472768ed4mikloshnull channel when the debugging level is zero.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshNow with these objects -- the category, module, and channel -- you can

7fd0120946822608dcfd6967ce427df472768ed4mikloshactually direct messages to your desired destinations. As shown in

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe next section, you associate the category/module pair with a

7fd0120946822608dcfd6967ce427df472768ed4mikloshchannel. It is possible to use one function call to say "all modules

7fd0120946822608dcfd6967ce427df472768ed4mikloshcoupled with this category" and vice versa, but conceptually the

7fd0120946822608dcfd6967ce427df472768ed4mikloshmatching is still referred to as applying to category/module pairs,

7fd0120946822608dcfd6967ce427df472768ed4mikloshsince that is what comes in from functions writing messages.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshSpeaking of functions writing messages, here's what happens when a

7fd0120946822608dcfd6967ce427df472768ed4mikloshfunction wants to write a message through the logging system. First

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe function calls isc_log_write(), specifying a category, module and

7fd0120946822608dcfd6967ce427df472768ed4mikloshlevel.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshIn isc_log_write(), the logging system first looks up a list that

7fd0120946822608dcfd6967ce427df472768ed4mikloshconsists of all of the channels associated with a particular category.

7fd0120946822608dcfd6967ce427df472768ed4mikloshIt walks down the list looking for each channel that also has the

7fd0120946822608dcfd6967ce427df472768ed4mikloshindicated module associated with it, and writes the message to each

7fd0120946822608dcfd6967ce427df472768ed4mikloshchannel it encounters. If no match is found in the list for the

7fd0120946822608dcfd6967ce427df472768ed4mikloshmodule, the default channel is used. Similarly, the default is used

7fd0120946822608dcfd6967ce427df472768ed4mikloshif no channels have been specified for the category at all.

7fd0120946822608dcfd6967ce427df472768ed4miklosh

7fd0120946822608dcfd6967ce427df472768ed4mikloshWhat is the default? It is ISC_LOGCATEGORY_DEFAULT -- sort of. You

7fd0120946822608dcfd6967ce427df472768ed4mikloshcan specify an association of the channel ISC_LOGCATEGORY_DEFAULT with

7fd0120946822608dcfd6967ce427df472768ed4mikloshany particular module, or more usually all of them, and that's what

7fd0120946822608dcfd6967ce427df472768ed4mikloshwill be used for any category/module pair for which you have not

7fd0120946822608dcfd6967ce427df472768ed4mikloshspecified a channel. If you do not associate ISC_LOGCATGORY_DEFAULT

7fd0120946822608dcfd6967ce427df472768ed4mikloshand the indicated module, then the internal default of using the

7fd0120946822608dcfd6967ce427df472768ed4mikloshdefault_stderr channel is used. This brings us back to the statement

7fd0120946822608dcfd6967ce427df472768ed4mikloshmade a few paragraphs ago about redefining the predefined channels --

7fd0120946822608dcfd6967ce427df472768ed4mikloshif you redefine default_stderr, and a messages comes in for a

7fd0120946822608dcfd6967ce427df472768ed4mikloshcategory/module pair that has had neither its original pair or

7fd0120946822608dcfd6967ce427df472768ed4mikloshthe ISC_LOGCATEGORY_DEFAULT/module pair configured for it, then the

message will go to the _new_ definition of default_stderr.

Here are some other ways to think about how category/module pairs get

matched with regard to using the defaults:

If a channel is is specified for a category as applying to all modules

which use that category, then the default channel will be used for no

combination of that category with any module.

If a category is specified with one or more explicit modules, any

modules _not_ using that category still use the default.

As with the BIND 8 logging code, when a log message is not written

because the of the severity level of the channel, the default is _not_

used, because the category and module are considered to have matched.

The default is only used when a category/module pair has not been

specified. If you want to use the default for some messages but also

send higher (lower?) priority messages someplace else, then you will

need to specify both the default channel and a custom channel for that

category/module pair.

It is important to note that specifying a null destination for a

category/module pair has no effect on any other destinations

associated with that pair, regardless of ordering. For example,

though it seems reasonable, you cannot say "for category A and all

modules, log to stderr, but for category A and module 2 don't show any

messages." You would need to specify stderr for category A with all

modules except module 2, and then specify null for A/2. This could be

inconvenient, especially if you do not know all of the modules

associated with a particular category but you know the one you want to

shut up. Because of this, it is likely that specifying a null

destination _will_ block other channels that also specify a particular

category/module pair, but the exact mechanism has not yet been

determined.

No attempt is made to filter out duplicate destinations, so it is

certainly possible to define things such that a single log gets more

than one copy of the same message. This may change in the future.

EXTERNALLY VISIBLE STRUCTURE

Two of the fundamental types used by programs for configuring log

message destinations are isc_log_t and isc_logconfig_t. The isc_log_t

type is normally created only once by a program, to hold the (relatively)

static information about what categories and modules exist in the program

and some other housekeeping information. isc_logconfig_t is used to

store the configurable specification of message destinations, which

can be changed during the course of the program.

A starting configuration (isc_logconfig_t) is created implicitly when

the context (isc_log_t) is created. The pointer to this configuration

is returned via a parameter to isc_log_create so that it can then be

configurated. A new configuration can be established by creating

it with isc_logconfig_create, configuring it, then installing it as

the active configuration with isc_logconfig_use.

MULTITHREADED PROGRAMS

The entire logging context is thread locked for most of duration of

the isc_log_write. However, isc_log_write does avoid the delays

caused by locking when it is clear that there are no possible outputs

for a message based on its debugging level --- this is so that a

program can have debugging messages sprinkled liberally throughout it

but not incur any locking penalty when debugging is not enabled.

The logging context is locked when a new configuration is installed

by isc_logconfig_use.

USING LIBRARIES THAT USE THE LOGGING SYSTEM

To enable the messages from a library that uses the logging system,

the following steps need to be taken to initialize it.

1) Include the main logging header file as well as the logging header

file for any additional library you are using. For example, when

using the DNS library, include the following:

#include <isc/log.h>

#include <dns/log.h>

2) Initialize a logging context. A logging context needs a valid

memory context in order to work, so the following code snippet shows a

rudimentary initialization of both.

isc_mem_t *mctx;

isc_log_t *lctx;

isc_logconfig_t *lcfg;

if (isc_mem_create(0, 0, &mctx) != ISC_R_SUCCESS) ||

isc_log_create(mctx, &lctx, &lcfg) != ISC_R_SUCCESS))

oops_it_didnt_work();

3) Initalize any additional libraries. The convention for the name of

the initialization function is {library}_log_init, with just a pointer

to the logging context as an argument. The function can only be

called once in a program or it will generate an assertion error.

dns_log_init(lctx);

If you do not want a library to write any log messages, simply do not

call its the initialization function.

4) Create any channels you want in addition to the internal channels

of default_syslog, default_stderr, default_debug and null. A

destination structure needs to be filled for any destination other

than null. The following examples show use of a file log, a file

descriptor log, and syslog.

isc_logdestination_t destination;

destination.file.name = "/var/log/example";

destination.file.maximum_size = 0; /* No byte limit. */

destination.file.versions = ISC_LOG_ROLLNEVER; /* External rolling. */

if (isc_log_createchannel(lcfg, "sample1" ISC_LOG_TOFILE, ISC_LOG_DYNAMIC,

&destination, ISC_LOG_PRINTTIME) != ISC_R_SUCCESS)

oops_it_didnt_work();

destination.file.stream = stdout;

if (isc_log_createchannel(lcfg, "sample2" ISC_LOG_TOFILEDESC, ISC_LOG_INFO,

&destination, ISC_LOG_PRINTTIME) != ISC_R_SUCCESS)

oops_it_didnt_work();

destination.facility = LOG_ERR;

if (isc_log_createchannel(lcfg, "sample3" ISC_LOG_SYSLOG, ISC_LOG_ERROR,

&destination, 0) != ISC_R_SUCCESS)

oops_it_didnt_work();

Note that ISC_LOG_DYNAMIC is used to define a channel that wants any

of the messages up to the current debugging level of the program

(described below). ISC_LOG_DEBUG(level) can define a channel that

_always_ gets messages up to the debug level specified, regardless of

the debugging state of the server.

Remember that you can redefine these internal channels, and that in

particular redefining default_stderr will change the default logging

method.

5) Direct the various log categories and modules to the desired

destination. This step is not necessary if the normal behavior of

sending all messages to default_stderr is acceptable. The following

examples sends DNS security messages to stderr, DNS database messages

to null, and all other messages to syslog.

if (isc_log_usechannel(lcfg, "default_stderr", DNS_LOGCATEGORY_SECURITY,

NULL) != ISC_R_SUCCESS)

oops_it_didnt_work();

if (isc_log_usechannel(lcfg, "null", DNS_LOGCATEGORY_DATABASE, NULL)

!= ISC_R_SUCCESS)

oops_it_didnt_work();

if (isc_log_usechannel(lcfg, "default_syslog", ISC_LOGCATEGORY_DEFAULT,

NULL) != ISC_R_SUCCESS)

oops_it_didnt_work();

Providing a NULL argument for the category means "associate the

channel with the indicated module in all known categories" ---

including ISC_CATEGORY_DEFAULT. Providing a NULL argument for the

module means "associate the channel with all modules that use this

category."

6) If you are sending any messages to syslog, call

isc_log_opensyslog(). Currently the arguments to this function are

exactly the same as to syslog's openlog() function, but it is expected

that this will change when the logging library is made to work with the

system logging facility on Windows NT.

isc_log_opensyslog(NULL, LOG_PID, LOG_DAEMON);

Now the libraries used by your program will write messages according

to your specifications.

7) If you want to swap in a new configuration to replace the existing

configuration, first create the new configuration with:

result = isc_logconfig_create(lctx, &newlcfg);

and then configure newlcfg with isc_log_createchannel() and

isc_log_usechannel(). When it is all ready:

result = isc_logconfig_use(lctx, newlcfg);

If the new configration is successfully installed, then the old one

will be destroyed, freeing all memory it used.

There are three additional functions you might find useful in your

program to control logging behavior, two to work with the debugging

level and one to control the closing of log files.

void isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level) and

unsigned int isc_log_getdebuglevel(isc_log_t *lctx) set and retrieve

the current debugging level of the program. isc_log_getdebuglevel()

can be used so that you need not keep track of the level yourself in

another variable. One use for these functions would be in a daemon

that could have its debugging level raised with a USR1 signal or lowered

with a USR2 signal.

The void isc_log_closefilelogs(isc_log_t *lcxt) function closes any

open log files. This is useful for programs that do not want to do

file rotation as with the internal rolling mechanism. For example, a

program that wanted to keep daily logs would define a channel which

used ISC_LOG_ROLLNEVER, then once a day would rename the log file and

call isc_log_closefilelogs(). The next time a message needs to be

written a file that has been closed, it is reopened.

WRITING LIBRARIES THAT USE THE LOGGING SYSTEM

This section describes how a new library, libfoo.a, would use the ISC

logging system internally.

1) Provide a header file that does the following:

* includes isc/log.h

* declares foo_lctx, a logging context that will be used throughout

the library.

* declares the structures that specify the categories and modules

known by the library.

* defines the macros that provide convenient access to the library's

categories and modules.

* prototypes the library's log initialization function.

See <dns/log.h> for a sample.

2) Write a C source module that includes the library's log.h,

provides storage for the library's logging context,

initializes the category and module structures, and defines the

initialization function, foo_log_init(). log.c from libdns.a looks

like this (trimmed down):

#include <isc/result.h>

#include <isc/log.h>

#include <dns/log.h>

isc_logcategory_t dns_categories[] = {

{ "dns_general", 0 },

{ "dns_database", 0 },

{ "dns_security", 0 },

{ NULL, 0 }

};

isc_logmodule_t dns_modules[] = {

{ "db", 0 },

{ "rbtdb", 0 },

{ NULL, 0 }

};

isc_log_t *dns_lctx;

dns_result_t

dns_log_init(isc_log_t *lctx) {

isc_result_t result;

REQUIRE(dns_lctx == NULL);

result = isc_log_registercategories(lctx, dns_categories);

if (result == ISC_R_SUCCESS) {

isc_log_registermodules(lctx, dns_modules);

dns_lctx = lctx;

}

return (result);

}

Note that the init function is what associates that library's logging

context with the one that the calling program must create and

initialize. If the init function is never called, the library's

logging context will be NULL, so any calls by other library functions

to log messages will simply return with no message being written.

3) Use the isc_log_write() function to have messages written according

to the definitions in the logging context. Its arguments are the

logging context, a category, a module, a logging level, a printf(3)

format string, and any additional arguments that are necessary for the

format string. For example:

isc_log_write(dns_lctx, DNS_LOGCATEGORY_GENERAL, DNS_LOGMODULE_RBT,

ISC_LOG_CRITICAL, "%s",

"Node %d in red-black tree is crimson!", node);

No newline should be included, nor should the program name. Usually

the source file name or the function name should not be included

either, since location information can be attained, if desired, with

ISC_LOG_PRINTMODULE. On rare occasion it might be necessary to

differentiate very similar messages in the same module.

When available, include standard library return codes via %s in the

format string, with strerrr(errno) from the system libary or functions

like isc_result_totext(result) and dns_result_totext(result).

THINGS I AM NOT KEEN ABOUT

I am not happy that using a null channel for a category/module pair

has no effect on other associations with that pair. It seems to me

that it would be nice to say "send all DATABASE category messages to

syslog, except for those from the RBT base code." I am not sure of

how I want it specified though. One way to do it is to simply say

that null overrides any previously defined matches for the

category/module, so that internally when walking down the channel

list, the first category/module match to a null channel stops

processing.