9.2 Configuring Serviceability
Prev | 9. Configuring the Virgo Web Server | Next

## 9.2 Configuring Serviceability

The serviceability sub-system of VWS 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 VWS instance when an internal failure or thread deadlock is detected.

  You configure service dumps for Virgo Web 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 VWS 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 Virgo Web 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 VWS.

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 VWS 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 VWS 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 VWS 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 VWS'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 VWS'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 VWS:

    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 VWS 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 Virgo Web 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 VWS due to internal requirements.

The following listing shows the default `serviceability.xml` file in a freshly-installed VWS; 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 VWS 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 VWS 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 VWS 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 VWS creates the first log file, it calls it `log.log`; however, when this file reaches a size of 10MB, VWS creates a new log file called `log_1.log`, and so on up to 4. At that point, the cycle starts again and VWS 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 VWS. 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 VWS 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.

Prev | Up | Next
9. Configuring the Virgo Web Server | Home | 9.3 Configuring the Embedded Tomcat Servlet Container