Configuring logging

Logging can be used for monitoring and debugging CM Server and CM API-based applications.

Logging tracks ordinary CM Server and CM API user operations as well as any errors that occur while CM Server or your CM API-based application is running. Log entries occur in the machine's default locale, or in U.S. English if the machine's locale is not supported.

By default, logging for CM Server is set at the INFO level. You should enable the logging for your CM API-based application to the INFO level.

You can configure CM API, WebSphere® Application Server, and TSlogger logging packages.

CM API logging

CM API logging is controlled by using the logging.properties file located in JDK directory structure of the JRE being used to run your application. Look for the logging.properties file in the jre\lib directory of your JDK (for example, C:\Program Files\IBM\WebSphere\AST\eclipse\jre\lib, C:\jdk_5.0\jre\lib, or C:\Program Files\Java\jre1.5.0_06\lib).

Logging is disabled by default; you should enable it at the INFO level.

The following example logging.properties file contains entries that show how to configure log and trace settings for CM API-based applications:
############################################################
#      Global properties
############################################################
#
# "handlers" specifies a comma separated list of log Handler 
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.
handlers = java.util.logging.ConsoleHandler

# To also add the FileHandler, use the following line instead.
#handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers.  For any given facility this global level
# can be overriden by a facility specific level
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
# The next line enables logging (for all logger objects) to occur at the INFO level
.level=INFO

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

# CMLogger - Should always be enabled at the INFO level. 
#
# Applications using CM API do not have to be stopped and restarted; changes to the configured

# logging.properties file are automatically noticed and honored within 10 seconds.
#
# The following lines designate logging for the CMLogger object to occur at the INFO level,
# and that the log output file will be named CMLogger[#].log, located in the logged-in
# user's HOME directory; the log output file will rotate through 40 files, each file being
# limited to 40000000 bytes.  Log entries will be appended to the current log output
# file in the rotation and will be written using a simple format.
#
com.ibm.rational.stp.common.internal.util.CMLogger.level = INFO
com.ibm.rational.stp.common.internal.util.LogHandler.pattern = %h/CMLogger%g.log
com.ibm.rational.stp.common.internal.util.LogHandler.limit = 40000000
com.ibm.rational.stp.common.internal.util.LogHandler.count = 40
com.ibm.rational.stp.common.internal.util.LogHandler.append = true
com.ibm.rational.stp.common.internal.util.LogHandler.formatter = java.util.logging.SimpleFormatter

# CMTracer - Enable (uncomment) the entries below for temporary use only, as tracing
# can be resource intensive.  
#
# Applications using CM API do not have to be stopped and restarted; changes to the configured
# logging.properties file are automatically noticed and honored within 10 seconds.
#
# The following lines designate tracing for the CMTracer object to occur at the FINER level,
# and that the trace output file will be named CMTracer[#].log, located in the logged-in
# user's HOME directory; the trace output file will rotate through 40 files, each file being
# limited to 40000000 bytes.  Trace entries will be appended to the current trace output
# file in the rotation and will be written using a simple format.
#
#com.ibm.rational.stp.common.internal.util.CMTracer.level = FINER
#com.ibm.rational.stp.common.internal.util.TraceHandler.pattern = %h/CMTracer%g.log
#com.ibm.rational.stp.common.internal.util.TraceHandler.limit = 40000000
#com.ibm.rational.stp.common.internal.util.TraceHandler.count = 40
#com.ibm.rational.stp.common.internal.util.TraceHandler.append = true
#com.ibm.rational.stp.common.internal.util.TraceHandler.formatter = java.util.logging.SimpleFormatter

These settings result in a log file named CMLogger[#].log (and a trace output file named CMTracer[#].log when the CMTracer entries are uncommented). Each file is located in the logged-in user's HOME directory (where [#] designates the file rotation number); the output rolls from file to file as each file becomes full.

Use of the logging.properties entries above designates that the log records should be appended to the end of the applicable file, and each entry is stored in simple format. Changes to the logging.properties file are automatically noticed and honored within approximately 10 seconds by CM API-based application; the application does not need to be stopped and restarted.

When a log output file becomes full (at 40 MBytes) a new file is created and the previous file is renamed to contain the date and timestamp when the file rotation occurred. Each file holds 40 MB of data and new entries are appended to the existing entries, including across application restarts. When the number of log files reaches 40, the rotation to a new file causes the oldest file to automatically be deleted.

For more information on how to configure Java logging, please refer to your JDK java.util.logging.Logger and java.util.logging.FileHandler Javadoc.

If you create a custom logging properties file, you must specify where to find it for the JVM by specifying the -D argument. For example:
java -Djava.util.logging.config.file=C:\myLogPropsFile.properties your_client_java_program_that_uses_CM-API

Configuring WebSphere Application Server logging and tracing

You set up and configure WebSphere Application Server logging and tracing by using the WebSphere Application Server Administration Console. You can use this URL to access the WebSphere Application Server Administration Console:
http://<server-name>:<admin-console-port-number>/ibm/console
where <server-name> is the name of the CM Server system, and <admin-console-port> is the Administration Console port number (12060 by default with CM Server, or 9060 for other WebSphere Application Server versions).
Note: Tracing at any level (FINE, FINER, or FINEST) for any component running in WebSphere Application Server (including the CM Server components) will have a negative impact on performance.

Depending on the type of Websphere Application Server being used on your CM Server system, you may be able to make changes in real time without having to stop and restart the CM Server. On most Administration Console logging setup pages there are two tabs: a Configuration tab and a Runtime tab.

From the Administration Console, click Troubleshooting->Logging and Tracing, and select the server to configure from the list of servers. Select Change Log Detail Level and click the Runtime tab. Changes made to the Runtime tab take effect as soon as you save your changes; changes made to the Configuration tab do not take effect until you restart the server. If you want changes to persist, select the Save runtime changes to configuration as well check box. Select the Components link. Note that *=info is listed in the box. Open the com.ibm.rational.* option and select com.ibm.rational.stp.*. Select the level by clicking the Message and Trace Levels option. Click OK, then click the Save link in the Messages area at the top of the page that opens. Changes take effect without restarting the server.

If the version or class of Websphere Application Server on your CM Server system does not provide a Runtime tab that enables real-time configuration changes, use the Configuration tab and then restart the server to make the saved changes take effect.

The default out-of-the-box settings for the log file size and the number of log files to rotate will probably need to be increased. You should set the number of log files to rotate through to at least 40, and set the log file size to at least 40 MB. In the Websphere Application Server Administration Console to change the JVM Log file size and file rotation settings follow these steps:
  1. Choose Troubleshooting->Logging and Tracing.
  2. Select the relevant server from the list of servers to configure.
  3. Select JVM Logs and then click the Configuration tab (the Runtime tab can be used for viewing the current SystemOut.log and SystemErr.log file contents).
  4. Make your changes for the SystemOut and SystemErr locations, file sizes (should be at least 40 MB), and how many historical files to maintain (should be at least 40 MB).
  5. Click OK, then click the Save link in the Messages area at the top of the page that opens.
WebSphere Application Server log files are at these locations:
  • UNIX® : /opt/IBM/RationalSDLC/common/CM/profiles/cmprofile/logs/server1/
  • Linux®: /opt/ibm/RationalSDLC/common/CM/profiles/cmprofile/logs/server1/
  • Windows®: \Program Files\IBM\RationalSDLC\common\CM\profiles\cmprofile\logs\server1\

TSlogger

TSLogger is for logging backend ONCRPC server processes. You configure this utility by editing the tslogger.properties file, located here:
  • Windows: \Program Files\IBM\RationalSDLC\common\CM\bin\tslogger.properties
  • UNIX: /opt/IBM/RationalSDLC/common/CM/bin/tslogger.properties
  • Linux: /opt/ibm/RationalSDLC/common/CM/bin/tslogger.properties
The log and trace files are located in these locations:
  • Windows: \Program Files\IBM\RationalSDLC\common\CM\logs\server1\ccrpc [and \cqrpc]
  • UNIX: /opt/IBM/RationalSDLC/common/CM/logs/server1/ccrpc [and /cqrpc]
  • Linux: /opt/ibm/RationalSDLC/common/CM/logs/server1/ccrpc [and /cqrpc]
Log and trace files include:
  • SystemOut.log - General log output, enabled to log at the INFO level by default.
  • SystemErr.log - Error/exception output, enabled by default.
  • trace.log - Trace output, disabled by default.

The tslogger.properties file has labelled areas where changes can be made and what the range of acceptable values can be. Logging is enabled by default at the INFO level. All INFO, WARNING, and SEVERE messages are recorded in the log file. Log files are configured by editing the tslogger.properties file, however, the file is properly configured at install time and no changes are required.

The default settings in the tslogger.properties file are set to values that should not require any modifications. As the output files fill up, output rotates to the next file. Once the maximum number of files in the rotation is reached, the oldest file is removed to make room for the next file in the rotation.

Summary of the logging levels from highest to lowest levels:
  • OFF: Disable all logging and tracing.
  • ERROR: Corresponds to SEVERE in JSR47.
  • WARNING: Corresponds to WARNING in JSR47.
  • INFO: Corresponds to INFO in JSR47.
  • DEBUG_MIN: Corresponds to FINE in JSR47.
  • DEBUG_MID: Corresponds to FINER in JSR47.
  • DEBUG_MAX: Corresponds to FINEST in JSR47.
  • ALL: Enable all levels of logging and tracing.
Related concepts
Los archivos de registro de ClearQuest y los archivos de propiedades de registro

Comentarios