BeJUG

Logging rules

Overview

Table B.2. Logging rules

Rules
LOG_001: Retrieve A Logger Based On The Fully Qualified Package And Class Name
LOG_002: Declare A Logger Instance private final static
LOG_003: Log A Catched Exception
LOG_004: Use A Correct FileHandler Log Name
LOG_005: Use The Log Level SEVERE Only For Non Recoverable Problems
LOG_006: Use The Log Level WARNING Only For Recoverable Problems
LOG_007: Use The Log Level INFO Only For Information Logs
LOG_008: Use The Log Level CONFIG Only For Configuration Problems

LOG_001: Retrieve A Logger Based On The Fully Qualified Package And Class Name

When retrieving a Logger the name should be the fully qualified package and class name. The easiest way to retrieve this information is by calling the getName method on the class reference.

WRONG

package be.vlaanderen.myproject.mypackage; 

import java.util.logging.Logger; 

public class Foo { 
    private static final Logger logger = Logger.getLogger("example"); 
    // ... 
}

RIGHT

package be.vlaanderen.myproject.mypackage; 

import java.util.logging.Logger; 

public class Foo { 
    private static final Logger logger = Logger.getLogger(Foo.class.getName()); 
    // ... }

LOG_002: Declare A Logger Instance private final static

A Logger instance should be declared private static final

WRONG

package be.vlaanderen.myproject.mypackage; 

import java.util.logging.Logger; 

public class Foo { 
    public Logger logger = Logger.getLogger(Foo.class.getName()); 
    // ... 
}

RIGHT

package be.vlaanderen.myproject.mypackage; 

import java.util.logging.Logger; 

public class Foo { 
    private static final Logger logger = Logger.getLogger(Foo.class.getName()); 
    // ... 
}

LOG_003: Log A Caught Exception

A caught exception must be reported using the logging API.

WRONG

public class Foo {
	public void bar(Message msg) {
		String txtMessage = null;

		try {
			txtMessage = ((TextMessage) msg).getText();
			helperMethod(txtMessage);
		} catch (JMSException e) {
			e.printStackTrace();
		}
	}
}

RIGHT

public class Foo {
	public void bar(Message msg) {
		String txtMessage = null;
		try {
			txtMessage = ((TextMessage) msg).getText();
			helperMethod(txtMessage);
		} catch (JMSException e) {
			logger.log(Level.WARNING, "JMS Problem", e);
		}
	}
}

LOG_004: Use A Correct FileHandler Log Name

The naming convention for the log file, when using the logging FileHandler class, should be %h/project_name%u.log. %h is the user.home system property and %u is a unique rotating number when the limit size of the log file is reached.

RIGHT

/** Initialize the logging API here and use it for any std. error output */
private static final Logger logger = Logger.getLogger(Foo.class.getName());

static {
	FileHandler fileHandler = null;
	try {
		fileHandler = new FileHandler("%h" + File.separator
				+ "guidelines%u.log");
	} catch (SecurityException e) {
		logger.log(Level.SEVERE, "Security Problem", e);
	} catch (IOException e) {
		logger.log(Level.CONFIG, "IO Problem", e);
	}
	logger.addHandler(fileHandler);
}

public static void main(String[] args) {
	logger.info("info log message");
}

The above example will create a guidelines0.log file in the user home directory with following data:

<?xml version="1.0" encoding="windows-1252" standalone="no"?>
<!DOCTYPE log SYSTEM "logger.dtd">
<log>
	<record>
		<date>2003-10-22T11:48:37</date>
		<millis>1066816117500</millis>
		<sequence>0</sequence>
		<logger>be.vlaanderen.examples.Foo</logger>
		<level>INFO</level>
		<class>be.vlaanderen.examples.Foo</class>
		<method>main</method>
		<thread>10</thread>
		<message>info log message</message>
	</record>
</log>

LOG_005: Use The Log Level SEVERE Only For Non Recoverable Problems

The log level SEVERE should be used for non-recoverable problems or runtime exceptions.

WRONG

try { 
	// ... 
} catch (SecurityException e) { 
	logger.log(Level.WARNING, "Security Problem", e); 
}

RIGHT

try { 
	// ... 
} catch (SecurityException e) { 
	logger.log(Level.SEVERE, "Security Problem", e); 
}

LOG_006: Use The Log Level WARNING Only For Recoverable Problems

The log level WARNING should be used for recoverable problems or checked exceptions.

WRONG

try { 
	// ... 
} catch (JMSException e) { 
	logger.info("JMS Problem" + e);
}

RIGHT

try { 
	// ... 
} catch (JMSException e) { 
	logger.log(Level.WARNING, "JMS Problem...", e);
}

LOG_007: Use The Log Level INFO Only For Information Logs

The log level INFO should be used for informational logs.

RIGHT

try { 
	logger.info("got here"); 
} catch (JMSException e) { 
	logger.log(Level.WARNING, "JMS Problem", e); 
}

LOG_008: Use The Log Level CONFIG Only For Configuration Problems

The log level CONFIG should be used for configuration messages or related problems.

WRONG

static {
	FileHandler fileHandler = null;
	
	try {
		fileHandler = new FileHandler("%h" + File.separator
				+ "guidelines%u.log");
	} catch (SecurityException e) {
		logger.log(Level.SEVERE, "Security Problem", e);
	} catch (IOException e) {
		logger.log(Level.INFO, "IO Problem", e);
	}
	
	logger.addHandler(fileHandler);
}

RIGHT

static {
	FileHandler fileHandler = null;
	
	try {
		fileHandler = new FileHandler("%h" + File.separator
				+ "guidelines%u.log");
	} catch (SecurityException e) {
		logger.log(Level.SEVERE, "Security Problem", e);
	} catch (IOException e) {
		logger.log(Level.CONFIG, "IO Problem", e);
	}
	
	logger.addHandler(fileHandler);
}