Log4j project - LogFactor5 Users' Guide

LF5 User Guide Overview Features Reading Files Configuration Library Examples Troubleshoot FAQ Log4j Project Home page |
LogFactor5 Examples
> ### Example 1: InitUsingDefaultConfigurator #### Example Description: The LogFactor5 library has a DefaultLF5Configurator class which provides a very basic LogFactor5 configuration for you. This class can be used to programmatically register an LF5Appender at the root of the org.apache.log4j.Category tree. The InitUsingDefaultConfigurator.java class demonstrates how to use this configurator. When using this class, all that you have to do is make a call to the static l method DefaultLF5Configurator.configure( ), and your basic configuration will be done for you. #### Running the Example: Let `LOG4J_HOME` be the the directory where you installed log4j and let VERSION stand for the log4j version. Ensure that LOG4J_HOME/dist/lib/log4j-VERSION.jar is in your CLASSPATH. Ensure that LOG4J_HOME/dist/classes is in your CLASSPATH. This directory contains the binary class files for running the lf5 examples. It is not needed under normal operational circumstances. Ensure that a JAXP compatible XML parser is in is in your CLASSPATH. Type the following at the command line: java examples.lf5.InitUsingDefaultConfigurator.InitUsingDefaultConfigurator ### Example 2: InitUsingPropertiesFile #### Example Description: The log4j environment is fully configurable programmatically. However, it is far more flexible to configure log4j using configuration files. One common method of configuring log4j involves using a properties file, and the `org.apache.log4j.PropertyConfigurator` class. The `PropertyConfigurator` class allows you to load properties from a standard properties document consisting of key=value pairs. This example demonstrates how to load LogFactor5 via a configuration file used by a PropertyConfigurator. This example uses a very basic properties file, which is loaded via a PropertyConfigurator. The example.properties file has only one property, which registers a `LF5Appender` with the root of the Category tree. The `InitUsingPropertiesFile` class loads this file using the `PropertyConfigurator` class. Note: The example.properties file used in this example is loaded as a resource via your CLASSPATH. For this reason, the example will only work if the LOG4J_HOME/dist/classes directory is in your CLASSPATH #### Running the Example: Let `LOG4J_HOME` be the the directory where you installed log4j. Set up your CLASSPATH as in Example 1 above. Type the following at the command line: java examples.lf5.InitUsingPropertiesFile.InitUsingPropertiesFile ### Example 3: InitUsingXMLPropertiesFile #### Example Description: Log4j can also be configured using an XML properties file, and the org.apache.log4j.xml.DOMConfigurator class. The DOMConfigurator class allows you to load properties from an XML based properties file. This example demonstrates how to load LogFactor5 via an XMLconfiguration file used by a DOMConfigurator. This example uses a very basic XML properties file. The example.xml file registers an LF5Appender with the root of the Category tree. The InitUsingXMLPropertiesFile.java class loads this file using the DOMConfigurator class. Note: The example.xml file used in this example is loaded as a resource via your CLASSPATH. For this reason, the example will only work if the LOG4J_HOME/dist/classes directory is in your CLASSPATH. You will also need an XML parser in order to run this example. #### Running the Example: Let `LOG4J_HOME` be the the directory where you installed log4j. Set up your CLASSPATH as in Example 1 above. Type the following at the command line: java examples.lf5.InitUsingXMLPropertiesFile.InitUsingXMLPropertiesFile ### Example 4: InitUsingLog4JProperties #### Example Description: The log4j library does not make any assumptions about its environment. In particular, there are no default log4j appenders. Under certain well-defined circumstances however, the static initializer of the org.apache.log4j.Category class will attempt to automatically configure log4j. The Java language guarantees that the static initializer of a class is called once and only during the loading of a class into memory. This automatic configuration is done from a file named log4j.properties. If you have a log4j.properties file in your CLASSPATH at the time that you instantiate a Category, log4j will register any appenders in this file at the root of the Category tree. This example provides you with a very basic log4j.properties file that you can add to your CLASSPATH in order to register the LF5Appender with the Category class. If you put this file somewhere in your CLASSPATH, all logging requests will now automatically be redirected to the LogFactor5 logging console in addition to any other Appenders you may have enabled. If you look at the InitUsingLog4JProperties.java file you will notice that no Configurators are used in the code. A Category is instantiated using the getInstance() method, and logging calls such as cat.debug( ) can be used immediately. Note: Adding the LOG4J_HOME/examples/lf5/InitUsingLog4JProperties/log4j.properties file to your CLASSPATH will reduce the number of lines of code you have to write (e.g. you will not need to add lines such as PropertyConfigurator.configure(configFileResource)). However, you should be aware that using this default static initialization has application wide effects. All logging will be directed to LogFactor5 if you use this approach! #### Running the Example: Set up your CLASSPATH as in Example 1 above. Copy the provided LOG4J_HOME/examples/lf5/InitUsingLog4JProperties/log4j.properties file to a directory that is currently in your CLASSPATH. Type the following at the command line: java examples.lf5.InitUsingLog4JProperties.InitUsingLog4JProperties After you are done running the example, make sure to remove the log4j.properties file again, otherwise the log4j will always be using the same configuration. ### Example 5: InitUsingMultipleAppenders #### Example Description: In Log4J, output destinations are called appenders. Currently, appenders exit for the console, rolling log files, remote socket servers, NT Event Loggers, and remote UNIX Syslog daemons. Suppose you want to output log messages to more than one appender... This example demonstrates how to use LogFactor5 along with Log4J's RollingFileAppender to output log messages to both the LogFactor5 console and a series of rolling log files. The example.properties registers two appenders with the root of the Category tree.
>     log4j.rootCategory=, A1, R

>     # A1 is set to be a LF5Appender which outputs to a swing
>     # logging console.

>     log4j.appender.A1=org.apache.log4j.lf5.LF5Appender

>     # R is the RollingFileAppender that outputs to a rolling log
>     # file called rolling_log_file.log.

>     log4j.appender.R=org.apache.log4j.RollingFileAppender
>     log4j.appender.R.File=rolling_log_file.log
> Users must also define a Pattern Layout for the log file. That is, which pieces of information you want logged to the log file and in which order. Information on the various conversion specifiers (i.e. d, p, t, l, m, n) are documented in the PatternLayout class of the Log4J API.
>     log4j.appender.R.layout=org.apache.log4j.PatternLayout
>     # Next line is editited to fit.
>     log4j.appender.R.layout.ConversionPattern=[slf5s.start]%d{DATE}[slf5s.DATE]%n\
>       %p[slf5s.PRIORITY]%n%x[slf5s.NDC]%n%t[slf5s.THREAD]%n%c[slf5s.CATEGORY]%n\
>       %l[slf5s.LOCATION]%n%m[slf5s.MESSAGE]%n%n
> Users also have the ability to set the size of the rolling log file(s) and the number of backup files that should be kept. In this case the the size of the maximum size of the log file is 100KB and the number of backup files kept is 1.
>     log4j.appender.R.MaxFileSize=100KB
>     log4j.appender.R.MaxBackupIndex=1
> The InitUsingMultipleAppenders.java class loads this file using the PropertyConfigurator class. Note: Another approach would be to add the RollingFileAppender configuration to the log4j.properties file. This would cause the InitUsingLog4JProperties example to use both the LogFactor5 console and a rolling log file as it's output destinations. #### Running the Example: Set up your CLASSPATH as in Example 1 above. Type the following at the command line: java examples.lf5.InitUsingMultipleAppenders.InitUsingMultipleAppenders ### Example 6: UsingSocketAppenders #### Example Description: When logging messages from an application, it is often useful to log the messages to a remote location over a socket. Log4j comes with a variety of classes designed for this purpose. This example is designed to show you how to use these log4j classes in conjunction with the LF5Appender. Two specific log4j classes are instrumental for logging messages over a socket: the org.apache.log4j.net.SocketAppender class and the org.apache.log4j.net.SocketServer class. The SocketAppender class: The SocketAppender class is used on the application side, where log messages are being created. This class sends all logging messages to a specific host and port as specified in a properties file. The properties file can be either an application specific properties file, or the system log4j.properties file. In this example, the socketclient.properties file contains the information that registers the SocketAppender with log4j. The following lines from the socketclient.properties file register the SocketAppender with log4j:
>            log4j.appender.A1=org.apache.log4j.net.SocketAppender
>            log4j.appender.A1.RemoteHost=localhost
>            log4j.appender.A1.Port=8887
> For additional details about properties files, refer to the log4j documentation or the other LogFactor5 examples. The SocketServer class: The SocketServer class listens on a port specified as a command line argument. The host and port of the machine running the SocketServer class must correspond to the host and port in the socketclient.properties file. The SocketServer class uses a separate properties file to determine which Appenders it should forward incoming messages to. In this example, the socketserver.properties file contains the information that registers the LF5Appender with log4j. The following lines from the socketserver.properties file register the LF5Appender with log4j on the server side:
>            log4j.appender.A=org.apache.log4j.lf5.LF5Appender
>            log4j.appender.A1.MaxNumberOfRecords=700
> The first line registers the LF5Appender with log4j, and the second line tells LogFactor5 the maximum number of records to display in the GUI at any one time. For additional information about how the SocketServer class loads properties files (including default properties files) please refer to the log4j documenation. #### Running the Example: Set up your CLASSPATH as in Example 1 above. Start the SocketServer using the following command: java org.apache.log4j.net.SimpleSocketServer 8887 LOG4J_HOME/examples/lf5/UsingSocketAppenders/socketserver.properties At another command line, start the client using the following command: java examples.lf5.UsingSocketAppenders.UsingSocketAppenders ### Example 7: OpeningLogFiles #### Example Description: Log4J's RollingFileAppender gives you the ability to output log messages to a series of rolling files. However, there are no utilities available for reading in and viewing those files once they have been written. LogFactor5 provides developers with two easy ways to open and view log files. Log files can be opened locally using the 'Open' menu item or log files can be opened from a remote server using the 'Open URL' menu item. An additional feature that was added to LogFactor5 was the ability to start the console window independent of Log4J. That is to say, you do not need to add a LF5Appender to your properties file to use LogFactor5. The benefit of this feature is that developers who run utilities like Ant to test their applications can now view their log files off-line (i.e. after their application has completed the test and the JVM has shut down). Moreover, the ability to open log files on a remote server provides the ability for multiple developers working on the same application to view log files independently. It also gives developers the ability to view log files both internally and from remote locations. This example uses the sample.log file created by Log4J's RollingFileAppender. 1The format of the log file can be set in the log4j.properties or a standard properties file and must follow the LogFactor5 layout conventions in order for LogFactor5 to open the file. The following is an example of a properties file with the LogFactor5 conversion pattern added:
>     log4j.rootCategory= R

>     # R is the RollingFileAppender that outputs to a rolling log
>     # file called sample.log.

>     log4j.appender.R=org.apache.log4j.RollingFileAppender
>     log4j.appender.R.File=sample.log

>     # Define a pattern layout for the file.
>     # For more information on conversion characters (i.e. d,p,t,c,l,m,n)
>     # please see the PatternLayout class of the Log4j API.

>     log4j.appender.R.layout=org.apache.log4j.PatternLayout
>     log4j.appender.R.layout.ConversionPattern=[slf5s.start]%d{DATE}[slf5s.DATE]%n\
>     %p[slf5s.PRIORITY]%n%x[slf5s.NDC]%n%t[slf5s.THREAD]%n\
>     %c[slf5s.CATEGORY]%n%l[slf5s.LOCATION]%n%m[slf5s.MESSAGE]%n%n

>     # Set the max size of the file

>     log4j.appender.R.MaxFileSize=500KB
> You are free to use any or all of the main conversion characters to create ml your log file (i.e. %p for Priority). There are only two requirements for the conversion pattern. First, the conversion pattern string must start with the tag [slf5s.start]. Second, for each log4j conversion character listed in the conversion pattern string, a corresponding LogFactor5 tag must be placed immediately after the character. The following is a complete list of the log4j characters and LogFactor5 tags:
>     Date - %d{DATE}[slf5s.DATE]
>     Priority - %p[slf5s.PRIORITY]
>     NDC - %x[slf5s.NDC]
>     Thread - %t[slf5s.THREAD]
>     Category - %c[slf5s.CATEGORY]
>     Location - %l[slf5s.LOCATION]
>     Message - %m[slf5s.MESSAGE]
> Note: The order of the characters does not matter so you are free to layout your log file any way you like. Just remember to include the LogFactor5 start tag at the beginning of the string and any LogFactor5 tags after each corresponding log4j conversion character. #### Running the Example: Set up your CLASSPATH as in Example 1 above. Type the following at the command line: java org.apache.log4j.lf5.StartLogFactor5 Under the 'File' menu, select 'Open'. Open the sample.log file located in the examples/lf5/OpeningLogFiles directory. Clear the log table using the Clear Log Table button. ### Example 8 #### Example 8a: UsingLogMonitorAdapter #### Example Description: Ideally LogFactor5's intended use is with Log4J, but this does not preclude its use with other logging schemes. The LogMonitorAdapter API allows developers to log directly to the LogFactor5 GUI Monitor with a minimum of effort. The UsingLogMonitorAdapter.java class demonstrates how to use the LogMonitorAdapter. This example requests a new instance of the LogMonitorAdapter, and uses the log4j Priority levels.
>          _adapter = LogMonitorAdapter.newInstance(LogMonitorAdapter.LOG4J_LOG_LEVELS);
> When you log to the LogFactor5 GUI Monitor, simply call one of the many log methods on the LogMonitorAdapter object:
>          _adapter.log(channel,"Doh this is a debugging");

>          _adapter.log(channel,LogLevel.INFO,"Hmmm fobidden doughnut");
>          _adapter.log(channel,LogLevel.WARN,"Danger Danger Will Robinson",
>              new RuntimeException("DANGER"), "32");
>          _adapter.log(channel,LogLevel.ERROR,"Exit stage right->");
>          _adapter.log(channel,LogLevel.FATAL,"What's up Doc?",
>              new NullPointerException("Unfortunate exception"));
> #### Running the Example: Set up your CLASSPATH as in Example 1 above. Type the following at the command line: java examples.lf5.UsingLogMonitorAdapter.UsingLogMonitorAdapter #### Example 8b: CustomizedLogLevels #### Example Description: What good is a LogMonitorAdapter if you can only use preset LogLevels? This example illustrates how to use the LogMonitorAdapter with a set of user-defined LogLevels. The CustomizedLogLevels.java class demonstrates how to customize LogLevels ml to suit your logging needs. As with the previous example we request an instance of the LogMonitorAdapter, but this time an array of defined LogLevels is supplied:
>          _adapter = LogMonitorAdapter.newInstance(new LogLevel[] {DEFAULT, LEVEL_ONE,
>                LEVEL_TWO,LEVEL_THREE, LEVEL_FOUR });
> The LogMonitorAdapter will set the first entry in the array to be the default LogLevel. For example, when logging a message where no LogLevel has been specified, the DEFAULT LogLevel will be used. The default LogLevel can also be set using the LogMonitorAdapter's setDefaultLevel method, while the severe LogLevel can be set as follows:
>          _adapter.setSevereLevel(LEVEL_ONE);
> Logging messages then follow the same rules as the example above.
>          _adapter.log(channel,"Using the customized LogLevels");

>          _adapter.log(channel,LEVEL_FOUR,"This is a test");
>          _adapter.log(channel,LEVEL_THREE,"Hmmm fobidden doughnut");
>          _adapter.log(channel,LEVEL_ONE,"Danger Danger Will Robinson",
>              new RuntimeException("DANGER"), "32");
>          _adapter.log(channel,LEVEL_TWO,"Exit stage right->");
>          _adapter.log(channel,LEVEL_FOUR,"What's up Doc?",
>              new NullPointerException("Unfortunate exception"));
#### Running the Example: Set up your CLASSPATH as in Example 1 above. Type the following at the command line: java examples.lf5.UsingLogMonitorAdapter.CustomizedLogLevels
Copyright © 1999-2002, Apache Software Foundation