Commit b23ef1cf authored by Stephen Morris's avatar Stephen Morris
Browse files

[trac622] Additional changes to documentation

parent 5ff855e1
......@@ -59,7 +59,7 @@ The steps in using the system are:
2. Run it through the message compiler to produce the .h and .cc files. It
is intended that this step be included in the build process. However,
for not run the compiler (found in the "compiler" subdirectory) manually.
for now run the compiler (found in the "compiler" subdirectory) manually.
The only argument is the name of the message file: it will produce as
output two files, having the same name as the input file but with file
types of ".h" and ".cc".
......@@ -74,7 +74,7 @@ The steps in using the system are:
4. Declare loggers in your code and use them to log messages. This is
described in more detail below.
5. To set the debug level and run-time message file, call runTimeInit (declared
5. To set the debug level and run-time message file, call initLogger (declared
in logger_support.h) in the main program unit. This is a temporary solution
for Year 2, and will be replaced at a later date, the information coming
from the configuration database.
......@@ -106,7 +106,7 @@ UNKNOWN unknown message
Points to note:
* Leading and trailing space are trimmed from the line. Although the above
exampl,e has every line starting at column 1, the lines could be indented
example has every line starting at column 1, the lines could be indented
if desired.
* Blank lines are ignored.
......@@ -120,10 +120,8 @@ Points to note:
* $PREFIX, which has one argument: the string used to prefix symbols. If
absent, there is no prefix to the symbols. (Prefixes are explained below.)
* $NAMESPACE, which has one argument: the namespace in which the symbols are
created. (Specifying the argument as a double colon - i.e. "$NAMESPACE
::" puts the symbol definitions in the unnamed namespace. And not
including a $NAMESPACE directive will result in the symbols note being
put in any namespace.
created. In the absence of a $NAMESPACE directive, symbols will be put
in the global namespace.
* Lines starting + indicate an explanation for the preceding message. These
are intended to be processed by a separate program and used to generate
......@@ -151,13 +149,11 @@ The message compiler processes the message file to produce two files:
the form:
namespace <namespace> {
isc::log::MessageID PREFIX_IDENTIFIER = "IDENTIFIER";
extern const isc::log::MessageID PREFIX_IDENTIFIER;
:
}
The symbols define the keys in the global message dictionary. At present
they are defined as std::strings, but a future implementation could redefine
them as numeric values.
The symbols define the keys in the global message dictionary.
The namespace enclosing the symbols is set by the $NAMESPACE directive.
......@@ -167,14 +163,18 @@ ABC with "MSG_" to give the symbol MSG_ABC. Similarly "$PREFIX E" would
prefix it with "E" to give the symbol EABC. If no $PREFIX is given, no
prefix appears (so the symbol in this example would be ABC).
The header file also includes a couple of lines to ensure that the message
text is included in the final program image.
2) A C++ source file (called <message-file-name>.cc) that holds the definitions
of the global symbols and code to insert the symbols and messages into the map.
Symbols are defined to be equal to strings holding the identifier, e.g.
2) A C++ source file (called <message-file-name>.cc) that holds the code to
insert the symbols and messages into the map.
extern const isc::log::MessageID MSG_DUPLNS = "DUPLNS";
This file declares an array of identifiers/messages in the form:
(The implementation allows symbols to be compared. However, use of strings
should not be assumed - a future implementation may change this.)
iIn addition, the file declares an array of identifiers/messages and an object
to add them to the global dictionary:
namespace {
const char* values[] = {
......@@ -183,20 +183,9 @@ This file declares an array of identifiers/messages in the form:
:
NULL
};
}
(A more complex structure to group identifiers and their messages could be
imposed, but as the array is generated by code and will be read by code,
it is not needed.)
It then declares an object that will add information to the global dictionary:
MessageInitializer <message-file-name>_<time>(values);
(Declaring the object as "static" or in the anonymous namespace runs the risk
of it being optimised away when the module is compiled with optimisation.
But giving it a standard name would cause a clash when multiple files are
used, hence an attempt at disambiguation.)
const isc::log::MessageInitializer initializer(values);
}
The constructor of the MessageInitializer object retrieves the singleton
global Dictionary object (created using standard methods to avoid the
......@@ -236,7 +225,7 @@ To use the current version of the logging:
(The argument is required to support a possible future implementation of
logging. Currently it has no effect.)
3. The main program unit should include a call to isc::log::runTimeInit()
3. The main program unit should include a call to isc::log::initLogger()
(defined in logger_support.h) to set the logging severity, debug log level,
and external message file.
......@@ -250,13 +239,13 @@ To use the current version of the logging:
isc::log::NONE
b) The debug log level is only interpreted when the severity is DEBUG and
is an integer raning from 0 to 99. 0 should be used for the highest-level
debug messages and 99 for the lowest-level (and typically more verbose)
messages.
is an integer ranging from 0 to 99. 0 should be used for the
highest-level debug messages and 99 for the lowest-level (and typically
more verbose) messages.
c) Name of an external message file. This is the same as a standard message
file, although it should not include the $PREFIX directive. (A single
$PREFIX directive will be ignored; multiple directives will cause the
file, although it should not include any directives. (A single directive
of a particular type will be ignored; multiple directives will cause the
read of the file to fail with an error.) If a message is replaced, the
message should include the same printf-format directives in the same order
as the original message.
......@@ -340,7 +329,7 @@ Logging Sources v Logging Severities
When logging events, make a distinction between events related to the server
and events related to DNS messages received. Caution needs to be exercised
with the latter as, if the logging is enabled in the normal course of events,
such logging could be a denoial of service vector. For example, suppose that
such logging could be a denial of service vector. For example, suppose that
the main authoritiative service logger were to log both zone loading and
unloading as INFO and a warning message if it received an invalid packet. An
attacker could make the INFO messages unusable by flooding the server with
......@@ -353,7 +342,7 @@ DEBUG is not enabled by default, so these events will not be recorded unless
DEBUG is specifically chosen.
b) Record system-related and packet-related messages via different loggers
(e.g. in the example given, sever events could be logged using the logger
(e.g. in the example given, server events could be logged using the logger
"auth" and packet-related events at that level logged using the logger
"pkt-auth".) As the loggers are independent and the severity levels
independent, fine-tuning of what and what is not recorded can be achieved.
......@@ -380,7 +369,7 @@ Outstanding Issues
log4cxx Issues
==============
Some experimental code to utilise log4cxx as an underlying implementation
is present in the source code directory, although it is not currently used.
is present in the source code directory although it is not currently used.
The files are:
logger_impl_log4cxx.{cc,h}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment