13.3 Configuring Serviceability and Diagnostics

The serviceability features of Virgo allow you to gather and view data and information that you can then use to diagnose problems and failures. Serviceability data includes:

For additional conceptual information about the serviceability subsystem, see Chapter 11, Serviceability and Diagnostics.

The org.eclipse.virgo.medic.properties File

The $SERVER_HOME/configuration/org.eclipse.virgo.medic.properties file configures Virgo service dumps and whether you want to capture System.out and System.err output to your application's trace file.

The following table describes the properties you can include in the $SERVER_HOME/configuration/org.eclipse.virgo.medic.properties file. This file configures serviceability properties that Virgo includes in addition to those supplied by the Logback, configured in the serviceability.xml file.

Table 13.4. Serviceability Properties

PropertyDescription
dump.root.directorySpecifies the directory to which Virgo writes the service dumps. The directory name is relative to $SERVER_HOME.
log.wrapSysOutSpecifies whether you want to capture System.out output from your applications to the application trace file. The output is logged by Virgo's root logger, which captures INFO level and above.

Valid values for this property are true to capture System.out output, or false to disable the capture.

For more information, see System.out and System.err.

log.wrapSysErrSpecifies whether you want to capture System.err output from your applications to the application trace file. The output is logged by Virgo's root logger, which captures INFO level and above.

Valid values for this property are true to capture System.err output, or false to disable the capture.

For more information, see System.out and System.err.

log.jul.consoleHandlerSpecifies whether you want to use the ConsoleHandler of Java Util Logging. The default JVM configuration uses the handler to write logs to System.err.

Valid values for this property are true to enable ConsoleHandler output, or false to disable it. The default value is false.

For more information, see Java Logging Overview.


The serviceability.xml File

Logging support in Virgo is based on Logback, which is a successor of the log4j project. The Logback logging framework is faster, more reliable, and easier to use than log4j and certain other logging systems.

You configure logging for Virgo using the $SERVER_HOME/configuration/serviceability.xml file. This file is the standard Logback logback.xml or logback-test.xml configuration file, but renamed for Virgo.

The following listing shows the default serviceability.xml file in a freshly-installed Virgo; see the text after the listing for a brief overview of the file:

<configuration>

	<jmxConfigurator />

	<contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>

	<appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender">
		<discriminator>
			<Key>applicationName</Key>
			<DefaultValue>virgo-server</DefaultValue>
		</discriminator>
		<sift>
			<appender name="${applicationName}_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
				<file>serviceability/logs/${applicationName}/log.log</file>
				<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
					<FileNamePattern>serviceability/logs/${applicationName}/log_%i.log</FileNamePattern>
					<MinIndex>1</MinIndex>
					<MaxIndex>4</MaxIndex>
				</rollingPolicy>
				<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
					<MaxFileSize>10MB</MaxFileSize>
				</triggeringPolicy>
				<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
					<Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
				</encoder>
			</appender>
		</sift>
	</appender>

	<appender name="LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
		<file>serviceability/logs/log.log</file>
		<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
			<FileNamePattern>serviceability/logs/log_%i.log</FileNamePattern>
			<MinIndex>1</MinIndex>
			<MaxIndex>4</MaxIndex>
		</rollingPolicy>
		<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
			<MaxFileSize>10MB</MaxFileSize>
		</triggeringPolicy>
		<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
			<Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-5level %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
		</encoder>
	</appender>

	<appender name="EVENT_LOG_STDOUT" class="org.eclipse.virgo.medic.log.logback.ReroutingAwareConsoleAppender">
		<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
			<Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread &lt;%X{medic.eventCode}&gt; %msg %ex%n</Pattern>
		</encoder>
	</appender>

	<appender name="EVENT_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
		<file>serviceability/eventlogs/eventlog.log</file>
		<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
			<FileNamePattern>serviceability/eventlogs/eventlog_%i.log</FileNamePattern>
			<MinIndex>1</MinIndex>
			<MaxIndex>4</MaxIndex>
		</rollingPolicy>
		<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
			<MaxFileSize>10MB</MaxFileSize>
		</triggeringPolicy>
		<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
			<Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread &lt;%X{medic.eventCode}&gt; %msg %ex%n</Pattern>
		</encoder>
	</appender>

	<logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.localized">
		<appender-ref ref="EVENT_LOG_STDOUT" />
		<appender-ref ref="EVENT_LOG_FILE" />
	</logger>

	<logger level="INFO" additivity="false" name="org.eclipse.virgo.medic.eventlog.default">
		<appender-ref ref="SIFTED_LOG_FILE" />
		<appender-ref ref="LOG_FILE" />
	</logger>

	<root level="INFO">
		<appender-ref ref="SIFTED_LOG_FILE" />
		<appender-ref ref="LOG_FILE" />
	</root>

</configuration>

Logback allows Virgo to use logger, appender, and encoder (layout) objects to log messages according to message type and level and to format these messages and define where they are written. The default serviceability.xml file shown above includes four appenders and three loggers (two user and one root.)

The main information to get from this file is that Virgo writes log messages to four different locations that map to the four appenders:

  • The jmxConfigurator provides a possibility to configure logback via JMX. For more information see JMX Configurator documentation.

  • The contextListener propagates the changes made to the levels of logback loggers to Java Util Logging (JUL). For more information see LevelChangePropagator documentation.

  • The SIFTED_LOG_FILE appender logs both global and application-specific messages to the $SERVER_HOME/serviceability/logs/applicationName/log.log file, where applicationName refers to the name of the application. The log messages for Virgo itself are logged to the $SERVER_HOME/serviceability/logs/virgo-server/log.log file. Because this appender creates different log files for each application, it is called a sifting appender.

    The default behaviour of these trace files is that, once log.log reaches a 10Mb limit, it rolls into a series of files named log_i.log where i ranges from 1 to 4, and logging continues in a new log.log file. This is called its rolling policy.

    The <Pattern> element defines the format of each log message; messages include the timestamp, the thread that generated the log message, the context-specific event code, and a stack trace of the exception, if any. For example:

    [2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080

  • The LOG_FILE appender is very similar to the first one, but it logs all log messages to the $SERVER_HOME/serviceability/log/log.log file rather than sifting application-specific messages to their own log file. The rolling policy and message format for this appender is similar to that of the SIFTED_LOG_FILE appender.

  • The EVENT_LOG_STDOUT appender does not log messages to a file, but rather to the console window from which you started Virgo. For example:

    [2010-10-25 16:20:49.367] Thread-3 <WE0000I> Starting web bundle 'org.eclipse.virgo.apps.admin.web' version '2.1.0.RELEASE' with context path '/admin'.

  • The EVENT_LOG_FILE appender logs only important events to the $SERVER_HOME/serviceability/eventlogs/eventlog.log file, and thus the volume of information is much lower than with the first two appenders. The rolling policy for the event log is the same as with the first two appenders, but the format of the messages is similar to that of the EVENT_LOG_STDOUT appender.

The loggers and root logger specify the level of log that is written for each of the referenced appenders.

Typically, the default logging configuration as specified by the serviceability.xml file is adequate for all Virgo environments. However, if you want to customize logging further, you can edit this file as well as the org.eclipse.virgo.medic.properties. See the logback documentation for detailed information about the architecture and the configuration of Logback.