xdocs/services/logging-service.xml - turbine-core - Git at Google

 <?xml version="1.0"?>

 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <document>

  <properties>
   <title>Turbine Services - Logging Service</title>
   <author email="jvanzyl@apache.org">Jason van Zyl</author>
   <author email="jon@latchkey.com">Jon S. Stevens</author>
   <author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
  </properties>

 <body>

 <section name="Logging Service">

 <p>
 Turbine's logging service is exceptionally powerful. And it was
 proprietary. So we ripped it out post Turbine 2.2 and replaced it with
 <a href="http://commons.apache.org/logging">commons-logging</a>
  backed by <a href="http://logging.apache.org/log4j/">Log4j</a>. You
 configure the new logging with a Log4j.properties file which can be
 configured with the log4j.file property in TurbineResource.properties:
 </p>

 </section>

 <section name="Configuration">

 <source><![CDATA[
 # -------------------------------------------------------------------
 #
 #  L O G 4 J - L O G G I N G
 #
 # -------------------------------------------------------------------

 # Configure log4j from the log4j properties file
 log4j.file = WEB-INF/conf/Log4j.properties
 ]]></source>

 <p>
 If you use another logging system and don't want to configure
 the log4j subsystem, you can use the empty string or &quot;none&quot; as
 <code>log4j.file</code> parameter to turn it off.
 </p>

 <source><![CDATA[
 # -------------------------------------------------------------------
 #
 #  L O G 4 J - L O G G I N G
 #
 # -------------------------------------------------------------------

 # Do not configure Log4J logging.
 log4j.file = none
 ]]></source>

 </section>

 <section name="Log4j Configuration">

 <p>
 To use the Logging system, all you need to do is configure some
 loggers in your Log4j.properties. This is an example how to do it:
 </p>

 <source><![CDATA[
 # ------------------------------------------------------------------------
 #
 # Logging Configuration
 #
 # $Id$
 #
 # ------------------------------------------------------------------------

 #
 # If we don't know the logging facility, put it into the
 # turbine.log
 #
 log4j.rootLogger = INFO, turbine

 #
 # Turbine goes into Turbine Log
 #
 log4j.category.org.apache.turbine = INFO, turbine
 log4j.additivity.org.apache.turbine = false

 #
 # Torque has its own log file
 #
 log4j.category.org.apache.torque = INFO, torque
 log4j.additivity.org.apache.torque = false

 #
 # Velocity Logfile
 #
 log4j.category.velocity = INFO, velocity
 log4j.additivity.velocity = false

 #
 # Scheduler Category
 #
 log4j.category.scheduler = INFO, scheduler
 log4j.additivity.scheduler = false

 ########################################################################
 #
 # Logfile definitions
 #
 ########################################################################

 #
 # turbine.log
 #
 log4j.appender.turbine = org.apache.log4j.FileAppender
 log4j.appender.turbine.file = ${applicationRoot}/logs/turbine.log
 log4j.appender.turbine.layout = org.apache.log4j.PatternLayout
 log4j.appender.turbine.layout.conversionPattern = %d [%t] %-5p %c - %m%n
 log4j.appender.turbine.append = false

 #
 # torque.log
 #
 log4j.appender.torque = org.apache.log4j.FileAppender
 log4j.appender.torque.file = ${applicationRoot}/logs/torque.log
 log4j.appender.torque.layout = org.apache.log4j.PatternLayout
 log4j.appender.torque.layout.conversionPattern = %d [%t] %-5p %c - %m%n
 log4j.appender.torque.append = false

 #
 # Scheduler Output
 #
 log4j.appender.scheduler = org.apache.log4j.FileAppender
 log4j.appender.scheduler.file = ${applicationRoot}/logs/scheduler.log
 log4j.appender.scheduler.layout = org.apache.log4j.PatternLayout
 log4j.appender.scheduler.layout.conversionPattern = %d [%t] %-5p %c - %m%n
 log4j.appender.scheduler.append = false

 #
 # Velocity gets configured to write its output onto the velocity
 # category.
 #
 log4j.appender.velocity = org.apache.log4j.FileAppender
 log4j.appender.velocity.file = ${applicationRoot}/logs/velocity.log
 log4j.appender.velocity.layout = org.apache.log4j.PatternLayout
 log4j.appender.velocity.layout.conversionPattern = %d [%t] %-5p %c - %m%n
 log4j.appender.velocity.append = false
 ]]></source>

 <p>
 Sub Projects like Torque and Velocity get either configured correctly
 by their Services (Velocity by the VelocityService) or already know
 about commons-logging (Torque).
 </p>

 </section>

 <section name="Usage">

 <p>
 You use the logging by accessing it via commons-logging. This is an
 example how to do it.
 </p>

 <source><![CDATA[
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;

 // Provide a logger with the class name as category. This
 // is recommended because you can split your log files
 // by packages in the Log4j.properties. You can provide
 // any other category name here, though.
 private Log log = LogFactory.getLog(this.getClass());

 log.info("this message would go to any facility configured to use the " + this.getClass().getName() + " Facility");
 ]]></source>

 <p>
 It is recommended for performance reasons that you provide a class wide logger like this:
 </p>

 <source><![CDATA[
 package foo;

 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;

 public class Bar
 {
     // Classwide static logger
     private static Log log = LogFactory.getLog(Bar.class);
 .
 .
 .
 }
 ]]></source>

 </section>
 </body>
 </document>
	<?xml version="1.0"?>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<document>

	<properties>
	<title>Turbine Services - Logging Service</title>
	<author email="jvanzyl@apache.org">Jason van Zyl</author>
	<author email="jon@latchkey.com">Jon S. Stevens</author>
	<author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
	</properties>

	<body>

	<section name="Logging Service">

	<p>
	Turbine's logging service is exceptionally powerful. And it was
	proprietary. So we ripped it out post Turbine 2.2 and replaced it with
	<a href="http://commons.apache.org/logging">commons-logging</a>
	backed by <a href="http://logging.apache.org/log4j/">Log4j</a>. You
	configure the new logging with a Log4j.properties file which can be
	configured with the log4j.file property in TurbineResource.properties:
	</p>

	</section>

	<section name="Configuration">

	<source><![CDATA[
	# -------------------------------------------------------------------
	#
	# L O G 4 J - L O G G I N G
	#
	# -------------------------------------------------------------------

	# Configure log4j from the log4j properties file
	log4j.file = WEB-INF/conf/Log4j.properties
	]]></source>

	<p>
	If you use another logging system and don't want to configure
	the log4j subsystem, you can use the empty string or "none" as
	<code>log4j.file</code> parameter to turn it off.
	</p>

	<source><![CDATA[
	# -------------------------------------------------------------------
	#
	# L O G 4 J - L O G G I N G
	#
	# -------------------------------------------------------------------

	# Do not configure Log4J logging.
	log4j.file = none
	]]></source>

	</section>

	<section name="Log4j Configuration">

	<p>
	To use the Logging system, all you need to do is configure some
	loggers in your Log4j.properties. This is an example how to do it:
	</p>

	<source><![CDATA[
	# ------------------------------------------------------------------------
	#
	# Logging Configuration
	#
	# $Id$
	#
	# ------------------------------------------------------------------------

	#
	# If we don't know the logging facility, put it into the
	# turbine.log
	#
	log4j.rootLogger = INFO, turbine

	#
	# Turbine goes into Turbine Log
	#
	log4j.category.org.apache.turbine = INFO, turbine
	log4j.additivity.org.apache.turbine = false

	#
	# Torque has its own log file
	#
	log4j.category.org.apache.torque = INFO, torque
	log4j.additivity.org.apache.torque = false

	#
	# Velocity Logfile
	#
	log4j.category.velocity = INFO, velocity
	log4j.additivity.velocity = false

	#
	# Scheduler Category
	#
	log4j.category.scheduler = INFO, scheduler
	log4j.additivity.scheduler = false

	########################################################################
	#
	# Logfile definitions
	#
	########################################################################

	#
	# turbine.log
	#
	log4j.appender.turbine = org.apache.log4j.FileAppender
	log4j.appender.turbine.file = ${applicationRoot}/logs/turbine.log
	log4j.appender.turbine.layout = org.apache.log4j.PatternLayout
	log4j.appender.turbine.layout.conversionPattern = %d [%t] %-5p %c - %m%n
	log4j.appender.turbine.append = false

	#
	# torque.log
	#
	log4j.appender.torque = org.apache.log4j.FileAppender
	log4j.appender.torque.file = ${applicationRoot}/logs/torque.log
	log4j.appender.torque.layout = org.apache.log4j.PatternLayout
	log4j.appender.torque.layout.conversionPattern = %d [%t] %-5p %c - %m%n
	log4j.appender.torque.append = false

	#
	# Scheduler Output
	#
	log4j.appender.scheduler = org.apache.log4j.FileAppender
	log4j.appender.scheduler.file = ${applicationRoot}/logs/scheduler.log
	log4j.appender.scheduler.layout = org.apache.log4j.PatternLayout
	log4j.appender.scheduler.layout.conversionPattern = %d [%t] %-5p %c - %m%n
	log4j.appender.scheduler.append = false

	#
	# Velocity gets configured to write its output onto the velocity
	# category.
	#
	log4j.appender.velocity = org.apache.log4j.FileAppender
	log4j.appender.velocity.file = ${applicationRoot}/logs/velocity.log
	log4j.appender.velocity.layout = org.apache.log4j.PatternLayout
	log4j.appender.velocity.layout.conversionPattern = %d [%t] %-5p %c - %m%n
	log4j.appender.velocity.append = false
	]]></source>

	<p>
	Sub Projects like Torque and Velocity get either configured correctly
	by their Services (Velocity by the VelocityService) or already know
	about commons-logging (Torque).
	</p>

	</section>

	<section name="Usage">

	<p>
	You use the logging by accessing it via commons-logging. This is an
	example how to do it.
	</p>

	<source><![CDATA[
	import org.apache.commons.logging.Log;
	import org.apache.commons.logging.LogFactory;

	// Provide a logger with the class name as category. This
	// is recommended because you can split your log files
	// by packages in the Log4j.properties. You can provide
	// any other category name here, though.
	private Log log = LogFactory.getLog(this.getClass());

	log.info("this message would go to any facility configured to use the " + this.getClass().getName() + " Facility");
	]]></source>

	<p>
	It is recommended for performance reasons that you provide a class wide logger like this:
	</p>

	<source><![CDATA[
	package foo;

	import org.apache.commons.logging.Log;
	import org.apache.commons.logging.LogFactory;

	public class Bar
	{
	// Classwide static logger
	private static Log log = LogFactory.getLog(Bar.class);
	.
	.
	.
	}
	]]></source>

	</section>
	</body>
	</document>