Managing Windchill Logging

Windchill log messages contain exception tracebacks and other information that can be used for troubleshooting application behavior.

You manage Windchill Directory Server log files using a command line utility from the server where Windchill Directory Server is installed.

Starting in Windchill 9.0, Apache log4j is now being used as the primary mechanism for managing and issuing log messages. Some legacy logging has been modified to make use of log4j, but a large amount of previously existing Windchill logging capabilities remain as they were in previous releases and are still managed by Windchill property files configuration settings.

In the 10.0 release, additional legacy Windchill logging capabilities have been migrated to log4j.

To manage logging, you should be familiar with the following:

• The property settings that affect logging that are in the wt.properties file. For information about these properties, see the properties.html file that is located in the <Windchill>/codebase directory and see the section Out-of-the-box wt.properties Log File Settings.

For descriptions of the out-of-the-box Windchill loggers and additional details on which Java package or class is used as the interface that produces entries in log files, see the following file:

You can use the MBeans associated with the loggers for making temporary changes to what is logged. For details on the logger and MBean associations, see the loggers.html file.

• The property settings that affect log4j logging. These property settings are in the properties files located in <Windchill>/codebase/WEB-INF:

◦ log4jMethodServer.properties - Controls method server log4j logging and the logging for the Windchill web applications running in the Tomcat servlet engine that is embedded in the method server.

◦ log4jServerManager.properties - Controls server manager log4j logging.

Additionally, the <Windchill>/codebase/log4j.properties file is used as the default configuration file that log4j uses if another configuration file is not specified. The log4j.properties file controls logging options for most command line applications.

Changes to the log4j properties files listed previously must be done by editing the files instead of using the xconfmanager utility. If you make any manual changes to these files, be sure to back up the files as described in Managing Customizations.

• How to make temporary changes to log settings using the Logging MBean. See Using MBeans to Work with Log Files.

◦ You can collect log files using the System Configuration Collector that is available from Site

> Utilities.

◦ You can access the Log File Viewer page to search, list, and view server log files. The link to this page is available from the System Health Monitoring Tools page. Clicking the Monitoring Tools link on the Server Status page opens the page.

For details on the Server Status page and its links, see About the Server Status Page.

For details on the Server Status page, access the page from Site

> Utilities and then open the online help from the page.

• How to use the xconfmanager utility to make permanent changes to the log settings for legacy logging and verbosity properties. For information on using the xconfmanager utility, see Using the xconfmanager Utility.

◦ The wt.util.jmx.SetLogLevel command-line utility allows you to set or reset logger verbosity levels for specified loggers in specified server processes. The utility is specified as follows:

java wt.util.jmx.SetLogLevel [-ms|-sm|-se|-all]* [-resetAll]

[<logger_name> [<log_level>]]

where <logger_name> is the name of the logger, and <log_level> is the specified verbosity level. Valid values for log level are: ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, and OFF.

The server processes can be specified by any combination of the following:

▪ -ms -- Targets all method servers in the cluster, including those with and without embedded servlet engines.

▪ -all --Targets all of the above processes. If nothing is specified, this is the assumed

The -resetAll option will reset all log4j verbosities in the target processes to the level specified by the log4j configuration file. If both -resetAll and a logger name are specified the reset will be performed prior to setting the specified logger's verbosity level. Either -resetAll or a logger name must be specified.

◦ The Log Levels link on the System Health Monitoring Tools page presents a page from which you can display or set log levels for server manager, method server, or servlet engine loggers for current server processes. You can get to the Log Levels link from Site

> Utilities > Server Status. On the Server Status page, click Monitoring Tools.

Certain logging functions should only be enabled for troubleshooting purposes. For more information, see Best Practices for Securing Your Windchill Solution.

The following sections provide additional information on wt.properties log file settings and log event configuration settings.

This section provides information about some of the common log file settings in the wt.properties file that are used in Windchill.

The wt.logs.dir property sets the default directory used for log files. Out of the box, this property is set to <Windchill>/logs.

The value of the wt.logs.dir property specifying the path of Windchill logs for Server Manager, Method Server, or Background Method Server, must not contain any spaces. For example:

• Incorrect Usage: D:\ptc\Windchill_giraffe_246_2\Windchill\ my logs

• Correct Usage: D:\ptc\Windchill_11.1\Windchill\mylogs

Log file naming and contents are primarily controlled by the log4j configuration. The log4j configuration for the server manager and method server is specified in wt.properties as follows:

wt.manager.log4j.config=WEB-INF/log4jServerManager.properties

wt.method.log4j.config=WEB-INF/log4jMethodServer.properties

PTC recommends that you do not change the log file settings because log file consistency simplifies interactions with technical support.

The main method server and server manager log files contain all of messages generated from the existing code as well as those messages generated using the log4j loggers. The list presented in this topic provides details on existing information about working with log files.

By default, most loggers are set up so that Windchill stores only ERROR and FATAL log events (except where the configuration has already been extended to output other log events) in Windchill log files. Therefore, you must usually change the configuration to see other log events, such as TRACE, DEBUG, INFO, or WARN.

To turn on a given logging level for a given area, determine if the area has a corresponding logger by viewing the loggers from the Operations tab (for details, see Using MBeans to Work with Log Files) or by using the Log Levels page (available from Site

> Utilities > Server Status. On the Server Status page, click Monitoring Tools):

• If a log4j logger has not been implemented, locate the property that sets the log level in wt.properties and set the level in that property using the xconfmanager utility.

• If a log4j logger has been implemented, you can turn on a given logging level for all loggers or adjust the logging level at a more specific level.

To turn on a given logging level for all loggers, find the log4j.rootLogger property in the appropriate properties file and change the value before the first comma ("error" by default) to the desired level. For example, change:

Turning on logging for all loggers usually results in too much data in the log output; therefore, a better practice is to adjust the logging level at a more specific logger level. To do this, you can append a line of following form to the properties file:

where <targetLoggerName> is the name of the logger and <desiredLogLevel> is the log level.

For example, to set the log level for wt.servlet.ServletRequestMonitor.stats to INFO, add the following property to the log4jWebApp.properties file:

Adding this property also causes the default log level of all wt.servlet.ServletRequestMonitor.stats.* loggers to be set to INFO. For example, the level of the wt.servlet.ServletRequestMonitor.stats.summary logger is also set to INFO unless the level of this logger is otherwise specified.

Changes to log4j configuration files may go unnoticed for as long as a few minutes as the checks for modifications to these files take place on a periodic basis. To force an immediate reload of the log4j configuration file, use the reconfigure operation on the Logging MBean, or make temporary changes to the log4j configuration without changing the configuration files.

Manual changes made to property files may not be preserved when you apply maintenance releases; ensure that any files you manually change are backed up.

Many of the log entries that are statistical summaries provide useful information for anyone checking on the health of your system or anyone attempting to debug a specific problem that has been identified. Configuring when and how often these types of messages are logged can be done through some of the Windchill MBeans.

To make the changes made through the MBeans permanent, you must use the Loader MBean as described in Using the Loader MBean to Persist Configuration Changes.

When viewing a log file, the statistical summaries included can be identified by either of the following:

What is generated for the general summary (provided from wt.summary.general) can be managed through the out-of-the-box summary MBean located under Summaries.

For the default statistical summary entries that are identified by stats.summary, you can determine which MBean controls the content of the generated entry by matching the MBean name with part of the name appearing before .stats.summary. For example, assume a method server log entry begins with the following:

Wed 9/3/08 13:52:50: wt.jmx.core.SharedScheduledExecutor.worker: INFO :

com.infoengine.util.IeContextMonitor.stats.summary -

From the name IeContextMonitor, you can deduce that the MBean controlling this entry is IeContexts (which can be located under the Monitors node in the tree). See IeContexts (Monitors).

If a method server log entry begins with the following:

Wed 9/3/08 13:52:50: wt.jmx.core.SharedScheduledExecutor.worker: INFO :

com.infoengine.jndi.DirContextMonitor.stats.summary -

Then, MBean controlling this entry is DirContexts. See DirContexts (Monitors).

Use the following attributes associated with each MBean to manage the summary:

• SummaryIntervalSeconds - determines how often the statistic is logged (default 600 seconds)

• SummaryStatisticsLoggerLevel - ERROR, FATAL, TRACE, DEBUG, INFO, or WARN

• StatisticsLoggerOutputAttributesSupported - the data available to be logged

PTC recommends that you always log summary information similar to what is provided by default so that you have a record of how the system is performing throughout the day.