logging revision 2aee8fb2cbb1d4b77ea05327340e839e26265ae9
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThe ISC logging system is designed to provide a flexible, extensible
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmethod of writing messages. Messages can be sent to the system's
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclogging facility, directly to a file, or into the bitbucket, usually
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncconfigured per the desires of the users of the program. Each message
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncis associated with a particular category (eg, "security" or
e64031e20c39650a7bc902a3e1aba613b9415deevboxsync"database") that reflects its nature, and a particular module (such as
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthe library's source file) that reflects its origin. Messages are
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncalso each assigned a priority level which states how remarkable the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmessage is, so that too can be configured by the program's user to
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynccontrol how much detail is desired.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncLibraries which use the ISC logging system can be linked against each
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncother without fear of conflict. A program is able to select which, if
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncany, libraries will write log messages.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncFUNDAMENTALS
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThis section describes the basics of how the system works, introduces
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncterms and defines C preprocessor symbols used in conjuction with
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclogging functions. Actual uses of functions are demonstrated in the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncfollowing two sections.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncLog messages are associated with three pieces of information that are
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncused to determine their disposition: a category, a module, and a
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclevel (aka "priority").
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncA category describes the conceptual nature of the message, that is,
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncwhat general aspect of the code it is concerned with. For example,
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthe DNS library defines categories that include the workings of the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncdatabase as well security issues. Macros for naming categories are
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynctypically provided in the library's log header file, such as
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncDNS_LOGCATEGORY_DATABASE and DNS_LOGCATEGORY_SECURITY in <dns/log.h>
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncfor the two categories in the previous sentence. The special category
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncISC_LOGCATEGORY_DEFAULT is associated with any message that does not
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmatch a particular category (or matches a category but not a module,
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncas seen in the next paragraph).
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncA module is loosely the origin of a message. Though there not be a
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncone-to-one correspondence of source files with modules, it is typical
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthat a module's name reflect the source file in which it is used. So,
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncfor example, the module identifier DNS_LOGMODULE_RBT would be used by
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmessages coming from within the dns/rbt.c source file.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThe specification of the combination of a category and a module for a
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmessage are called the message's "category/module pair".
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThe level of a message is an indication of its severity. There are
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncsix standard logging levels, in order here from most to least severe
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync(least to most common):
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsync ISC_LOG_CRITICAL -- An error so severe it causes the program to exit.
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsync ISC_LOG_ERROR -- A very notable error, but the program can go on.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync ISC_LOG_WARNING -- Something is probably not as it should be.
5cf075f1173d07b89c26db295070415dffc6109dvboxsync ISC_LOG_NOTICE -- Notable events that occur while the program runs.
5cf075f1173d07b89c26db295070415dffc6109dvboxsync ISC_LOG_INFO -- Statistics, typically.
5cf075f1173d07b89c26db295070415dffc6109dvboxsyncand finally:
5cf075f1173d07b89c26db295070415dffc6109dvboxsync ISC_LOG_DEBUG(unsigned int level) -- detailed debugging messages.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncISC_LOG_DEBUG is not quite like the others in that it takes an
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncargument the defines roughly how detailed the message is; a higher
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsynclevel means more copious detail, so that values near 0 would be used
75863a3e9de2e8c46a1c1f6e32c2518622a41410vboxsyncat places like the entry to major sections of code, while greater
5cf075f1173d07b89c26db295070415dffc6109dvboxsyncnumbers would be used inside loops.
5cf075f1173d07b89c26db295070415dffc6109dvboxsyncSo, ok, technically there are five + at least 4,294,967,296 levels.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncPicky picky. In any event, the six levels correspond with similar
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclevels used by Unix's syslog, and when messages using one of those
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclevels is sent to syslog, the equivalent syslog level is used. (Note
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthat this means that any debugging messages go to the singular
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncLOG_DEBUG priority in syslog, regardless of their level internal to
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthe ISC logging system.)
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThe next building block of the logging system is a channel. A channel
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncspecifies where a message of a particular priority level should go, as
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncwell as any special options for that destination. There are four
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncbasic destinations, as follows:
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_TOSYSLOG -- Send it to syslog.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_TOFILE -- Write to a file.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_TOFILEDESC -- Write to a (previously opened) file descriptor.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_TONULL -- Do not write the message when selected.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncA file destination names a path to a log file. It also specifies the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmaximum allowable byte size of the file before it is closed (where 0
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmeans no limit) and the number of versions of a file to keep (where
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncISC_LOG_ROLLNEVER means the logging system never renames the log file,
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncand ISC_LOG_ROLLINFINITE means no cap on the number of versions).
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncVersion control is done just before a file is opened, so a program
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthat used it would start with a fresh log file (unless using
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncISC_LOG_ROLLNEVER) each time it ran. If you want to use an external
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncrolling method, use ISC_LOG_ROLLNEVER and ensure that your program has
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynca mechanism for calling isc_log_closefilelogs().
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync(ISC_LOG_ROLLINFINITE is not truly infinite; it will stop at INT_MAX.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncOn 32 bit machines that means the logs would need to roll once per
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncsecond for more than sixty years before exhausting the version number
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsyncA file descriptor destination is simply associated with a previously
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncopened stdio file descriptor. This is mostly used for associating
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncstdout or stderr with log messages, but could also be used, for
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncexample, to send logging messages down a pipe that has been opened by
2e6dc32bcc9c3a3e70c957764c033b1f402bc617vboxsyncthe program. File descriptor destinations are never closed, have no
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmaximum size limit, and do not do version control.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncSyslog destinations are associated with the standard syslog facilities
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncavailable on your system. They too have no maximum size limit and do
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncno version control.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncSince null channels go nowhere, no additional destination
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsyncspecification is necessary.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThe words "destination" and "channel" can be used interchangably in
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncsome contexts. Referring to a file channel, for example, means a
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncchannel that has a file destination.
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsyncChannels have string names that are their primary external reference.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThere are four predefined logging channels:
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync "default_stderr" -- Descriptor channel to stderr at priority ISC_LOG_INFO
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync "default_debug" -- Descriptor channel to stderr at priority ISC_LOG_DYNAMIC
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync "default_syslog" -- Syslog channel to LOG_DAEMON at priority ISC_LOG_INFO
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsync "null" -- Null channel
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsyncWhat's ISC_LOG_DYNAMIC? That's how you tell the logging system that
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncyou want debugging messages, but only at the current debugging level
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncof the program. The debugging level is controlled as described near
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthe end of the next section. When the debugging level is 0 (turned
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncoff), then no debugging messages are written to the channel. If the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncdebugging level is raised, only debugging messages up to its level are
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncwritten to the channel.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncYou can reuse a channel name. If you define a channel with the same
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncname as an existing channel, the new definition is used by all future
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncreferences to the name. The old definition is still used by anything
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthat was pointing to the name before the redefinition. This even
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncapplies to redefinitions of the predefined channels, with one
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncexception: redefining default_stderr will change the default
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncdestination of messages, as explained in more detail in a few paragraphs.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncChannels can additionally have any of four options associated with
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncthem. The following options are listed in the order which their
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynccorresponding print strings appear in a log message:
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_PRINTTIME -- The date and time.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_PRINTCATEGORY -- The category name.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_PRINTMODULE -- The module name.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync ISC_LOG_PRINTLEVEL -- The level.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncSyslog channels do not need ISC_LOG_PRINTTIME, but it is usally a good
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncidea for file and file descriptor feeds.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncNow with these objects -- the category, module, and channel -- you can
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncactually direct messages to your desired destinations. As shown in
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncthe next section, you associate the category/module pair with a
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncchannel. It is possible to use one function call to say "all modules
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynccoupled with this category" and vice versa, but conceptually the
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncmatching is still referred to as applying to category/module pairs,
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncsince that is what comes in from functions writing messages.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncSpeaking of functions writing messages, here's what happens when a
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncfunction wants to write a message through the logging system. First
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncthe function calls isc_log_write(), specifying a category, module and
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncIn isc_log_write(), the logging system first looks up a list that
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncconsists of all of the channels associated with a particular category.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncIt walks down the list looking for each channel that also has the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncindicated module associated with it, and writes the message to each
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncchannel it encounters. If no match is found in the list for the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmodule, the default channel is used. Similarly, the default is used
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncif no channels have been specified for the category at all.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncWhat is the default? It is ISC_LOGCATEGORY_DEFAULT -- sort of. You
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsynccan specify an association of the channel ISC_LOGCATEGORY_DEFAULT with
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncany particular module, or more usually all of them, and that's what
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsyncwill be used for any category/module pair for which you have not
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncspecified a channel. If you do not associate ISC_LOGCATGORY_DEFAULT
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncand the indicated module, then the internal default of using the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncdefault_stderr channel is used. This brings us back to the statement
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmade a few paragraphs ago about redefining the predefined channels --
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncif you redefine default_stderr, and a messages comes in for a
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynccategory/module pair that has had neither its original pair or
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthe ISC_LOGCATEGORY_DEFAULT/module pair configured for it, then the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmessage will go to the _new_ definition of default_stderr.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncHere are some other ways to think about how category/module pairs get
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncmatched with regard to using the defaults:
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync If a channel is is specified for a category as applying to all modules
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync which use that category, then the default channel will be used for no
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync combination of that category with any module.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync If a category is specified with one or more explicit modules, any
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync modules _not_ using that category still use the default.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncAs with the BIND 8 logging code, when a log message is not written
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncbecause the of the severity level of the channel, the default is _not_
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncused, because the category and module are considered to have matched.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncThe default is only used when a category/module pair has not been
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncspecified. If you want to use the default for some messages but also
46936038e727128ddeb7122eb50e16f2c8b0645evboxsyncsend higher (lower?) priority messages someplace else, then you will
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncneed to specify both the default channel and a custom channel for that
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncIt is important to note that specifying a null destination for a
e6a86a4d338a624268b412775d5a8921143274d6vboxsynccategory/module pair has no effect on any other destinations
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncassociated with that pair, regardless of ordering. For example,
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncthough it seems reasonable, you cannot say "for category A and all
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncmodules, log to stderr, but for category A and module 2 don't show any
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncmessages." You would need to specify stderr for category A with all
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncmodules except module 2, and then specify null for A/2. This could be
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncinconvenient, especially if you do not know all of the modules
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncassociated with a particular category but you know the one you want to
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncshut up. Because of this, it is likely that specifying a null
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncdestination _will_ block other channels that also specify a particular
e6a86a4d338a624268b412775d5a8921143274d6vboxsynccategory/module pair, but the exact mechanism has not yet been
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncNo attempt is made to filter out duplicate destinations, so it is
e6a86a4d338a624268b412775d5a8921143274d6vboxsynccertainly possible to define things such that a single log gets more
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncthan one copy of the same message. This may change in the future.
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncFinally, here is a note about multiprocessing. The entire logging
e6a86a4d338a624268b412775d5a8921143274d6vboxsynccontext is pthread locked for most of duration of the isc_log_write.
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncThat's it, that's the note.
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncUSING LIBRARIES THAT USE THE LOGGING SYSTEM
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncTo enable the messages from a library that uses the logging system,
e6a86a4d338a624268b412775d5a8921143274d6vboxsyncthe following steps need to be taken to initialize it.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync1) Include the main logging header file as well as the logging header
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncfile for any additional library you are using. For example, when
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncusing the DNS library, include the following:
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync2) Initialize a logging context. A logging context needs a valid
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncmemory context in order to work, so the following code snippet shows a
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncrudimentary initialization of both.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_mem_t *mctx;
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_log_t *lctx;
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync if (isc_mem_create(0, 0, &mctx) != ISC_R_SUCCESS) ||
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_log_create(mctx, &lctx) != ISC_R_SUCCESS))
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync oops_it_didnt_work();
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync3) Initalize any additional libraries. The convention for the name of
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncthe initialization function is {library}_log_init, with just a pointer
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncto the logging context as an argument. The function can only be
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynccalled once in a program or it will generate an assertion error.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync dns_log_init(lctx);
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncIf you do not want a library to write any log messages, simply do not
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynccall its the initialization function.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync4) Create any channels you want in addition to the internal channels
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncof default_syslog, default_stderr, default_debug and null. A
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncdestination structure needs to be filled for any destination other
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncthan null. The following examples show use of a file log, a file
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncdescriptor log, and syslog.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_logdestination_t destination;
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync destination.file.maximum_size = 0; /* No byte limit. */
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync destination.file.versions = ISC_LOG_ROLLNEVER; /* External rolling. */
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync if (isc_log_createchannel(lctx, "sample1" ISC_LOG_TOFILE, ISC_LOG_DYNAMIC,
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync &destination, ISC_LOG_PRINTTIME) != ISC_R_SUCCESS)
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync oops_it_didnt_work();
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync if (isc_log_createchannel(lctx, "sample2" ISC_LOG_TOFILEDESC, ISC_LOG_INFO,
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync &destination, ISC_LOG_PRINTTIME) != ISC_R_SUCCESS)
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync oops_it_didnt_work();
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync if (isc_log_createchannel(lctx, "sample2" ISC_LOG_SYSLOG, ISC_LOG_ERROR,
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync &destination, 0) != ISC_R_SUCCESS)
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync oops_it_didnt_work();
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncNote that ISC_LOG_DYNAMIC is used to define a channel that wants any
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncof the messages up to the current debugging level of the program
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync(described below). ISC_LOG_DEBUG(level) can define a channel that
2e6dc32bcc9c3a3e70c957764c033b1f402bc617vboxsync_always_ gets messages up to the debug level specified, regardless of
2e6dc32bcc9c3a3e70c957764c033b1f402bc617vboxsyncthe debugging state of the server.
75863a3e9de2e8c46a1c1f6e32c2518622a41410vboxsyncRemember that you can redefine these internal channels, and that in
ad27e1d5e48ca41245120c331cc88b50464813cevboxsyncparticular redefining default_stderr will change the default logging
75863a3e9de2e8c46a1c1f6e32c2518622a41410vboxsync5) Direct the various log categories and modules to the desired
75863a3e9de2e8c46a1c1f6e32c2518622a41410vboxsyncdestination. This step is not necessary if the normal behavior of
75863a3e9de2e8c46a1c1f6e32c2518622a41410vboxsyncsending all messages to default_stderr is acceptable. The following
92c51a0051e45b58014df65bfb90615eb718ffa7vboxsyncexamples sends DNS security messages to stderr, DNS database messages
92c51a0051e45b58014df65bfb90615eb718ffa7vboxsyncto null, and all other messages to syslog.
75863a3e9de2e8c46a1c1f6e32c2518622a41410vboxsync if (isc_log_usechannel(lctx, "default_stderr", DNS_LOGCATEGORY_SECURITY,
75863a3e9de2e8c46a1c1f6e32c2518622a41410vboxsync NULL) != ISC_R_SUCCESS)
2e6dc32bcc9c3a3e70c957764c033b1f402bc617vboxsync oops_it_didnt_work();
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync if (isc_log_usechannel(lctx, "null", DNS_LOGCATEGORY_DATABASE, NULL)
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync != ISC_R_SUCCESS)
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync oops_it_didnt_work();
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync if (isc_log_usechannel(lctx, "default_syslog", ISC_LOGCATEGORY_DEFAULT,
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync NULL) != ISC_R_SUCCESS)
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync oops_it_didnt_work();
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncProviding a NULL argument for the category means "associate the
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncchannel with the indicated module in all known categories" ---
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncincluding ISC_CATEGORY_DEFAULT. Providing a NULL argument for the
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncmodule means "associate the channel with all modules that use this
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync6) If you are sending any messages to syslog, call
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncisc_log_opensyslog(). Currently the arguments to this function are
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncexactly the same as to syslog's openlog() function, but it is expected
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncthat this will change. This is necessary
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsync isc_log_opensyslog(NULL, LOG_PID, LOG_DAEMON);
2fd23abb6f9e4d687f636f3e62e707e822aaadd6vboxsyncNow the libraries used by your program will write messages according
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncto your specifications.
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncThere are three additional functions you might find useful in your
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncprogram to control logging behavior, two to work with the debugging
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsynclevel and one to control the closing of log files.
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncvoid isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level) and
2fd23abb6f9e4d687f636f3e62e707e822aaadd6vboxsyncunsigned int isc_log_getdebuglevel(isc_log_t *lctx) set and retrieve
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsyncthe current debugging level of the program. isc_log_getdebuglevel()
81b3101ea5e60964f67c97185bbd43dbf75c5ab5vboxsynccan be used so that you need not keep track of the level yourself in
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncanother variable. One use for these functions would be in a daemon
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncthat could have its debugging level raised with a USR1 signal or lowered
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncwith a USR2 signal.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncThe void isc_log_closefilelogs(isc_log_t *lcxt) function closes any
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncopen log files. This is useful for programs that do not want to do
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncfile rotation as with the internal rolling mechanism. For example, a
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncprogram that wanted to keep daily logs would define a channel which
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncused ISC_LOG_ROLLNEVER, then once a day would rename the log file and
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynccall isc_log_closefilelogs(). The next time a message needs to be
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncwritten a file that has been closed, it is reopened.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncWRITING LIBRARIES THAT USE THE LOGGING SYSTEM
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncThis section describes how a new library, libfoo.a, would use the ISC
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynclogging system internally.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync1) Provide a header file that does the following:
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync * declares foo_lctx, a logging context that will be used throughout
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync the library.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync * declares the structures that specify the categories and modules
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync known by the library.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync * defines the macros that provide convenient access to the library's
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync categories and modules.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync * prototypes the library's log initialization function.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync See <dns/log.h> for a sample.
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync2) Write a C source module that includes the library's log.h,
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync provides storage for the library's logging context,
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync initializes the category and module structures, and defines the
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync initialization function, foo_log_init(). log.c from libdns.a looks
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync like this (trimmed down):
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_logcategory_t dns_categories[] = {
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync { "dns_general: ", 0 },
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync { "dns_database: ", 0 },
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync { "dns_security: ", 0 },
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync { NULL, 0 }
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_logmodule_t dns_modules[] = {
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync { "db: ", 0 },
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync { "rbtdb: ", 0 },
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync { NULL, 0 }
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_log_t *dns_lctx;
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync dns_result_t
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync dns_log_init(isc_log_t *lctx) {
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_result_t result;
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync REQUIRE(dns_lctx == NULL);
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync result = isc_log_registercategories(lctx, dns_categories);
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync if (result == ISC_R_SUCCESS) {
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync isc_log_registermodules(lctx, dns_modules);
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync dns_lctx = lctx;
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsync return (result);
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncNote that the init function is what associates that library's logging
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynccontext with the one that the calling program must create and
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncinitialize. If the init function is never called, the library's
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsynclogging context will be NULL, so any calls by other library functions
9f99c4dd20c44a6b4a532fd7370168f392ea6375vboxsyncto log messages will simply return with no message being written.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync3) Use the isc_log_write() function to have messages written according
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncto the definitions in the logging context. Its arguments are the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclogging context, a category, a module, a logging level, a printf(3)
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncformat string, and any additional arguments that are necessary for the
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsyncformat string. For example:
9f52ff8b6b89d6ac4215d122a95b685170a5a382vboxsync isc_log_write(dns_lctx, DNS_LOGCATEGORY_GENERAL, DNS_LOGMODULE_RBT,
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync ISC_LOG_CRITICAL, "%s",
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsync "Node %d in red-black tree is crimson!", node);
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncNo newline should be included, nor should the program name. Usually
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthe source file name or the function name should not be included
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynceither, since location information can be attained, if desired, with
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncISC_LOG_PRINTMODULE. On rare occasion it might be necessary to
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncdifferentiate very similar messages in the same module.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncWhen available, include standard library return codes via %s in the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncformat string, with strerrr(errno) from the system libary or functions
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclike isc_result_totext(result) and dns_result_totext(result).
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncTHINGS I AM NOT KEEN ABOUT
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncThe category/module names passed into the registration functions need
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncto have a colon-space (": ") at the end of each name.
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncI am not happy that using a null channel for a category/module pair
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynchas no effect on other associations with that pair. It seems to me
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthat it would be nice to say "send all DATABASE category messages to
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncsyslog, except for those from the RBT base code." I am not sure of
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynchow I want it specified though. One way to do it is to simply say
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsyncthat null overrides any previously defined matches for the
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynccategory/module, so that internally when walking down the channel
e0e0c19eefceaf5d4ec40f9466b58a771f50e799vboxsynclist, the first category/module match to a null channel stops