Short introduction to Apache log4cxxIntroductionApache log4cxx is a logging framework for C++ patterned after Apache log4j . Apache log4cxx uses Apache Portable Runtime for most platform-specific code and should be usable on any platform supported by APR. Apache log4cxx is licensed under the Apache License , an open source license certified by the Open Source Initiative .Almost every large application includes its own logging or tracing API. Inserting log statements into code is a low-tech method for debugging it. It may also be the only way because debuggers are not always available or applicable. This is usually the case for multithreaded applications and distributed applications at large. Experience indicates that logging is an important component of the development cycle. It offeres several advantages. It provides precise context about a run of the application. Once inserted into the code, the generation of logging output requires no human intervention. Moreover, log output can be saved in persistent medium to be studied at a later time. In addition to its use in the development cycle, a sufficiently rich logging package can also be viewed as an auditing tool. Logging does have its drawbacks. It can slow down an application. If too verbose, it can cause scrolling blindness. To alleviate these concerns, log4cxx is designed to be reliable, fast and extensible. Since logging is rarely the main focus of an application, the log4cxx API strives to be simple to understand and to use. Loggers, Appenders and LayoutsLog4cxx has three main components: loggers, appenders and layouts. These three types of components work together to enable developers to log messages according to message type and level, and to control at runtime how these messages are formatted and where they are reported. Logger hierarchyThe first and foremost advantage of any logging API over plain Loggers are named entities. Logger names are case-sensitive and they follow the hierarchical naming rule:
For example, the logger named The root logger resides at the top of the logger hierarchy. It is exceptional in two ways:
Invoking the class static log4cxx::Logger::getRootLogger method retrieves it. All other loggers are instantiated and retrieved with the class static log4cxx::Logger::getLogger method. This method takes the name of the desired logger as a parameter. Some of the basic methods in the Logger class are listed below.
Loggers may be assigned levels. The pre-defined levels: TRACE, DEBUG, INFO, WARN, ERROR and FATAL are defined in the If a given logger is not assigned a level, then it inherits one from its closest ancestor with an assigned level. More formally:
To ensure that all loggers can eventually inherit a level, the root logger always has an assigned level. Below are four tables with various assigned level values and the resulting inherited levels according to the above rule.
In example 1 above, only the root logger is assigned a level. This level value,
In example 2, all loggers have an assigned level value. There is no need for level inheritence.
In example 3, the loggers
In example 4, the loggers Logging requests are made by invoking a method of a logger instance, preferrably through the use of LOG4CXX_INFO or similar macros which support short-circuiting if the threshold is not satisfied and use of the insertion operator (<<) in the message parameter.
A logging request is said to be enabled if its level is higher than or equal to the level of its logger. Otherwise, the request is said to be disabled. A logger without an assigned level will inherit one from the hierarchy. This rule is summarized below.
This rule is at the heart of log4cxx. It assumes that levels are ordered. For the standard levels, we have Here is an example of this rule.
Calling the For example, in
x and y refer to exactly the same logger object.
Thus, it is possible to configure a logger and then to retrieve the same instance somewhere else in the code without passing around references. In fundamental contradiction to biological parenthood, where parents always preceed their children, log4cxx loggers can be created and configured in any order. In particular, a "parent" logger will find and link to its descendants even if it is instantiated after them. Configuration of the log4cxx environment is typically done at application initialization. The preferred way is by reading a configuration file. This approach will be discussed shortly. Log4cxx makes it easy to name loggers by software component. This can be accomplished by statically instantiating a logger in each class, with the logger name equal to the fully qualified name of the class. This is a useful and straightforward method of defining loggers. As the log output bears the name of the generating logger, this naming strategy makes it easy to identify the origin of a log message. However, this is only one possible, albeit common, strategy for naming loggers. Log4cxx does not restrict the possible set of loggers. The developer is free to name the loggers as desired. Nevertheless, naming loggers after the class where they are located seems to be the best strategy known so far. Appenders and LayoutsThe ability to selectively enable or disable logging requests based on their logger is only part of the picture. Log4cxx allows logging requests to print to multiple destinations. In log4cxx speak, an output destination is called an appender. Currently, appenders exist for the console , files , GUI components, remote socket servers, NT Event Loggers , and remote UNIX Syslog daemons. It is also possible to log asynchronously . More than one appender can be attached to a logger. The addAppender method adds an appender to a given logger. Each enabled logging request for a given logger will be forwarded to all the appenders in that logger as well as the appenders higher in the hierarchy. In other words, appenders are inherited additively from the logger hierarchy. For example, if a console appender is added to the root logger, then all enabled logging requests will at least print on the console. If in addition a file appender is added to a logger, say C, then enabled logging requests for C and C's children will print on a file and on the console. It is possible to override this default behavior so that appender accumulation is no longer additive by setting the additivity flag to The rules governing appender additivity are summarized below.
The table below shows an example:
More often than not, users wish to customize not only the output destination but also the output format. This is accomplished by associating a layout with an appender. The layout is responsible for formatting the logging request according to the user's wishes, whereas an appender takes care of sending the formatted output to its destination. The PatternLayout , part of the standard log4cxx distribution, lets the user specify the output format according to conversion patterns similar to the C languageprintf function.
For example, the PatternLayout with the conversion pattern "%r [%t] %-5p %c - %m%n" will output something akin to: 176 [main] INFO org.foo.Bar - Located nearest gas station.
The first field is the number of milliseconds elapsed since the start of the program. The second field is the thread making the log request. The third field is the level of the log statement. The fourth field is the name of the logger associated with the log request. The text after the '-' is the message of the statement. ConfigurationInserting log requests into the application code requires a fair amount of planning and effort. Observation shows that approximately 4 percent of code is dedicated to logging. Consequently, even moderately sized applications will have thousands of logging statements embedded within their code. Given their number, it becomes imperative to manage these log statements without the need to modify them manually. The log4cxx environment is fully configurable programmatically. However, it is far more flexible to configure log4cxx using configuration files. Currently, configuration files can be written in XML or in Java properties (key=value) format. Let us give a taste of how this is done with the help of an imaginary application
The invocation of the BasicConfigurator::configure method creates a rather simple log4cxx setup. This method is hardwired to add to the root logger a ConsoleAppender . The output will be formatted using a PatternLayout set to the pattern "%-4r [%t] %-5p %c %x - %m%n". Note that by default, the root logger is assigned to The output of MyApp is: 0 [12345] INFO MyApp - Entering application. 36 [12345] DEBUG com.foo.Bar - Did it again! 51 [12345] INFO MyApp - Exiting application.
The previous example always outputs the same log information. Fortunately, it is easy to modify
This version of Here is a sample configuration file that results in exactly same output as the previous
It can be noticed that the PropertyConfigurator file format is the same as log4j. Suppose we are no longer interested in seeing the output of any component belonging to the
The output of 2000-09-07 14:07:41,508 [12345] INFO MyApp - Entering application. 2000-09-07 14:07:41,529 [12345] INFO MyApp - Exiting application. As the logger Here is another configuration file that uses multiple appenders.
Calling the enhanced MyApp with the this configuration file will output the following on the console. INFO [12345] (MyApp2.cpp:31) - Entering application. DEBUG [12345] (Bar.h:16) - Doing it again! INFO [12345] (MyApp2.cpp:34) - Exiting application.
In addition, as the root logger has been allocated a second appender, output will also be directed to the Note that to obtain these different logging behaviors we did not need to recompile code. We could just as easily have logged to a UNIX Syslog daemon, redirected all Default Initialization ProcedureThe log4cxx library does not make any assumptions about its environment. In particular, there are no default log4cxx appenders. Under certain well-defined circumstances however, the static inializer of the The exact default initialization algorithm is defined as follows:
Nested Diagnostic ContextsMost real-world systems have to deal with multiple clients simultaneously. In a typical multithreaded implementation of such a system, different threads will handle different clients. Logging is especially well suited to trace and debug complex distributed applications. A common approach to differentiate the logging output of one client from another is to instantiate a new separate logger for each client. This promotes the proliferation of loggers and increases the management overhead of logging. A lighter technique is to uniquely stamp each log request initiated from the same client interaction. Neil Harrison described this method in the book "Patterns for Logging Diagnostic Messages," in Pattern Languages of Program Design 3, edited by R. Martin, D. Riehle, and F. Buschmann (Addison-Wesley, 1997). To uniquely stamp each request, the user pushes contextual information into the NDC, the abbreviation of Nested Diagnostic Context. The NDC class is shown below. namespace log4cxx { class NDC { public: // pushes the value on construction and pops on destruction. NDC(const std::string& value); NDC(const std::wstring& value); // Remove the top of the context from the NDC. static LogString pop(); // Add diagnostic context for the current thread. static void push(const std::string& message); static void push(const std::wstring& message); }
The NDC is managed per thread as a stack of contextual information. Note that all methods of the To illustrate this point, let us take the example of a servlet delivering content to numerous clients. The servlet can build the NDC at the very beginning of the request before executing other code. The contextual information can be the client's host name and other information inherent to the request, typically information contained in cookies. Hence, even if the servlet is serving multiple clients simultaneously, the logs initiated by the same code, i.e. belonging to the same logger, can still be distinguished because each client request will have a different NDC stack. Contrast this with the complexity of passing a freshly instantiated logger to all code exercised during the client's request. Nevertheless, some sophisticated applications, such as virtual hosting web servers, must log differently depending on the virtual host context and also depending on the software component issuing the request. Recent log4cxx releases support multiple hierarchy trees. This enhancement allows each virtual host to possess its own copy of the logger hierarchy. PerformanceOne of the often-cited arguments against logging is its computational cost. This is a legitimate concern as even moderately sized applications can generate thousands of log requests. Much effort was spent measuring and tweaking logging performance. Log4cxx claims to be fast and flexible: speed first, flexibility second. The user should be aware of the following performance issues.
ConclusionsApache Log4cxx is a popular logging package written in C++. One of its distinctive features is the notion of inheritance in loggers. Using a logger hierarchy it is possible to control which log statements are output at arbitrary granularity. This helps reduce the volume of logged output and minimize the cost of logging. One of the advantages of the log4cxx API is its manageability. Once the log statements have been inserted into the code, they can be controlled with configuration files. They can be selectively enabled or disabled, and sent to different and multiple output targets in user-chosen formats. The log4cxx package is designed so that log statements can remain in shipped code without incurring a heavy performance cost. |
|