Wrapping System.out and System.err log files

• Introduction of System.out and System.err streams
• Directions to activate the new function

Introduction of System.out and System.err streams

A Java virtual machine (JVM) provides two output streams to which Java code can print or write: the System.out and System.err streams. A JVM runs in a native process, which also provides two output streams to which process native code can write. These are the process stdout and stderr streams. By default, data written to the JVM System.out and System.err streams is simply forwarded to the process stdout and stderr streams respectively. WebSphere Application Server Version 4.0 supports the redirection of stdout and stderr streams to log files. The installation default is to redirect these streams to files that are located in the <WASHOME>/logs directory. These log files grow without bound and you must stop a server process in order to perform log file maintenance.

This new feature supports the JVM System.out and System.err streams of any server process to redirect to self-managing log files, which are independent of the process stdout and stderr files. The process stdout and stderr files are retained, but have no data written to them under normal operating conditions. Activate this feature on a per-server process basis. To activate this feature, new configuration data in the Ras properties file (logging.properties) is required. A new version of the logging.properties file is installed, along with this FixPak. By default, this feature is disabled. If this new feature is activated, the new self-managing log files for the System.out and System.err streams manage themselves based on file size. When a self-managing log file is configured, you specify a name, maximum file size (in megabytes), and archive size. When the server starts, the specified stream is redirected to this file. When this file approaches the specified maximum size, logging is temporarily suspended. The current file is closed, renamed and put into the archive. The system generates a new file name, based upon the original file name, plus the timestamp at which the rename occurred. A new (empty) file with the original name is opened and logging resumes to that file. When the number of files in the archive exceeds the specified size of the archive, the system deletes the oldest archive file. Note that no messages are lost while this maintenance occurs.

Directions to activate the new function

1. Shut down WebSphere Application Server. All server processes must stop. For Advanced Edition, this shut down includes both application servers and the administrative server.
2. Archive the existing stdout or stderr logs for all server processes. The default location for these log files is the <WASHOME>/logs directory. For Advanced Edition Single Server, the default log names are default_server_stdout.log and default_server_stderr.log. For Advanced Edition, the default log names are tracefile and AdminServer_stderr.log for the administrative server and AppServerName_stdout.log and AppServerName_stderr.log for the application servers. Moving these log files to an archive directory is recommended.
3. Locate the current Ras properties file. By default, this file is named logging.properties and is found in the <WASHOME>/properties directory. Normally all server processes on a node share a single copy of this file. If coexistence support is enabled, then every server process has its own private copy of this file. If coexistence support is in use, it is recommended that you make a backup copy of all existing Ras properties files at this time.
4. Create a copy of the logging.properties file for each server configured to use wrapping log files. It is recommended that you use the server names in naming the copy. For Advanced Edition, this recommendation includes both application servers and the administrative server. If coexistence support is currently in use, each server process now has two Ras properties files defined. Merge these files into a single file. The new properties file is a proper superset of the old. The new version of the Ras properties file has added properties, but none are deleted. Copy the new properties to the existing Ras properties files for each server.
5. Change the properties setting for the System.out and System.err logs in each of the Ras properties files. Each log has four properties that you can potentially modify.

   The four properties for the System.out log are listed below. A similar set of properties exists for the System.err log.

   • com.ibm.ws.ras.SystemOutLogEnable
     Set this property to true, to enable this log. The default value is false.

   • com.ibm.ws.ras.SystemOutLogName
     Set this property to a unique, fully qualified file name. The recommended value is <WASHOME>/logs/<ServerName>_SystemOut.log. Ensure the specified file name is in a valid format for the platform. If a non-default directory is specified, create the directory before you start the server process. In addition, WebSphere Application Server must have write access to this directory.

   • com.ibm.ws.ras.SystemOutLogRollover
     Specify the maximum size of the log file, in megabytes. The default is 1 (one megabyte). This number must be positive.

   • com.ibm.ws.ras.SystemOutLogBackups
     Specify the maximum number of archive files to retain. The default is 1. This number must be positive.

6. Configure each server process to use its private copy of the Ras properties file, instead of the shared (logging.properties) file. Use the com.ibm.ws.ras.RasProperties system property for this purpose. The name of the properties file specified using the com.ibm.ws.ras.RasProperties must be relative to the class path. Store the properties files in the properties directory, since this directory is on the class path.

   Following is an example of how to configure an Advanced Edition Single Server, an Advanced Edition administrative server, and an Advanced Edition application server to use a properties file named ServerName.properties. The ServerName.properties file resides in the <WASHOME>/properties directory.

   • Advanced Edition Single Server
   1. Select the server XML configuration file in the Web Console.
   2. Click Nodes > <node_name> > Application Servers.
   3. Click Server > Process Definition > JVM Settings.
   4. Click SystemProperties in Advanced Settings.
   5. Click New.
   6. Add com.ibm.ws.ras.RasProperties for the name field, ServerName.properties for the value field.
   7. Save the configuration.
   • Advanced Edition administrative server
   1. Edit the admin.config file in the <WASHOME>/bin directory.
   2. Add -Dcom.ibm.ws.ras.RasProperties=ServerName.properties to the com.ibm.ejs.sm.util.process.Nanny.adminServerJvmArgs statement.
   • Advanced Edition application server
   1. Start the administrative server and the administrative console.
   2. Expand nodes > <node_name> > Application Servers.
   3. Click Application Servers.
   4. Click JVM Settings.
   5. Click Add in System Properties. Add com.ibm.ws.ras.RasProperties for the name field, ServerName.properties for the value field.
   6. Click Apply.
   7. Verify that the generated property is correct
      (-Dcom.ibm.ws.ras.RasProperties=ServerName.properties) in the Generated Command Line Arguments section.

7. Restart the application servers.