Presentation log4 j

http://logging.apache.org/log4j/docs/

Sylvain Bouchard

2006Communication interactive et nouvelles technologies / Interactive Communications through New Technologies

Page 2

Agenda Definition Basic features Level Appenders Loggers Layouts Filters Tips


Page 3

- Logging is a low-tech method for debugging applications. - Logging can also be viewed as an auditing tool.

Applicability Debuggers are not always available for multi-threaded or distributed applications.

Advantages Debugging sessions are transient, logging is persistent.

Disadvantages• Logging can slow down an application. • Can be hard to locate relevant information for large log outputs.

The central issue in logging is the categorization of logging statements.

Logging, a definition


Page 4



Page 5

Basic features of any logging library are control over which logging statements are enabled or disabled

The first feature corresponds to the Logger, the central class in the log4j package.

manage output destinations The second feature is implemented by Appenders. There are appenders for files, the

console, Unix Syslog, NT Event Log, remote servers, SMTP e-mail, etc.

manage output format The third feature is implemented by Layouts. The most popular layouts are the

PatternLayout and HTMLLayout


Page 6



Page 7

Level Allows you to prioritize your logged messages

TRACE, DEBUG, INFO, WARN, ERROR and FATAL Other priorities possible but usually unnecessary

Determines which log items are actually logged For example, a given line of code might always attempt to log an item at

Debug level but if the logger tree is not set to log items below Error level then the log message will be ignored and not make it to an appender.


Page 8



Page 9

Appenders ConsoleAppender, FileAppender, RollingFileAppender,

DailyRollingFileAppender, SMTPAppender, JDBCAppender, NTEventLogAppender, …

Multiple appenders can be used One appender could be used for auditing while another is used for

general logging


Page 10

An appender element must have name and class attributes. The name is the value used to reference the appender in the rest of the configuration file. The class attribute should be the fully qualified class name of the appender class to use (ie org.apache.log4j.ConsoleAppender ).

An appender element can also contain child elements: 0 or 1 errorHandler element - <yet to be described> 0 or more param elements - Each appender can be configured with

setting specific to the functioning of the appender.

<!ELEMENT appender (errorHandler?, param*, layout?, filter*, appender-ref*)> <!ATTLIST appender name ID #REQUIRED class CDATA #REQUIRED >

log4j.dtd


Page 11

0 or 1 layout element - Not all appenders use or require a layout. For appenders that do, the layout element defines what layout class to use. The layout element has one attribute, class, which is the fully qualified class name of the layout class to use. Similar to the appender element, the layout element is allowed to have 0 or more param child elements.

0 or more filter elements. 0 or more appender-ref elements

<appender name="console" class="org.apache.log4j.ConsoleAppender"> <param name="Target" value="System.out"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%-5p %c{1} - %m%n"/> </layout> </appender>

A simple example


Page 12

Appenders Configuration Example

<appender name="FileAppender" class="org.apache.log4j.FileAppender"> <param name="File" value="/log/myFile.log" /> <param name="Append" value="true" /> <param name="Threshold" value="INFO"/> . . .</appender>

FileAppenders: Appends log events to a file.

File: path and filename of the file.Append: If true, open the file in append mode.

If false, open in truncate mode.Threshold: Set the threshold level. All log events with lower

level than the threshold level are ignored by the appender. (TRACE, DEBUG, INFO, WARN, ERROR and FATAL)

ImmediateFlush: Default is true, meaning log messages are not bufferedat all which is what you want almost all of the time.


Page 13

<appender name="RollingFileSample" class="org.apache.log4j.RollingFileAppender"> <param name="File" value="/log/myRollingFile.log"/> <param name="Append" value="true"/> <param name="MaxFileSize" value="500KB"/> <param name="MaxBackupIndex" value="1"/> . . .</appender>

RollingFileAppenders: Extends FileAppender to backup the log files when

they reach a certain size.

MaxFileSize: Set the maximum size that the output file is allowed to reach before being rolled over to backup files. You can specify the value with the suffixes "KB","MB" or

"GB“.MaxBackupIndex: Set the maximum number of backup files to keep around.

0 means no backup files at all.

* Plus all parameters from fileAppender


Page 14

<appender name="DRFileSample" class="org.apache.log4j.DailyRollingFileAppender"> <param name="File" value="/log/myDailyFile.log"/> <param name="DatePattern" value="'.'yyyy-MM-dd'.log'"/>

<layout class="org.apache.log4j.PatternLayout"><param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>

</layout></appender>

DailyRollingFileAppender: Extends FileAppender so that the underlying file is rolled over at a user chosen frequency.

DatePattern : Takes a string in the same format as expected by SimpleDateFormat. This options determines the rollover schedule.

Ex: DatePattern Rollover schedule'.'yyyy-MM' Rollover at the beginning of each month'.'yyyy-MM-dd' Rollover at midnight each day.'.'yyyy-MM-dd-HH' Rollover at the top of every hour.where '.' represent your filename in the datePattern

* Plus all parameters from fileAppender


Page 15

<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender"><param name="Target" value="System.out"/><param name="Threshold" value="INFO"/>. . .

</appender>

ConsoleAppender: appends log events to System.out or System.err using a layout specified by the user. The default target is System.out.

Target: Recognized values are "System.out" and "System.err". Any other value will be ignored.

Threshold: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.ImmediateFlush: Default is true, meaning log messages are not buffered at all which is what you want almost all of the time.


Page 16

<appender name="JDBCSample" class="org.apache.log4j.jdbc.JDBCAppender"><param name="Threshold" value="ERROR"/><param name="driver" value="com.sybase.jdbc2.jdbc.SybDriver"/><param name="URL" value="jdbc:sybase:Tds:127.0.0.1:2638/Summit"/><param name="user" value="DBA"/><param name="password" value="SQL"/>. . .

</appender>

JDBCAppender: sending log events to a database.

Driver: Ensures that the given driver class has been loaded for SQL connection creation. URL: url / jdbc connection.user: Connection username.password: Connection username.Threshold: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.


Page 17

<appender name="EmailSample" class="org.apache.log4j.net.SMTPAppender"><param name="Threshold" value="FATAL"/><param name="To" value="[email protected]"/><param name="From" value="[email protected]"/><param name="Subject" value="One Fatal Error"/><param name="SMTPHost" value="localhost"/><param name="BufferSize" value="10"/>. . .

</appender>

SMTPAppender: Send an e-mail when a specific logging event occurs.

To, From: takes a string value which should be a comma separated list of e-mail address of the recipients / sender.Cc, Bcc: the cc and bcc recipient addresses.Subject: the subject of the e-mail message.SMTHHost: the host name of the SMTP server that will send the e-mail message.SMTHUsername: the username required to authenticate against the mail server.SMTHPassword: the password required to authenticate against the mail server.BufferSize: the maximum number of logging events to collect in a cyclic buffer.Threshold: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.


Page 18



Page 19

LoggersNow the appenders are configured. But how to configure loggers to output messages at a certain level? How to configure loggers to output to specific appender?

Welcome to logger configuration. The most important logger you need to configure is the root logger. From the simple example,this was done with the following configuration:

<root> <priority value ="debug" /> <appender-ref ref="console" /> </root>

The root logger is configured to output log message at level "debug" or higher to the appender named "console". All loggers inherit their settings from the root logger, so with no other configuration settings, all loggers will output all of their messages to the "console" appender automatically. This may be fine for simple debugging, but eventually more specific logger configuration is going to be required.


Page 20

A logger element must have a name attribute. This is the name of the logger used when creating the Logger instance(usually the fully qualified class name).

A logger element can also contain child elements: 0 or 1 level element - This defines the level of log messages that will be

allowed to be logged for this logger. Normal usage has a value of "debug", "info", "warn", "error", or "fatal". Only that level or above will be reported to the log.

0 or more appender-ref elements - This references a defined appender that log messages from this logger should be directed to. Appender-ref elements are simple elements that have a ref attribute. The value for this attribute should be the name of the appender.

<!ELEMENT logger (level?,appender-ref*)> <!ATTLIST logger

name ID #REQUIRED additivity (true|false) "true"

>

log4j.dtd


Page 21

<logger name="com.mycompany.apackage.MyClass"> <level value="info"/></logger>

A simple example

The logger is configured to output log message at level “info" or higher to the default appender Root, cause there’s no appender-ref defined. And the logger will log message coming from the specific class com.mycompany.apackage.MyClass.

You can log for a entire package by changing the name to com.mycompany.apackage. And every message coming from the package com.mycompany.apackage, will be log.


Page 22



Page 23

Layouts Method of customizing output from logger: Simple, HTML, Pattern and XML layouts are

included Some layout classes are SimpleLayout, PatternLayout, HTMLLayout, and XMLLayout. Custom object renderers can be installed

SimpleLayout - org.apache.log4j.SimpleLayout

SimpleLayout consists of the priority of the log statement, followed by " - " and then the log message itself. For example:DEBUG - Hello world

<!ELEMENT layout (param*)> <!ATTLIST layout

class CDATA #REQUIRED >

log4j.dtd


Page 24

PatternLayout - org.apache.log4j.PatternLayout

PatternLayout lets you specify the output format according to conversion patterns similar to the C language printf function.

For example, PatternLayout with the conversion pattern %r [%t] %-5p %c - %m%n will output something like:

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 priority of the log statement. The fourth field is the name of the category associated with the log request. The text after the '-' is the message of the statement.


Page 25

You can insert any literal text within the conversion pattern Conversion characters are:

%m: Outputs your message. %p: Outputs the priority of the logging event. %r: Outputs the number of milliseconds elapsed since the start of the

application until the creation of the logging event. %c: Outputs the category of the logging event.

Example: For the category name "a.b.c", the pattern %c{2} will output "b.c". {2} means "output last two components of the dot-separated category name". If no {n} is there, full Category name is output by default.

%t: Outputs the name of the thread that generated the logging event. %x: Outputs the nested diagnostic context (NDC) associated with the thread that

generated the logging event. Useful when multiple clients are handled by separate threads such as in Java servlets.


Page 26

Conversion characters are (Continue…): %n: Outputs the platform-dependent newline character(s). Preferable to specifying "\n" or

"\r\n" etc. %%: Outputs a single percent sign.WARNING: The patterns below will slow down the execution of your program

somewhat. Avoid unless execution speed is not an issue. %d: Outputs the date of the logging event. The date conversion specifier may be

followed by a date format specifier enclosed between braces. Example: %d{HH:mm:ss,SSS} or %d{dd MMM yyyy HH:mm:ss,SSS}. If no date format specifier is given then ISO8601 format is assumed. The date format specifier admits the same syntax as the time pattern string of Java's SimpleDateFormat which is slow. For faster performance, use %d{ISO8601}, %d{ABSOLUTE}, %d{RELATIVE} (millisecs since program start, fastest) or %d{DATE} which use log4j's ISO8601DateFormat, AbsoluteTimeDateFormat, RelativeTimeDateFormat and DateTimeDateFormat date formatters respectively.


Page 27

Conversion characters are (Continue…): %l: Outputs source code location information. Shortcut for %C.%M(%F:%L). %C: Outputs the fully-qualified class name of the caller issuing the logging request.

Example: For the class name "org.apache.xyz.SomeClass", the pattern %C{1} will output "SomeClass". {1} means "output last one component of the fully-qualified class name". If no {n} is there, full class name is output by default.

%M: Outputs the method name where the logging request was issued. %F: Outputs the file name where the logging request was issued. %L: Outputs the line number from where the logging request was issued. -: To left-justify within a field. Default is to right-justify (pad on left).


Page 28

Pattern: %d{dd MM yyyy HH:mm:ss} %p %l: %m %n

This example will output: %d{dd MM yyyy HH:mm:ss} : 07 12 2006 09:25:02 (Date)%p: ERROR (Priority)%l: com.ing.canada.YourClass.yourMethod(filename.java:65) (source code location)%m: TEST ERROR (message)%n: (newline character)

PatternLayout - Example


Page 29

XMLLayout - org.apache.log4j.xml.XMLLayout

The output of the XMLLayout consists of a series of log4j:event elements as defined in the log4j.dtd. It does not output a complete well-formed XML file. The output is designed to be included as an external entity in a separate file to form a correct XML file.

For example, if abc is the name of the faile where the XMLLayout output goes, then a well-formed XML file would be:

<log4j:event logger="com.ing.canada.myPackage.MyClass" timestamp="1165519924224" level="FATAL" thread="Servlet.Engine.Transports : 0"> <log4j:message>

<![CDATA[TEST FATAL. debug]]> </log4j:message></log4j:event>


Page 30

HTMLLayout - org.apache.log4j.HTMLLayout

This layout outputs events in a HTML table.

<body bgcolor="#FFFFFF" topmargin="6" leftmargin="6"> <hr size="1" noshade> Log session start time Thu Dec 07 15:03:00 EST 2006 <table cellspacing="0" cellpadding="4" border="1" bordercolor="#224466" width="100%"> <tr> <th>Time</th><th>Thread</th><th>Level</th><th>Category</th> <th>File:Line</th><th>Message</th> </tr>

<tr> <td>16</td> <td title="Servlet.Engine.Transports : 0 thread">Servlet.Engine.Transports : 0</td> <td title="Level">FATAL</td> <td title="com.ing.canada.autoquote.filter.SessionAttributesFiltercategory"> com.ing.canada.autoquote.filter.SessionAttributesFilter </td> <td>SessionAttributesFilter.java:66</td> <td title="Message">TEST FATAL. debug</td> </tr>


Page 31

Layout Configuration Example

<layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/></layout>

<layout class="org.apache.log4j.xml.XMLLayout"><param name="LocationInfo" value="true" />

</layout>

<layout class="org.apache.log4j.HTMLLayout"><param name="LocationInfo" value="true" /><param name="Title" value=“Html Title" />

</layout>

ConvesionPattern: This is the string which controls formatting and consists of a mix of literal content and conversion specifiers.

LocationInfo: If the the option is set to true, then the file name and line number of the statement at the origin of the log statement will be output. Default is false.

Title: This option sets the document title of the generated HTML document.


Page 32



Page 33

FiltersAt some situation, You have to write logs to different outputs according to the level. How can it be done by simply configuration of Log4j?

By using LevelMatchFilter, LevelRangeFilter or StringMatchFilter.

You can define multiple filter for the same appender. But Keep in mind that when attaching multiple filters to the same appender, that if the statement fails one filter, it will pass down to the next. A denial by a filter does not necessarily mean that the message is thrown away. The message just fails that filter and goes onto the next one (except in the case of DenyAllFilter). Which is why it's always safest to have a "DenyAllFilter" at the bottom of the list to catch the stragglers.

Notes: Filter is not supported by PropertiesConfigurator, so if you want to configure it, just use the XML file instead.


Page 34

LevelMatchFilter

The filter admits two options LevelToMatch and AcceptOnMatch.LevelToMatch: TRACE, DEBUG, INFO, WARN, ERROR or FATALAcceptOnMatch: If acceptOnMatch is set to true (default) and the level match the criteria all

others filters will not be execute and the message will be accepted. Otherwise

the message is rejected and passed to the next filter.

<filter class="org.apache.log4j.varia.LevelMatchFilter"> <param name="LevelToMatch" value="INFO"/> <param name="AcceptOnMatch" value="true"/></filter>

Filter based on level matching.


Page 35

LevelRangeFilter

The filter admits three options LevelMin, LevelMax and AcceptOnMatch.LevelMin: TRACE, DEBUG, INFO, WARN, ERROR or FATAL

LevelMin: TRACE, DEBUG, INFO, WARN, ERROR or FATALAcceptOnMatch: If acceptOnMatch is set to true (default) and the level match the criteria all others filters will not be execute and the message will be accepted. Otherwise


<filter class="org.apache.log4j.varia.LevelRangeFilter"> <param name="LevelMin" value="DEBUG"/> <param name="LevelMax" value="ERROR"/> <param name="AcceptOnMatch" value="true"/></filter>

Filter based on level matching, which can be used to reject messages with priorities

outside a certain range (inclusive).


Page 36

StringMatchFilter

The filter admits two options StringToMatch and AcceptOnMatch.StringToMatch: String to find in the messageAcceptOnMatch: If acceptOnMatch is set to true (default) and the level match the criteria all

others filters will not be execute and the message will be accepted. Otherwise


<filter class="org.apache.log4j.varia.StringMatchFilter"> <param name="StringToMatch" value="1" /> <param name="AcceptOnMatch" value="true" /> </filter>

Filter based on string matching (Case sensitive).


Page 37

DenyAllFilter

You can add this filter to the end of a filter chain to switch from the default "accept all unless instructed otherwise" filtering behaviour to a "deny all unless instructed otherwise" behaviour.

<filter class="org.apache.log4j.varia.DenyAllFilter"/>

This filter drops all logging events.


Page 38

Log4j.xml

Debug: Probably the most important attribute for log4:configuration, setting it to "true" will print out information as the configuration file is read and used to configure the log4j environment. Very useful when trying to figure out why your configuration file is not doing what you expect.

Threshold: Set to off to disable all logging.

<!ELEMENT appender (errorHandler?, param*, layout?, filter*, appender-ref*)> <!ATTLIST log4j:configuration xmlns:log4j CDATA #FIXED "http://jakarta.apache.org/log4j/" threshold (all|debug|info|warn|error|fatal|off|null) "null“ debug (true|false|null) "null">


Page 39



Page 40

When the generation of your logging message takes a long time, you might want to check to see if it will ever make it to an appenderFunctions like isDebugEnabled() and isEnabledFor() on the Logger class allow you to test first (testing is very fast) and then generate the string and log it if you know the message will actually be logged.

You can use system properties in the log4j.xml by simply call ${VAR_NAME}. You can now configure runtime information like path/filename without changing your configuration file.

Tips

Technology

Presentation log4 j