Windchill MBeans
As mentioned earlier, the Windchill MBeans are accessible from the com.ptc node in a JMX client, such as JConsole. Selecting a Windchill MBean from the tree displays the information related to that MBean.
The following sections provide descriptions of the some of the more prominent Windchill MBeans. The MBeans included are listed in ascending alphabetical order and the (Monitors) designation is included for the MBeans that appear under the Monitors node in the JMX client tree display.
ActiveUsers (Monitors)
The ActiveUsers MBean presents information about active users on the current system.
The following attributes provide active user information:
|
Attribute
|
Description
|
|
ActiveUserCount
|
Number of unique users who are logged on to the method server node that is servicing the MBean request for this information.
|
|
ActiveUsers
|
List of user names of those users who are logged on to the method server node that is servicing the request for this information.
|
|
TotalActiveUserCount
|
Number of unique users who are logged on to any method server node. If your system has only one method server, this number is the same as the number displayed in the ActiveUserCount attribute.
|
|
TotalActiveUsers
|
List of user names of those users who are logged on to any method server node.
|
Since there is no logout function in Windchill, a user that has logged on is assumed to be an active user until there is no recorded action by the user for a specified period of time that is, by default, 30 minutes. After the specified time has elapsed with no activity, the user is removed from the active users list and the active user count is decremented by 1. The wt.session.sessionUsers.timeout property stored in wt.properties controls the time-out period.
Additionally, audit reports can provide a history of how many users accessed
Windchill during a specified time period. The auditing service records login/logout auditing event information in the database and presents the user information in usage reports. For information about auditing and usage reporting, see
About Auditing Administration.
Additionally, audit reports can provide a history of how many users accessed Windchill during a specified time period. The auditing service records login/logout auditing event information in the database and presents the user information in usage reports. For information about auditing and usage reporting, see auditing online help that is available from the Windchill Help Center.
DirContexts (Monitors)
The DirContexts MBean monitors JNDI requests made by the system. It is similar in intent to the servlet request and method context monitoring MBeans. The DirContexts MBean’s existence, life cycle, and configuration persistence are controlled by the Loader MBean.
Dumper
The Dumper MBean provides:
• Operations to dump stack traces, attributes MBean of all or selected MBeans (as XML), or text file contents to a new window in JConsole.
• Operations to email any of this data to individual email addresses, or a mailing list managed by the Emailer MBean.
• Provides ability to apply XSLT stylesheet to MBean attribute XML.
• Emailer MBean performs actual emailing.
• A DefaultXsltStylesheet attribute which is a file, URL, or Java resource path reference to an XSLT style sheet used by default for MBean attribute XML styling. Out-of-the-box this defaults to a simple XSLT style sheet that produces easy-to-read HTML.
Emailer
The Emailer MBean provides:
• The underlying emailing facilities used by all other MBeans.
These emailing facilities do not use Windchill's persistent queues as they are intended to be usable from any Java process; however, they do email in the background and there is a retry function that is configured to resend a message a configurable number of times at a configurable interval prior to giving up (and logging an error).
• Manages email lists for use by other MBeans in emailing to a group of email addresses.
These email lists are described by EmailList MBeans shown nested beneath the Emailer MBean in JConsole.
• Attributes for configuring the appropriate email server, port, and so on, to use.
These are read from wt.properties or Java system properties by default, but can be overridden here.
To configure the EmailList, see the section Populating the JMX-Administrators List in
Setting Up Your JMX Environment.
GarbageCollection (Monitors)
The GarbageCollection MBean monitors the percentage of overall time spent in garbage collection during intervals of a configurable duration. If this value exceeds a configurable threshold a JMX notification is sent.
IeCalls (Monitors)
The IeCalls MBean provides aggregate statistics about outgoing Info*Engine calls. The IeCalls MBean’s existence, life cycle, and configuration persistence are controlled by the Loader MBean.
IeContexts (Monitors)
The IeContexts MBean monitors Info*Engine requests being handled by a method server. It is similar in intent to the servlet request and method context monitoring MBeans. The IeContexts MBean’s existence, life cycle, and configuration persistence are controlled by the Loader MBean.
InfoEngine
The InfoEngine MBean is the root MBean for an Info*Engine System under which service beans and other administrative information beans are exposed. The Loader MBean manages this MBean.
Loader
The Loader MBean can detect changes to the configuration file, unload the existing MBeans, and instantiate new MBeans from the file. Changes to MBeans are not automatically detected nor are the MBeans automatically/periodically saved at any time.
Rather, if an administrator wants to save configuration changes they have made so they extend beyond the life span of the server JVM, they can use the save operation at their discretion. For additional information, see
Using the Loader MBean to Persist Configuration Changes.
Logging
The Logging MBean provides the ability to examine and dynamically change the log4j logging configuration.
The Logging MBean itself can detect when the log4j configuration file has changed and apply the altered configuration. It cannot save a log4j configuration change made via JMX back to the logging configuration file. Instead changes made to the logging configuration via JMX are for the life span of the target JVM only.
To make permanent changes to a log file, refer to
Using MBeans to Work with Log Files for further instructions.
wt.logs.dir (LogsDirViewers)
The wt.logs.dir MBean produces MBeans for viewing/tailing and emailing.log files found in the Windchill logs directory (and its subdirectories). The intent is to provide basic capabilities for legacy (non-log4j) logs.
The wt.logs.dir MBean is currently instantiated in server manager, method server, and servlet engine processes.
|
|
The MBeans that represent the logs directory and its subdirectories (including the wt.logs.dir MBean itself) do not poll for changes in the corresponding directories; instead, explicitly use the Refresh operation on the MBeans to view changes.
|
Memory (Monitors)
The Memory MBean allows percentage thresholds to be set for various memory pools. It also allows an overall memory usage percentage threshold to be set and periodically checks to see if this has been exceeded. JMX notifications are sent when any of these thresholds are exceeded. It also allows the current percentage usage values to be examined via its attributes.
MethodContexts (Monitors)
The MethodContexts MBean monitors method server method contexts and thus is only instantiated in method servers.
Use this MBean to establish what data is logged in the method server.
By default, the following values are set for ContextLoggerOutputAttributes:
StartTime, Id, ParentId, IeContextIds, ServletRequestId, UserName,
RemoteAddr, TargetClass, TargetMethod, AccessLogDetail, Redirects,
JDBCQueryCalls, ElapsedJDBCSeconds, ElapsedTotalCpuSeconds, ElapsedTotalSeconds
|
|
If you choose to modify the output attributes, be aware that to get the data needed for tracing anything through Windchill, you must include IeContextIds and ServletRequestId in ContextLoggerOutputAttributes.
|
If the ContextLoggerLevel is set to INFO, then the following is a sample of the output in the method server log (formatted to fit the page):
2010-12-30 14:55:10,246 INFO [RMI TCP Connection(23)-132.253.12.51]
wt.method.MethodContextMonitor.contexts.rmi wcadmin - 2010-12-30 20:55:09.715
+0000, 10wdulv;gic4vdn7;5780;cplas;9, -, -, -, wcadmin, 132.253.12.51,
wt.query.template.ReportTemplateHelper$Server, hasModifyAccess, ,
0, 1, 0.233122646, 0.03125, 0.530067928
In this sample, data field names are not shown because the default short format omits the names to avoid repeatedly outputting them in the log entries. (You can change the default using either the MethodContextMonitor MBean or the Performance Feedback Settings).
The items included in this sample (after the common information about logger time, log event level, thread, logger name, and current user) are:
• StartTime - start time of method context: 2010-12-30 20:55:09.715 +0000
• Id - method context ID: 10wdulv;gic4vdn7;5780;cplas;9
Notice that the delimiter is a comma. The semicolon is considered part of the contextId string.
• ParentId - ID of parent method context: none (-)
• IeContextIds - associatedInfo*Engine context ids: none (-)
• ServletRequestId - associated servlet request id: none (-)
• UserName - name of user for which the method context is invoked: wcadmin
• RemoteAddr - remote IP address of the method context call: 132.253.12.51
• TargetClass - target class: wt.query.template.ReportTemplateHelper$Server
• TargetMethod - target method: hasModifyAccess
• AccessLogDetail - additional details: none
• Redirects - number of times call was redirected: 0
• JDBCQueryCalls - JDBC query call count: 1
• ElapsedJDBCSeconds - time spent in JDBC calls: 0.233122646 seconds
• ElapsedTotalCpuSeconds - CPU time used for method context: 0.03125 seconds
• ElapsedTotalSeconds - elapsed time of method context: 0.530067928 seconds
|
|
From the Operations node, you can use the captureActiveContexts button to capture running contexts. They will then display under MethodContexts MBean.
|
The statistical summary provided in the method server log through wt.method.MethodContextMonitor.stats.summary can be helpful when reviewing system performance. For example, the following sample output from the method server log (formatted to fit the page) shows information about the active method contexts using the method server during the specified time interval (identified by ElapsedSeconds):
2010-12-10 17:48:50,290 INFO [wt.jmx.core.SharedScheduledExecutor.worker]
wt.method.MethodContextMonitor.stats.summary Administrator -
ElapsedSeconds=600.008322566, CompletedContexts=630, ErrorCount=0,
RedirectCount=0, ContextSecondsAverage=0.3671603731396825,
ContextSecondsMax=42.013152789, ContextCpuSecondsAverage=0.03640873015873016,
ContextUserSecondsAverage=0.03318452380952381,
ContextJDBCConnWaitSecondsAverage=1.294644634920635E-4,
ActiveContextsAverage=0.38546599761132355,
ActiveContextsMax=10, ActiveContextsStart=0, ActiveContextsEnd=0,
AverageJDBCCallsPerContext=3.212698412698413,
AverageJNDICallsPerContext=0.009523809523809525,
PercentageOfContextTimeInJDBCCalls=10.215606919069739,
PercentageOfContextTimeInJDBCConnWait=0.03526101207082334,
PercentageOfContextTimeInJNDICalls=0.008320770340035786
Many items in this log entry are self explanatory. The following list provides some additional information:
• CompletedContexts indicates the number of method contexts that completed execution during the specified time interval.
• ContextCpuSecondsAverage indicates the average number of CPU seconds used by the contexts.
• ActiveContextsAverage provides the average number of active contexts for the time interval.
• ContextSecondsMax indicates the maximum number of seconds used by any context executing during the time interval.
• ActiveContextsMax indicates the maximum number of contexts executing at one time during the time interval.
• ActiveContextsStart identifies the number of contexts executing at the beginning of the time interval.
• ActiveContextsEnd identifies the number of contexts executing at the end of the time interval.
MethodServer
The MethodServer MBean provides a brief summary of some top-level method server information. This MBean is only available for the method server.
MethodServers (Monitors)
The MethodServers MBean is only instantiated in the server manager and provides information on a server manager's method servers using child MBeans which it manages.
By default these child MBeans proxy all of the MBeans from the corresponding method server JVMs into the server manager JVM (as nested MBeans) to allow an administrator to easily manage and monitor details of a server manager and all of its method servers by just connecting to the server manager. Each of the MBeans representing method servers also exposes a RemoteJmxUrl attribute which provides a JMX URL that can be used to connect a JMX client directly to the given method server.
The MethodServers MBean fires JMX notifications whenever:
• A method server is registered
• A method server is removed
• The JMX connection to a method server is lost.
The MethodServers MBean's existence, life cycle, and configuration persistence are controlled by the Loader MBean.
NotificationHandlers
The NotificationHandlers MBean allows you to create and manage NotificationHandler MBeans. The NotificationHandlers MBean's existence, life cycle, and configuration persistence are controlled by the Loader MBean.
NotificationHandler MBeans allow an administrator to specify logging and/or emailing actions that are to take place upon the occurrence of a JMX notification. One or more MBeans can be listened to by filtering on the types of notifications that are of interest. Administrators can specify additional data to query from the MBean generating the notification or other MBeans when a notification occurs, which is specified to be included in logs and emails.
Some items to note:
• MBeans are referenced via the ObjectName syntax - either an exact ObjectName or an ObjectName pattern. See the ObjectName documentation for more information. Also note that JConsole provides the ObjectName of each MBean on the MBeanInfo table that is displayed in the right pane when you select the MBean.
• If an email subject is not provided, one will be automatically generated upon receipt of a notification from the notification's message and other data.
• You can specify multiple attributes via "*" or fields within a composite data attribute by using "attributeName.fieldName" syntax.
• The NotificationHandler MBean's log level is one of the few logger level attributes that is actually a persistent attribute (meaning that it is reapplied when the JVM restarts). In most other cases, such attributes are merely shortcuts to allow per-JVM-session tweaks and overrides to log4j log levels. An exception is made here to allow easier dynamic creation and specification of new notification handlers.
ProcessCpuTime
The ProcessCpuTime MBean monitors the percentage of overall CPU time consumed by the target process over the last configurable time interval. If this metric exceeds a configurable threshold, a JMX notification is sent.
Properties
The Properties MBean exposes current WTProperties settings, providing you with a method to modify the property values. It is instantiated out-of-the-box in all server JVMs.
|
|
Your changes are written to the site.xconf file and the affected property files are regenerated using your changes. The regenerated property files are used to set system properties when the system is next restarted. For additional information, see Using MBeans to Modify Property Values. |
PropertiesManager
The PropertiesManager MBean exposes the properties files, providing a read only view of those settings in the files. It is instantiated out-of-the-box in all server JVMs.
Queues (Monitors)
This MBean is instantiated in the background method server and provides management and monitoring for the queues. It is not managed by the Loader MBean. See also
Using MBeans to Review Queue Attributes.
Reporting System
The Reporting System MBean periodically pings the Cognos (when it is installed and enabled) and reports on its availability, including the providing of notifications when the system availability changes. It also exposes various administrative operations against it.
This MBean can be deployed in both servlet engine and method server JVMs, but is only deployed in the servlet engine by default. The Reporting System MBean’s existence, life cycle, and configuration persistence are controlled by the Loader MBean.
RMICalls (Monitors)
The RMICalls MBean provides statistics on the number of total and "recent" outgoing RMI calls to Windchill method servers calls and the average time consumed during that time span.
ServerManager
The ServerManager MBean provides a brief summary of some top-level server manager statistics. It is available for the server manager.
ServerManager (Monitors)
This MBean appears in the "Monitors" grouping in JConsole and differs from the ServerManager MBean which appears outside this grouping. This MBean runs in the servlet engine and monitors the local server manager via pings. It provides ping statistics, notifications upon server manager status change, and operations to start, stop, and restart the local server manager.
ServletRequests (Monitors)
The ServletRequests MBean monitors servlet requests and thus is only instantiated in the servlet engine. For those method servers that have an embedded Tomcat, the ServletRequests MBean is located under the following method server node:
> > >
Using the attributes for this MBean, you can set the logger levels to gather statistics. The following table shows the levels of statistics that can be gathered:
|
Statistics Grouping
|
Description
|
|
Total
|
Statistics accumulated since web application startup.
|
|
Baseline
|
Statistics accumulated since last invocation of the resetBaselineStatistics() operation (or since web application startup if this operation is never invoked).
|
|
Summary
|
Statistics accumulated for a time interval specified by the SummaryIntervalSeconds attribute. Summary statistics are logged but not reflected in the MBean attributes.
|
|
Recent
|
Statistics accumulated for a time interval specified by the RecentIntervalSeconds attribute. The corresponding Recent* MBean attributes are updated at the end of each measurement interval.
|
|
Request
|
Data for an individual servlet request.
|
|
|
You can set up which servlet requests are tracked and which statistics are gathered by setting values for the RequestLoggerOutputAttributes and StatisticLoggerOutputAttributes in this MBean.
|
|
|
To trace a user session into the method server, you can set RequestLoggerLevel to INFO and set the Id and SessionID in RequestLoggerOutputAttributes.
|
|
|
The RequestLoggerUseShortFormat attribute controls whether the Property Name is prepended to the value in the logs. If you put the column headings in Excel, you can set this to false and import the data more easily for analysis.
|
|
|
From the Operations node under the method server, you can use the captureActiveContexts button to capture running contexts. The contexts then display under ServletRequests MBean.
|
The ServletRequests MBean also provides a MaxAverageActiveRequestsThreshold attribute. When the average (concurrently) active requests over a summary statistics interval exceeds this threshold a JMX notification is sent. For information about notifications, see
Setting Up Your JMX Environment.
ServletSessions (Monitors)
The ServletSessions MBean monitors servlet sessions and thus is only instantiated in the servlet engine.
The ServletSessions MBean provides capabilities similar to those of the ServletRequest MBean, but for servlet sessions rather than for servlet requests. One difference is that the ServletSessions MBean does not provide a "capture" operation. Instead, you can set the SessionRegistrationEnabled attribute to true from which point new sessions will be represented using nested Session MBeans.
Summaries
The Summaries MBean is very similar to the NotificationHandlers MBean. It allows you to create and manage Summary MBeans which allow you to log attributes collected from one or more MBeans on a periodic basis. Therefore, Summary MBeans are much like NotificationHandler MBeans except that the trigger is a timer, not a notification, and that only logging, not emailing, is a possible result of the trigger.
PTC provides one out-of-the-box summary MBean named wt.summary.general that is instantiated to provide information summarizing basic JVM statistics.
|
|
PTC recommends that, at a minimum, you always include the log summary information provided by default so that you have a record of how the system is performing throughout the day. You can then add to the information or use it as is when troubleshooting system health and performance issues.
|
The value of the IntervalSeconds attribute determines how frequently this summary is logged. The default value is set to 600 seconds. This means that an entry similar to the following is added to the method server log every 10 minutes:
2010-12-10 17:48:54,501 INFO [wt.jmx.core.SharedScheduledExecutor.worker]
wt.summary.general Administrator - JVMName=4668@JMHOLLE03L,
HeapMemoryUsage=255381976, NonHeapMemoryUsage=136583088, Uptime=1518824,
ProcessCpuTime=199546875000, JITCTime=82080,
GarbageCollectors=[PS MarkSweep,PS Scavenge], GCTime=[3148,3217],
GCCount=[5,44], Classes=20148, Threads=83, TotalStartedThreadCount=465,
PermGenPercentCollUsage=40.03666542671822, PermGenPercentUsage=40.03666542671822
The items included in the out-of-the-box summary are described in the following table:
|
Item
|
Description
|
|
JVMName
|
Internal name of the JVM.
|
|
HeapMemoryUsage
|
Heap memory usage (in bytes).
|
|
NonHeapMemoryUsage
|
Memory usage that is not related to the heap (in bytes).
|
|
Uptime
|
Number of milliseconds since system startup.
|
|
ProcessCpuTime
|
CPU time used by the process (in nanoseconds).
|
|
JITCTime
|
Time spent by the Just In Time compiler (in milliseconds).
|
|
GarbageCollectors
|
List of the current garbage collectors (in this case, Copy and MarkSweepCompact).
|
|
GCTime
|
List of times spent by each garbage collector. Times are in milliseconds and are listed in the same order as the garbage collectors listed in the GarbageCollectors item. In the example, 5201 is the time spent by the Copy garbage collector and 34411 is the time spent by the MarkSweepCompact garbage collector.
|
|
GCCount
|
List of the number of garbage collector activities for each garbage collector. Numbers are listed in the same order as the garbage collectors listed in the GarbageCollectors item. In the example, 121 is the number of activities for the Copy garbage collector and 60 is the number of activities for the MarkSweepCompact garbage collector.
|
|
Classes
|
Number of classes that are loaded into the system.
|
|
Threads
|
Number of live threads in this Java process.
|
|
TotalStartedThreadCount
|
Number of threads started in this Java process since the process started.
|
|
PermGenPercentCollUsage
|
Percentage of perm gen in use right after the last garbage collection.
|
|
PermGenPercentUsage
|
Percentage of perm gen in use at the time of this log entry.
|
Support
The Support MBean provides a simple, straightforward operation for sending logs and JMX MBean data to PTC technical support. The Support MBean operation associates the sent information with an existing technical support call number. The Support MBean’s existence, life cycle, and configuration persistence are controlled by the Loader MBean.
For information about all of the actions that send data to PTC technical support, see
Actions that Send System Information.
TopSQL (Monitors)
The TopSQL MBean monitors SQL calls from the Windchill persistence layer in the method server. Within each time interval, this MBean tracks the most expensive SQL statements (in terms of total elapsed time).
When an SQL statement has a high number of calls or high total elapsed time, a representative state trace is also captured to aid in determining which portion of the application is making the calls.
The TopSQL monitor configuration is controlled by the Loader MBean.
UserSpecified (Monitors)
The UserSpecified monitors MBean allows the (administrative) user to create their own instances of the various built-in Java subclasses of javax.management.monitors.Monitor which are then managed and persisted through the UserSpecified monitors MBean.
The creation of the Monitor instances is done via operations on the UserSpecified monitors MBean whereas further configuration of the Monitor instances is done via attributes and operations on the Monitor instances themselves (which are also MBeans). The UserSpecified monitors MBean is instantiated out-of-the-box in all server JVMs.
VaultSites
The VaultSites MBean monitors the accessibility of Windchill vaulting sites to HTTP(S) requests. It periodically sends short, simple "ping" requests to all sites (including itself) and logs results. Aggregate statistics and last ping results are available using the SiteStatusInfo attribute. A JMX notification is generated whenever a site does not respond to a ping.
The VaultSites MBean is deployed into the method server by default; the file vaulting services requires this deployment.
WebAppContexts
The WebAppContexts MBean is only instantiated in the servlet engine and provides a top-level information node for an entire Web application. The WebAppContexts MBean is only available from those method servers that have an embedded Tomcat from:
>
WindchillVersion
The WindchillVersion MBean provides a summary of Windchill version information, including the products, patches, and locale support that have been installed. The WindchillVersion McBean’s existence, life cycle, and configuration persistence are controlled by the Loader MBean.
WrappedSockets
The WrappedSockets MBean provides visibility into the number of Windchill "WrappedSocket" RMI sockets and number of bytes sent and received over them. It is currently instantiated in both method server and server manager processes.
