9.2 Configuring Serviceability

9.2 Configuring Serviceability
Prev	9. Configuring the SpringSource dm Server	Next

The serviceability sub-system of dm Server allows you to gather and view data and information that you can then use to diagnose problems and failures. Serviceability includes data from:

Service dumps: Contain a snapshot of all the important state from the running dm Server instance when an internal failure or thread deadlock is detected.
You configure service dumps for SpringSource dm Server using the com.springsource.medic.properties file in the SERVER_HOME/config directory. This file also includes some additional logging configuration.
Event logs and server/application logging (previously called tracing): Logging support in dm Server is based on Logback. This means that you now have complete control over the format of log output and have the complete range of Logback's appenders available for your use.
You configure logging for SpringSource dm Server using the serviceability.xml file in the SERVER_HOME/config directory. This file is essentially the Logback logback.xml (or logback-test.xml) configuration file but renamed for dm Server.

For additional conceptual information about the serviceability subsystem, see Chapter 7, Serviceability.

The com.springsource.medic.properties File

The SERVER_HOME/config/com.springsource.medic.properties file configures dm Server service dumps and whether you want to capture System.out and System.err output to your application's trace file.

The service dump support provides an in-memory buffer of log output. Whenever a dump is triggered this in-memory buffer is written out as part of the dump.

The following table describes the properties you can include in the SERVER_HOME/config/com.springsource.medic.properties file. This file configures serviceability properties that dm Server includes in addition to those supplied by the Logback, configured in the serviceability.xml file.

Table 9.5. Serviceability Properties

Property	Description
`dump.root.directory`	Specifies the directory to which dm Server writes the service dumps. The directory name is relative to `SERVER_HOME`.
`log.wrapSysOut`	Specifies whether you want to capture `System.out` output from your applications to the application trace file. The output is logged by dm Server'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.wrapSysErr`	Specifies whether you want to capture `System.err` output from your applications to the application trace file. The output is logged by dm Server'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.dump.level`	Specifies the log-level of the entries that are captured in the in-memory buffer. Valid values of this property are the same as the log-levels offered by Logback: TRACE, DEBUG, INFO, WARN and ERROR. For more details about these levels, see Logback Architecture.
`log.dump.bufferSize`	Specifies the number of entries will be held in the in-memory buffer. Once the buffer is full, it wraps so that oldest entries start to be overwritten by newer entries; in other words, the buffer is circular.
`log.dump.pattern`	Specifies the formatting of the entries when they're written out as part of the service dump. Use the same pattern layout as for Logback logs; see Layouts in the Logback documentation.

The following sample com.springsource.medic.properties is from a freshly-installed dm Server:

dump.root.directory=serviceability/dump
log.wrapSysOut=true
log.wrapSysErr=true
log.dump.level=DEBUG
log.dump.bufferSize=10000
log.dump.pattern=[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n

The serviceability.xml File

Logging support in dm Server 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 other logging systems.

You configure logging for SpringSource dm Server using the SERVER_HOME/config/serviceability.xml file. This file is the standard Logback logback.xml or logback-test.xml configuration file, but renamed for dm Server due to internal requirements.

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

<configuration>

    <appender name="SIFTED_LOG_FILE" class="ch.qos.logback.classic.sift.SiftingAppender">
        <discriminator>
            <Key>applicationName</Key>
            <DefaultValue>dm-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>
		<layout class="ch.qos.logback.classic.PatternLayout">
		    <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
		</layout>
	    </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>
	<layout class="ch.qos.logback.classic.PatternLayout">
	    <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n</Pattern>
	</layout>
    </appender>

    <appender name="EVENT_LOG_STDOUT" class="com.springsource.osgi.medic.log.logback.ReroutingAwareConsoleAppender">
	<layout class="ch.qos.logback.classic.PatternLayout">
 	    <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread &lt;%X{medic.eventCode}&gt; %msg %ex%n</Pattern>
	</layout>
    </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>
	<layout class="ch.qos.logback.classic.PatternLayout">
	    <Pattern>[%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread &lt;%X{medic.eventCode}&gt; %msg %ex%n</Pattern>
	</layout>
    </appender>

    <logger level="INFO" additivity="false" name="com.springsource.osgi.medic.eventlog.localized">
	<appender-ref ref="EVENT_LOG_STDOUT" />
	<appender-ref ref="EVENT_LOG_FILE" />
    </logger>
	
    <logger level="INFO" additivity="false" name="com.springsource.osgi.medic.eventlog.default">
	<appender-ref ref="SIFTED_LOG_FILE" />
	<appender-ref ref="LOG_FILE" />
    </logger>

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

</configuration>

Logback allows dm Server to use logger, appender, and 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 dm Server writes log messages to four different locations that map to the four appenders:

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 the dm Server itself are logged to the SERVE_HOME/serviceability/logs/dm-server/log.log file. Because this appender creates different log files for each application, it is called a sifting appender.
When dm Server creates the first log file, it calls it log.log; however, when this file reaches a size of 10MB, dm Server creates a new log file called log_1.log, and so on up to 4. At that point, the cycle starts again and dm Server overwrites the existing log.log. 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 dm Server. The format of the messages is similar to that of the preceding appenders, although with slightly less information. For example:
[2009-08-25 15:04:57.044] server-dm-7 <OF0001I> OSGi telnet console available on port 2401.
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 dm Server environments. However, if you want to customize the logging framework even further, you can edit this file as well as the com.springsource.medic.properties.. See the logback documentation for detailed information about the architecture and the configuration of Logback.