Remerciez-le!

Remerciez @Admin pour avoir partagé cet document gratuitement, de la manière la plus simple, en partageant sur les réseaux sociaux.

Log4C Developers Guide 1.0.6 13 Nov 2006 First Draft: pulls together informatio

Log4C Developers Guide 1.0.6 13 Nov 2006 First Draft: pulls together information from README files and various 'how to ' documents for Log4C. This document is started between the release of Log4C 1.1.0 and 1.2 so although much of it is valid for older releases it is more looking towards the 1.2 release. Where you see xxx in the text this denotes an item we need to get back to. This document was created with Open Office 2.0.2 . Table of Contents 1 Introduction.............................................................................................................................................2 2 Log4C Concepts and Overview..............................................................................................................2 3 How to download and build Log4C.......................................................................................................3 3.1 Parsing the Log4C configuration filethe expat dependency.........................................................3 3.2 Some comments on building Log4C in the corporate factory.......................................................4 3.2.1 Log4C is released under the LGPL license. ..........................................................................4 3.2.2 Building on different platforms..............................................................................................5 3.2.2.1 Building On Unix............................................................................................................5 3.2.2.2 Building on Windows.....................................................................................................5 3.2.2.3 Building on MAC OS.....................................................................................................5 3.2.3 Packaging on different platforms...........................................................................................6 4 Getting startedrunning the examples...................................................................................................6 4.1 Running application_1...................................................................................................................6 4.2 Configuring the priority for a category..........................................................................................8 4.3 Configuring application_1 to log to a set of log files.....................................................................8 4.4 What about application_2 ?............................................................................................................9 5 Using the Log4C API.............................................................................................................................9 5.1 The helloworld example with Log4C.............................................................................................9 5.1.1 The helloworld code...............................................................................................................9 5.1.2 Configuring and running helloworld....................................................................................10 5.1.2.1 Configuring helloworld with the configuration file......................................................10 5.1.2.2 Configuring helloworld with the environment variables..............................................11 5.1.2.3 Configuring helloworld via the Log4C API.................................................................12 5.2 Comments on the the different configuration methods................................................................12 5.3 Interaction of the configuration methods.....................................................................................12 5.4 Including Log4C calls into your code .........................................................................................13 5.4.1 Making it easy to remove Log4C calls from your code.......................................................13 5.4.2 Other useful Log4C functions..............................................................................................15 5.4.3 Multi threaded applications using Log4C............................................................................15 5.4.3.1 Why the Log4C API is not fully MT safe....................................................................15 5.4.3.2 How to use Log4C in an MT safe way.........................................................................16 6 Extending Log4C with your own custom appender and layout types..................................................17 7 Troubleshooting and debugging..........................................................................................................19 8 Deployment Experience with Log4C....................................................................................................19 8.1 Blame it on the logger...................................................................................................................20 8.2 Preparing to move logging from development into a production environment............................20 9 References............................................................................................................................................22 1 Introduction Log4C is a Cbased logging library. Its goal is provide the C software developer with a configurable and efficient library for logging messages. So Log4C provides the classic logging functionality required by most projects by default while leaving the scope for extensibility for those projects that have special requirements. It seems extraordinary that just about every C project ends up developing it's own logging system. While there are environments like embedded systems or operating system kernels that may justify customized logging technology (and there are open source projects aimed at those areas) there seems to be no a priori reason why most user level application and server software written in C cannot share a logging library. Log4C may be linked with end user applications or other libraries that will eventually be linked into applications. The library is released on SourceForge under the LGPL license. This document is aimed at developers who wish to use Log4C to manage logging in their own project. The kind of information you can find here includes: ● a general introduction to Log4C concepts and how Log4C can be useful to you ● how to download and build Log4C ● how to use and configure the library via examples ● how to extend Log4C with your own code for customizing, for example, where messages are logged and how they are formatted. ● troubleshooting and debug information ● deployment experience with Log4C ● references to useful material For information relating to Log4C internals the intention is to create a separate documents, “Log4C Internals”. This will help keep the size of each document reasonable and help decouple the evolution of those documents. 2 Log4C Concepts and Overview Log4C follows the overall style of the native Java logging and Log4j utilities. There are three fundamental types of object in Log4C: categories, appenders and layouts. You can think of these objects as corresponding to the what, where and how of the logging system: categories describe what subsystem the message relates to, appenders determine where the message goes and layouts determine how the message is formatted. So for example a category might be named “httpd.network.connection” that may be logging messages to the “syslog” appender using the “dated” format. The convention of using dotted names for categories determines an obvious hierarchy which is used to determine parent and child relationships during logging. These are used because during logging (and this is configurable) a message logged by a category will also be logged to the appenders of any parent categories. There is always a root category which represents a conceptual root of the hierarchy of categories. The categorization of the system make sit easy to select which messages are logged and where—if I configure an appender and priority for a given category then I automatically do it for all it's descendants (unless I explicitly say not to). The extreme case of this is the root category—any configuration positioned there will by default apply to all categories in the system. However, if I need to drill down for finer grained control then the categorization allows me to do that. This means that you should expect to spend some time defining the categories within your system. As an example, if your system separates into different applications then you should have at least one category per application. If your product ships a set of libraries, then each library probably merits it's own category. Libraries linked in as a dependency on a given library should probably be subcategories of the including library. Within a library you might identify other sub categories, for example a housekeeping category, a connection manager category, a request processor and so on that correspond to logging messages that will come from those sections of code. The other concept fundamental to Log4C is the logging priority: each message has an associated priority. At a given point a given instance of Log4c has an associated configured priorityonly messages with a higher priority than the current Log4c priority are sent to an appender for processing. 3 How to download and build Log4C The README file shipped in the workspace gives a good account of Log4C dependencies and how to do a basic build so we will not repeat all that information here. Here we treat that information that requires more detail than the basic build instructions. 3.1 Parsing the Log4C configuration file--the expat dependency “The expat dependency”no it's not the latest Robert Ludlum novel...it refers to the fact that Log4C can use the expat library (cf. http://expat.sourceforge.net/) as the low level xml parser for it's configuration file. By default when you run configure, it will look for expat and if it finds it it will use it. You can tell configure not to go looking for expat by using the withoutexpat option. In the case where you have specified withoutexpat or expat is not found or is the wrong version or fails to compile with a small test program, then Log4C will use a custom XML parser using lex/yacc code for the lower level xml parsing. This code works ok with the current configuration file and bundled appenders and layouts. So why do you need to know how Log4C handles it's xml parsing ? Well, as a developer integrating Log4C you will probably prefer the “bundled parser” option as it means you do not pull a dependency on expat. However from the point of view of maintaining Log4C there is still a dependency on the lex/yacc tools needed to generate the parsing code. So there is a choice to make in terms of which dependency Log4C manages. The current consensus is that expat is now sufficiently widespread and mature that introducing a dependency on it is a reasonable step. So as a developer consuming Log4C you can rely on the older bundled code staying in Log4C for the foreseeable future. But you should not expect bug fixes therein nor that that code will evolve to take account of potential enhancements to the configuration file. So the message is that you should start to prepare for handling the dependency on the expat library, either by bundling it in your delivery with Log4C or ensuring that it is available natively on your supported platforms or by specifying it as a requirement to your end users. 3.2 Some comments on building Log4C in the corporate factory The Log4C source code is free, which is good, but there is still a cost in integrating it into your project. Here are some points to consider on this. 3.2.1 Log4C is released under the LGPL license. See the COPYING file in the release for the full license but this means a few things: ● you will almost certainly require a legal review inside your company to approve your use of Log4C. ● you are required by the LGL license to ship along with your project a copy of the Log4C source as used in your project. You are also required to ship a copy of the LGL license. Typically one ships a file called something like, ThirdPartyLicenses which lists uploads/S4/ log4c-developersguide.pdf