user-guide/src/serviceability.xml - virgo/org.eclipse.virgo.documentation - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <chapter id="serviceability">
   <title>Serviceability</title>

 <para>
 	@tomcat.product.name@ supports two kinds of logging: <emphasis>Event Logging</emphasis> and <emphasis>Trace logging</emphasis> which is usually referred
 	to simply as <emphasis>Logging</emphasis>. The difference between Event Logging and Logging is explained below, but both are configured in the
 	<literal>serviceability.xml</literal> file in the <literal>config</literal> directory. This file takes the form of a Logback configuration, @tomcat.product.name.short@
 	uses a Logback implementation behind the SLF4J logging interface.
 	<para>
 		For a description of the syntax and facilities provided by <literal>serviceability.xml</literal>
 		see the <emphasis>Logback</emphasis> documentation (referenced in <xref linkend="furtherreading"/>).
 	</para>
 </para>

    <section id="serviceability-info-log">
       <title>Event logging</title>
       <para>
         Event logging records important events in @tomcat.product.name@. Each event is logged to
  		an event log file and is accompanied by a code enclosed in angle brackets.
  		An example is shown below:
 <screen>
 [2010-10-25 16:20:45.897] system-artifacts             &lt;TC0010I&gt; Creating HTTP/1.1 connector with scheme http on port 8080.
 </screen>
 		(For a description of the log code syntax, see <xref linkend="log-codes"/>.)
         The format of event log messages is fully configurable.
       </para>
 		<para>
 		    By default, event log messages are stored in <literal>$SERVER_HOME/serviceability/eventlogs/eventlog.log</literal>.
       	</para>
 		<para>
 			The default behaviour is that, once <literal>eventlog.log</literal> reaches a 10Mb limit, it rolls into a series of files named
 			<literal>eventlog_</literal><emphasis>i</emphasis><literal>.log</literal> where <emphasis>i</emphasis> ranges from 1 to 4, and event logging continues in
 			a new <literal>eventlog.log</literal> file.
 		</para>
     </section>

     <section id="serviceability-info-trace">
       <title>(Trace) Logging</title>
       <para>
 	    The @tomcat.product.name@&rsquo;s (trace) logging support serves two main purposes:
 	    <itemizedlist>
 		  <listitem>
 		    It provides global trace files that capture high-volume information regarding the @tomcat.product.name@&rsquo;s internal events.
 		    The files are intended for use by support personnel to diagnose runtime problems.
 	      </listitem>
 	      <listitem>
 			It provides application trace files that contain application-generated output. This includes output generated using popular logging and
 			tracing APIs including the OSGi LogService, as well as output generated by calls to <literal>System.out</literal> and <literal>System.err</literal>.
 			These files are intended for use by application developers and system administrators. An application is defined as a scope so a single bundle will
 			not get it's own log file unless it is a Web application Bundle or is included in a scoped plan or a par file.
 		  </listitem>
 		</itemizedlist>
         </para>
         <para>
 			By default, the @tomcat.product.name.short@ trace file is called <literal>$SERVER_HOME/serviceability/logs/log.log</literal>,
 			and, again by default, the application trace files are called <literal>$SERVER_HOME/serviceability/logs/</literal><emphasis>application_name</emphasis>
 			<literal>/log.log</literal>, where <emphasis>application_name</emphasis> is automatically set by @tomcat.product.name.short@ for each application artifact
 			installed and run (it is a combination of the artifact name and the version).
         </para>
 		<para>
 			The default behaviour of these trace files is that, once <literal>log.log</literal> reaches a 10Mb limit, it rolls into a series of files named
 			<literal>log_</literal><emphasis>i</emphasis><literal>.log</literal> where <emphasis>i</emphasis> ranges from 1 to 4, and logging continues in
 			a new <literal>log.log</literal> file.
 		</para>
       <para>
 		Entries in trace files are by default of the form &lt;timestamp&gt; &lt;thread-name&gt; &lt;source&gt; &lt;level&gt; &lt;entry-text&gt;. For example:
 		<screen>
 [2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080
 	    </screen>
         although this format is completely determined by the Logback configuration file <literal>serviceability.xml</literal>.
       </para>
 	  <section id="serviceability-info-trace-app">
 		<title>Application Output</title>
 		<para>
 			@tomcat.product.name@ provides advanced support for capturing and tracing application-generated output by automatically separating trace output on a
 			per-application basis and will also capture any <literal>System.out</literal> and <literal>System.err</literal> output.
 		</para>
 		<section id="per-application-trace">
 			<title>Per-application trace</title>
 			<para>
 				@tomcat.product.name@ uses SLF4J interfaces to Logback, and the root logger (by default) captures all logging output
 				and appends it to the application-specific trace files as described above.
 				To modify this, define application-specific loggers in the <literal>serviceability.xml</literal> file in the normal way.
 			</para>
         </section>
         <section id="sysout-and-syserr">
 	      <title>System.out and System.err</title>
 		  <para>
             <literal>System.out</literal> and <literal>System.err</literal> output from applications is, by default, captured in the
             application&rsquo;s trace file.
             This happens because the output streams are intercepted and written to the loggers named
             <literal>System.out</literal> and <literal>System.err</literal> respectively.
 			Since there are no explicit loggers defined with these names in the <literal>serviceability.xml</literal> file,
 			this output is logged by the root logger (which captures <literal>INFO</literal> level and above).
           </para>
 		  <para>
 			The capture of <literal>System.out</literal> and <literal>System.err</literal> output is configured in the
 			<literal>config/org.eclipse.virgo.medic.properties</literal> file by the <literal>log.wrapSysOut</literal> and
 			<literal>log.wrapSysErr</literal> properties. By default the properties have a value of <literal>true</literal>
 			and capture is enabled. Capture can be disabled by configuring the properties with a value of <literal>false</literal>.
 		  </para>
           <para>
             The trace entries for <literal>System.out</literal> and <literal>System.err</literal>
 			output are of the form:
 		    <screen>
 [2008-05-16 09:28:45.874] server-tomcat-thread-1 System.out Hello world!
 [2008-05-16 09:28:45.874] server-tomcat-thread-1 System.err Hello world!
 			</screen>
 			The third column indicates where the output came from (<literal>System.out</literal> or <literal>System.err</literal>).
 		  </para>
 		  <para>
 		  To over-ride this behaviour, simply define explicit loggers named <literal>System.out</literal>
 		  and/or <literal>System.err</literal> in the configuration file to send this output to an appender of your choice.
 		  Be aware that all applications&rsquo; output streams will be caught by these loggers, and that a sifting appender might be useful to separate them.
 		  </para>
 		</section>
 	  </section>
     </section>
     <section id="serviceability-info-dump">
       <title>Service Dumps</title>
       <para>
         A service dump is triggered when one of the following events
         occurs:
       </para>
       <orderedlist numeration="arabic">
         <listitem>
           <para>
             A failure is detected in the @tomcat.product.name@ code, or
           </para>
         </listitem>
         <listitem>
           <para>
             a thread deadlock is detected.
           </para>
         </listitem>
       </orderedlist>
       <para>
         A service dump contains a snapshot of all the important state from
         the running @tomcat.product.name@ instance. This snapshot is not intended
         for end user consumption but is useful for service personnel.
       </para>
       <para>
         By default, service dumps are created in
         <literal>$SERVER_HOME/serviceability/dump</literal>.
       </para>
     </section>
 </chapter>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
	<chapter id="serviceability">
	<title>Serviceability</title>

	<para>
	@tomcat.product.name@ supports two kinds of logging: <emphasis>Event Logging</emphasis> and <emphasis>Trace logging</emphasis> which is usually referred
	to simply as <emphasis>Logging</emphasis>. The difference between Event Logging and Logging is explained below, but both are configured in the
	<literal>serviceability.xml</literal> file in the <literal>config</literal> directory. This file takes the form of a Logback configuration, @tomcat.product.name.short@
	uses a Logback implementation behind the SLF4J logging interface.
	<para>
	For a description of the syntax and facilities provided by <literal>serviceability.xml</literal>
	see the <emphasis>Logback</emphasis> documentation (referenced in <xref linkend="furtherreading"/>).
	</para>
	</para>

	<section id="serviceability-info-log">
	<title>Event logging</title>
	<para>
	Event logging records important events in @tomcat.product.name@. Each event is logged to
	an event log file and is accompanied by a code enclosed in angle brackets.
	An example is shown below:
	<screen>
	[2010-10-25 16:20:45.897] system-artifacts <TC0010I> Creating HTTP/1.1 connector with scheme http on port 8080.
	</screen>
	(For a description of the log code syntax, see <xref linkend="log-codes"/>.)
	The format of event log messages is fully configurable.
	</para>
	<para>
	By default, event log messages are stored in <literal>$SERVER_HOME/serviceability/eventlogs/eventlog.log</literal>.
	</para>
	<para>
	The default behaviour is that, once <literal>eventlog.log</literal> reaches a 10Mb limit, it rolls into a series of files named
	<literal>eventlog_</literal><emphasis>i</emphasis><literal>.log</literal> where <emphasis>i</emphasis> ranges from 1 to 4, and event logging continues in
	a new <literal>eventlog.log</literal> file.
	</para>
	</section>

	<section id="serviceability-info-trace">
	<title>(Trace) Logging</title>
	<para>
	The @tomcat.product.name@’s (trace) logging support serves two main purposes:
	<itemizedlist>
	<listitem>
	It provides global trace files that capture high-volume information regarding the @tomcat.product.name@’s internal events.
	The files are intended for use by support personnel to diagnose runtime problems.
	</listitem>
	<listitem>
	It provides application trace files that contain application-generated output. This includes output generated using popular logging and
	tracing APIs including the OSGi LogService, as well as output generated by calls to <literal>System.out</literal> and <literal>System.err</literal>.
	These files are intended for use by application developers and system administrators. An application is defined as a scope so a single bundle will
	not get it's own log file unless it is a Web application Bundle or is included in a scoped plan or a par file.
	</listitem>
	</itemizedlist>
	</para>
	<para>
	By default, the @tomcat.product.name.short@ trace file is called <literal>$SERVER_HOME/serviceability/logs/log.log</literal>,
	and, again by default, the application trace files are called <literal>$SERVER_HOME/serviceability/logs/</literal><emphasis>application_name</emphasis>
	<literal>/log.log</literal>, where <emphasis>application_name</emphasis> is automatically set by @tomcat.product.name.short@ for each application artifact
	installed and run (it is a combination of the artifact name and the version).
	</para>
	<para>
	The default behaviour of these trace files is that, once <literal>log.log</literal> reaches a 10Mb limit, it rolls into a series of files named
	<literal>log_</literal><emphasis>i</emphasis><literal>.log</literal> where <emphasis>i</emphasis> ranges from 1 to 4, and logging continues in
	a new <literal>log.log</literal> file.
	</para>
	<para>
	Entries in trace files are by default of the form <timestamp> <thread-name> <source> <level> <entry-text>. For example:
	<screen>
	[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080
	</screen>
	although this format is completely determined by the Logback configuration file <literal>serviceability.xml</literal>.
	</para>
	<section id="serviceability-info-trace-app">
	<title>Application Output</title>
	<para>
	@tomcat.product.name@ provides advanced support for capturing and tracing application-generated output by automatically separating trace output on a
	per-application basis and will also capture any <literal>System.out</literal> and <literal>System.err</literal> output.
	</para>
	<section id="per-application-trace">
	<title>Per-application trace</title>
	<para>
	@tomcat.product.name@ uses SLF4J interfaces to Logback, and the root logger (by default) captures all logging output
	and appends it to the application-specific trace files as described above.
	To modify this, define application-specific loggers in the <literal>serviceability.xml</literal> file in the normal way.
	</para>
	</section>
	<section id="sysout-and-syserr">
	<title>System.out and System.err</title>
	<para>
	<literal>System.out</literal> and <literal>System.err</literal> output from applications is, by default, captured in the
	application’s trace file.
	This happens because the output streams are intercepted and written to the loggers named
	<literal>System.out</literal> and <literal>System.err</literal> respectively.
	Since there are no explicit loggers defined with these names in the <literal>serviceability.xml</literal> file,
	this output is logged by the root logger (which captures <literal>INFO</literal> level and above).
	</para>
	<para>
	The capture of <literal>System.out</literal> and <literal>System.err</literal> output is configured in the
	<literal>config/org.eclipse.virgo.medic.properties</literal> file by the <literal>log.wrapSysOut</literal> and
	<literal>log.wrapSysErr</literal> properties. By default the properties have a value of <literal>true</literal>
	and capture is enabled. Capture can be disabled by configuring the properties with a value of <literal>false</literal>.
	</para>
	<para>
	The trace entries for <literal>System.out</literal> and <literal>System.err</literal>
	output are of the form:
	<screen>
	[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.out Hello world!
	[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.err Hello world!
	</screen>
	The third column indicates where the output came from (<literal>System.out</literal> or <literal>System.err</literal>).
	</para>
	<para>
	To over-ride this behaviour, simply define explicit loggers named <literal>System.out</literal>
	and/or <literal>System.err</literal> in the configuration file to send this output to an appender of your choice.
	Be aware that all applications’ output streams will be caught by these loggers, and that a sifting appender might be useful to separate them.
	</para>
	</section>
	</section>
	</section>
	<section id="serviceability-info-dump">
	<title>Service Dumps</title>
	<para>
	A service dump is triggered when one of the following events
	occurs:
	</para>
	<orderedlist numeration="arabic">
	<listitem>
	<para>
	A failure is detected in the @tomcat.product.name@ code, or
	</para>
	</listitem>
	<listitem>
	<para>
	a thread deadlock is detected.
	</para>
	</listitem>
	</orderedlist>
	<para>
	A service dump contains a snapshot of all the important state from
	the running @tomcat.product.name@ instance. This snapshot is not intended
	for end user consumption but is useful for service personnel.
	</para>
	<para>
	By default, service dumps are created in
	<literal>$SERVER_HOME/serviceability/dump</literal>.
	</para>
	</section>
	</chapter>