|
@@ -121,10 +121,10 @@ logger. The top of the hierarchy is the root logger; this does not
|
|
|
have a parent. The reason for this hierarchy is that unless a logger
|
|
|
explicitly assigns a value to an attribute (such as severity of messages
|
|
|
it should log), it picks it up the value from the parent. In Kea,
|
|
|
-each component (b10-dhcp4, b10-dhcp-ddns etc.) has a root logger (named
|
|
|
+each component (kea-dhcp4, kea-dhcp-ddns etc.) has a root logger (named
|
|
|
after the program) and every other logger in the component is a child
|
|
|
of that. So in the example above, the error/syslog attributes could be
|
|
|
-associated with the b10-resolver logger while the logger associated with
|
|
|
+associated with the kea-resolver logger while the logger associated with
|
|
|
the cache sets its own values for the debug/file attributes.
|
|
|
|
|
|
More information about the logging hierarchy can be found in the section
|
|
@@ -177,11 +177,10 @@ compiling the message files of all Kea components and libraries.
|
|
|
|
|
|
For C++ development, the message compiler produces two files in the
|
|
|
default directory, having the same name as the input file but with file
|
|
|
-types of ".h" and ".cc". For Python, the message compiler will produce
|
|
|
-a Python module containing the symbols.</li>
|
|
|
+types of ".h" and ".cc".</li>
|
|
|
|
|
|
<li>Include the resultant files in your source code to define message symbols,
|
|
|
-and (for C++) compile the code and link it into your program.</li>
|
|
|
+and compile the code and link it into your program.</li>
|
|
|
|
|
|
<li>Declare loggers in your code and use them to log messages.</li>
|
|
|
|
|
@@ -351,17 +350,14 @@ programs.
|
|
|
The message compiler is a program built in the src/log/compiler directory.
|
|
|
It is invoked by the command:
|
|
|
@code
|
|
|
-message [-h] [-v] [-p] [-d dir] <message-file>
|
|
|
+message [-h] [-v] [-d dir] <message-file>
|
|
|
@endcode
|
|
|
"-v" prints the version number and exits; "-h" prints brief help text.
|
|
|
-The compiler produces source files for C++ unless the "-p" switch is
|
|
|
-specified, in which case it produces Python code. Finally, the "-d"
|
|
|
-switch directs the compiler to produce the output files in the specified
|
|
|
-directory (the default being the current working directory).
|
|
|
+Finally, the "-d" switch directs the compiler to produce the output
|
|
|
+files in the specified directory (the default being the current
|
|
|
+working directory).
|
|
|
|
|
|
<b>C++ Files</b><br/>
|
|
|
-Without the "-p" option, the message compiler processes the message file
|
|
|
-to produce two files:
|
|
|
|
|
|
<ol>
|
|
|
<li>A C++ header file (called <message-file-name>.h) holding lines of
|
|
@@ -415,28 +411,13 @@ The appearance of such a message indicates a programming error.
|
|
|
</li>
|
|
|
</ol>
|
|
|
|
|
|
-<b>Python Files</b><br/>
|
|
|
-If the "-p" option is given, the compiler produces a Python module defining
|
|
|
-the messages. The content of this is of the form:
|
|
|
-@code
|
|
|
-import isc.log
|
|
|
- :
|
|
|
-LOG_WRITE_ERROR = isc.log.create_message("LOG_WRITE_ERROR",
|
|
|
- "error writing to %1 : %2")
|
|
|
-@endcode
|
|
|
-(The definition is output on one line - it is split across two lines in this
|
|
|
-document for readability.)
|
|
|
-
|
|
|
-The module can be imported into other Python code, and messages logged
|
|
|
-in a similar way to C++ using the Python logging library.
|
|
|
-
|
|
|
@subsubsection logMakefile Include Message Compilation in Makefile
|
|
|
-The source file for the messages is the ".mes" file, but the files used
|
|
|
-by the code (which, in the case of C++, must be compiled and linked)
|
|
|
-are the output of the message compiler. (The compiler is produced very
|
|
|
-early on in the Kea build sequence, so is available for use in the
|
|
|
-building of subsequent components.) To allow this, certain dependencies
|
|
|
-must be included in the Makefile.am for each component that uses logging.
|
|
|
+The source file for the messages is the ".mes" file, but the files
|
|
|
+used by the code which must be compiled and linked are the output of
|
|
|
+the message compiler. (The compiler is produced very early on in the
|
|
|
+Kea build sequence, so is available for use in the building of
|
|
|
+subsequent components.) To allow this, certain dependencies must be
|
|
|
+included in the Makefile.am for each component that uses logging.
|
|
|
|
|
|
<b>Including Message files in C++ Component Builds</b><br/>
|
|
|
The following segment from the "hooks" Makefile.am illustrates
|
|
@@ -485,31 +466,6 @@ These files are therefore included in the definition of the CLEANFILES macro.
|
|
|
Not shown are the Makefile.am lines where the .h and .cc file are used. These
|
|
|
are the same as other lines specifying .h and .cc source files.
|
|
|
|
|
|
-<b>Including Message files in Python Component Builds</b><br/>
|
|
|
-The following (modified) segments from the "xfrin" Makefile.am illustrates
|
|
|
-the entries needed.
|
|
|
-
|
|
|
-@code
|
|
|
-CLEANFILES = $(PYTHON_LOGMSGPKG_DIR)/work/xfrin_messages.py
|
|
|
-CLEANFILES += $(PYTHON_LOGMSGPKG_DIR)/work/xfrin_messages.pyc
|
|
|
- :
|
|
|
-EXTRA_DIST += xfrin_messages.mes
|
|
|
- :
|
|
|
-# Define rule to build logging source files from message file
|
|
|
-$(PYTHON_LOGMSGPKG_DIR)/work/xfrin_messages.py : xfrin_messages.mes
|
|
|
- $(top_builddir)/src/lib/log/compiler/message \
|
|
|
- -d $(PYTHON_LOGMSGPKG_DIR)/work -p $(srcdir)/xfrin_messages.mes
|
|
|
-@endcode
|
|
|
-The CLEANFILES lines remove the created Python (and compiled Python)
|
|
|
-code when "make clean" is run.
|
|
|
-
|
|
|
-The EXTRA_DIST line ensures that the .mes file is copied to the
|
|
|
-distribution tarball.
|
|
|
-
|
|
|
-The final dependency shows the use of the message compiler to
|
|
|
-create the Python message module in a working directory.
|
|
|
-
|
|
|
-
|
|
|
@subsection logUsage Using Logging Files in Program Development
|
|
|
|
|
|
@subsubsection logCppUsage Use in a C++ Program or Module
|
|
@@ -529,8 +485,8 @@ in file scope. The string passed to the constructor is the name of
|
|
|
the logger (it can be any string) and is used when configuring it.
|
|
|
(Remember though that the name of root logger for the program will be
|
|
|
prepended to the name chosen. So if, for example, the name "cache"
|
|
|
-is chosen and the model is included in the "b10-resolver" program, the
|
|
|
-full name of the logger will be "b10-resolver.cache".) Loggers with
|
|
|
+is chosen and the model is included in the "kea-resolver" program, the
|
|
|
+full name of the logger will be "kea-resolver.cache".) Loggers with
|
|
|
the same name share the same configuration. For this reason if, as is
|
|
|
usual, messages logged in different files in the same component (e.g.
|
|
|
hooks module, nameserver address store, etc.) originate from loggers
|
|
@@ -565,34 +521,6 @@ messages of INFO severity or above).</li>
|
|
|
level, and external message file.
|
|
|
</ol>
|
|
|
|
|
|
-@subsubsection logPythonUsage Use in a Python Module
|
|
|
-To use logging in a Python module:
|
|
|
-<ol>
|
|
|
-<li>Build message module as described above.</li>
|
|
|
-
|
|
|
-<li>Declare a logger through which the message will be logged.
|
|
|
-@code
|
|
|
-isc.log.Logger logger("name")
|
|
|
-@endcode
|
|
|
-The string passed to the constructor is the name of the logger (it can
|
|
|
-be any string) and is used when configuring it. Loggers with the same
|
|
|
-name share the same configuration.</li>
|
|
|
-
|
|
|
-<li>Issue calls to the logging methods:
|
|
|
-@code
|
|
|
-logger.error(LOG_WRITE_ERROR, "output.txt")
|
|
|
-@endcode
|
|
|
-The message parameters are included as trailing arguments in the
|
|
|
-logger call.</li>
|
|
|
-
|
|
|
-<li>The main program unit must include a call to isc.log.init() (described
|
|
|
-in more detail below) to set the to set the logging severity, debug log
|
|
|
-level, and external message file. The settings remain in effect until
|
|
|
-the logging configuration is read, so are the ones used during program
|
|
|
-initialization.</li>
|
|
|
-</ol>
|
|
|
-
|
|
|
-
|
|
|
@subsection logInitialization Logging Initialization
|
|
|
In all cases, if an attempt is made to use a logging method before
|
|
|
the logging has been initialized, the program will terminate with a
|
|
@@ -615,7 +543,7 @@ Arguments are:
|
|
|
<dl>
|
|
|
<dt><code>root</code></dt>
|
|
|
<dd>Name of the root logger. This should be the name of the program
|
|
|
-(e.g. "b10-auth") and is used when configuring logging.</dd>
|
|
|
+(e.g. "kea-auth") and is used when configuring logging.</dd>
|
|
|
|
|
|
<dt><code>severity</code></dt>
|
|
|
<dd>Default severity that the program will start logging with. Although
|
|
@@ -732,38 +660,6 @@ instance from the global dictionary.
|
|
|
The hook library itself must not perform any action to register or
|
|
|
unregister log messages in the global dictionary!
|
|
|
|
|
|
-@subsection logInitializationPython Python Initialization
|
|
|
-To initialize the logger in a Python program, the "init" method must be
|
|
|
-called:
|
|
|
-@code
|
|
|
-isc.log.init(name, severity, debuglevel, file, buffer)
|
|
|
-@endcode
|
|
|
-
|
|
|
-<dl>
|
|
|
-<dt><code>name</code></dt>
|
|
|
-<dd>String giving the name of the root logger. This is the only mandatory
|
|
|
-argument, the rest are optional.</dd>
|
|
|
-
|
|
|
-<dt><code>severity</code></dt>
|
|
|
-<dd>The severity, and is one of the strings "DEBUG", INFO" etc.
|
|
|
-The default is "INFO".</dd>
|
|
|
-
|
|
|
-<dt><code>debuglevel</code></dt>
|
|
|
-<dd>Debug level, an integer between 0 and 99. A default value of 0 will
|
|
|
-be used if this is not specified.</dd>
|
|
|
-
|
|
|
-<dt><code>file</code></dt>
|
|
|
-<dd>Name of the external message file (if present). By default, no
|
|
|
-external message file is used.</dd>
|
|
|
-
|
|
|
-<dt><code>buffer</code></dt>
|
|
|
-<dd>If set to true, initial log messages will be internally buffered,
|
|
|
-until the first time a logger specification is processed. This
|
|
|
-way the program can use logging before even processing its logging
|
|
|
-configuration. By default, no buffer is used.</dd>
|
|
|
-</dl>
|
|
|
-
|
|
|
-
|
|
|
@section logNotes Notes on the Use of Logging
|
|
|
One thing that should always be kept in mind is whether the logging
|
|
|
could be used as a means for a DOS attack. For example, if a warning
|