5 Monitoring Applications

This chapter describes how to use the provided JMX MBeans to monitor the health and performance of Coherence*Web on your system.It also describes how to run the Reporter—a JMX-based reporting utility that provides several preconfigured reports that help administrators and developers manage capacity and troubleshoot problems.

This chapter contains the following sections:

Note:

To enable Coherence*Web JMX Management and Monitoring, this section assumes that you have first set up the Coherence Clustered JMX Framework. To set up this framework, see the configuration and installation instructions in "Using JMX to Manage Coherence" in Managing Oracle Coherence.

5.1 Managing and Monitoring Applications with JMX

The management attributes and operations for Web applications that use Coherence*Web for HTTP session management are visible through the HttpSessionManagerMBean MBean (com.tangosol.coherence.servlet.management.HttpSessionManagerMBean).

During startup, each Coherence*Web Web application registers a single instance of the HttpSessionManager class. You can use a monitoring tool, such as JConsole, to view the values of the MBean attributes. The MBean is unregistered when the Web application shuts down.

Table 5-1 describes the object name that the MBean uses for registration.

Table 5-1 Object Name for HttpSessionManagerMBean

Managed Bean	Object Name
`HttpSessionManager`	`type`=`HttpSessionManager`, `nodeId=cluster` `node` `id`, `appId`=`web` `application` `id`

Table 5-2 describes the information that HttpSessionManager provides. All of the names represent attributes, except resetStatistics, which is an operation.

Several of the MBean attributes use the following prefixes:

LocalSession, which indicates a session that is not distributed to all members of the cluster. The session remains local to the originating server until a later point in the life of the session.
LocalAttribute, which indicates a session attribute that is not distributed to all members of the cluster.
Overflow, a cache which stores the large session attributes when the Split Session model is used.

Table 5-2 Information Returned by the HttpSessionManager

Attribute Name	Data Type	Description
`AverageReapDuration`	long	The average reap duration (the time it takes to complete a reap cycle) in milliseconds, since the statistic was reset. See "Getting Session Reaper Performance Statistics".
`CollectionClassName`	String	The fully qualified class name of the `HttpSessionCollection` implementation in use. The `HttpSessionCollection` interface is an abstract model for a collection of `HttpSessionModel` objects. The interface is not at all affected by how the sessions communicate between the clients and the servers.
`FactoryClassName`	String	The fully-qualified class name of the `Factory` implementation being used. The `SessionHelper.Factory` class is used by the `SessionHelper` class to obtain objects that implement various important parts of the servlet specification. The `Factory` implementation can be placed in front of the application instead of the application server's own objects. This changes the apparent implementation of the application server itself (for example, adding clustering.)
`LastReapDuration`	long	The amount of time, in milliseconds, it took for the last reap cycle to finish. See "Getting Session Reaper Performance Statistics".
`LocalAttributeCacheName`	String	The name of the local cache that stores non-distributed session attributes. If the attribute displays null then local session attribute storage is disabled.
`LocalAttributeCount`	Integer	The number of non-distributed session attributes stored in the local session attribute cache. If the attribute displays `-1`, then local session attribute storage is disabled.
`LocalSessionCacheName`	String	The name of the local cache that stores nondistributed sessions. If the attribute displays a null value, then local session storage is disabled.
`LocalSessionCount`	Integer	The number of nondistributed sessions stored in the local session cache. If the attribute displays a -1 value, then local session storage is disabled.
`MaxReapedSessions`	long	The maximum number of sessions reaped in a reap cycle since the statistic was reset. See "Getting Session Reaper Performance Statistics".
`NextReapCycle`	java.lang.Date	The time, expressed as a `java.lang.Date` data type, for the next reap cycle. See "Getting Session Reaper Performance Statistics".
`OverflowAverageSize`	Integer	The average size (in bytes) of the session attributes stored in the overflow clustered cache since the last time statistics were reset. If the attribute displays `-1`, then a `SplitHttpSessionCollection` model is not in use.
`OverflowCacheName`	String	The name of the clustered cache that stores the large attributes that exceed a certain size and thus are determined to be more efficiently managed as separate cache entries and not as part of the serialized session object itself. A null value is displayed if a `SplitHttpSessionCollection` model is not in use.
`OverflowMaxSize`	Integer	The maximum size (in bytes) of a session attribute stored in the overflow clustered cache since the last time statistics were reset. The attribute displays a -1 value if a `SplitHttpSessionCollection` model is not in use.
`OverflowThreshold`	Integer	The minimum length (in bytes) that the serialized form of an attribute value must be stored in the separate overflow cache that is reserved for large attributes. The attribute displays a -1 value if a `SplitHttpSessionCollection` model is not in use.
`OverflowUpdates`	Integer	The number of updates to session attributes stored in the overflow clustered cache since the last time statistics were reset. The attribute displays a -1 value if a `SplitHttpSessionCollection` model is not in use.
`ReapedSessions`	long	The number of sessions reaped during the last cycle. See "Getting Session Reaper Performance Statistics".
`ReapedSessionsTotal`	long	The number of expired sessions that have been reaped since the statistic was reset. See "Getting Session Reaper Performance Statistics".
`ServletContextCacheName`	String	The name of the clustered cache that stores `javax.servlet.ServletContext` attributes. The attribute displays `null` if `ServletContext` is not clustered.
`ServletContextName`	String	The name of the Web application `ServletContext`.
`SessionAverageLifetime`	Integer	The average lifetime (in seconds) of session objects invalidated (either due to expiration or to an explicit invalidation) since the last time statistics were reset.
`SessionAverageSize`	Integer	The average size (in bytes) of session objects placed in the session storage clustered cache since the last time statistics were reset.
`SessionCacheName`	String	The name of the clustered cache that stores serialized session objects.
`SessionIdLength`	Integer	The length (in characters) of generated session IDs.
`SessionMaxSize`	Integer	The maximum size (in bytes) of a session object placed in the session storage clustered cache since the last time statistics were reset.
`SessionMinSize`	Integer	The minimum size (in bytes) of a session object placed in the session storage clustered cache since the last time statistics were reset.
`SessionStickyCount`	Integer	The number of session objects that belong to this instance of the Web application. The attribute displays `-1` if sticky session optimizations are disabled.
`SessionTimeout`	Integer	The session expiration time (in seconds). The attribute displays `-1` if sessions never expire.
`SessionUpdates`	Integer	The number of updates of session object stored in the session storage clustered cache since the last time statistics were reset.
`resetStatistics` (operation)	void	Reset the session management statistics.

Figure 5-1 illustrates the attributes of the HttpSessionManager MBean displayed in the JConsole monitoring tool.

Figure 5-1 HttpSessionManager Displayed in the JConsole Monitoring Tool

Description of "Figure 5-1 HttpSessionManager Displayed in the JConsole Monitoring Tool"

5.1.1 Managing and Monitoring Applications on WebLogic Server

For WebLogic Server, management attributes and operations for Web applications that use Coherence*Web for HTTP session management are visible through the WebLogicHttpSessionManagerMBean MBean (com.tangosol.coherence.servlet.management.WebLogicHttpSessionManagerMBean).

Table 5-3 describes the object name that the MBean uses for registration.

Table 5-3 Object Name for WebLogicHttpSessionManagerMBean

Managed Bean	Object Name
WebLogicHttpSessionManager	`type`=`WebLogicHttpSessionManager`, `nodeId=cluster` `node` `id`, `appId`=`web` `application` `id`

The WebLogicHttpSessionManager class extends the HttpSessionManager class. In addition to the information described in Table 5-2, the WebLogicHttpSessionManager class also returns the information listed in Table 5-4. Enterprise Manager uses this information to correlate the Coherence*Web instances to the server.

Table 5-4 Information Returned by the WebLogicHttpSessionManager MBean

Attribute Name	Data Type	Description
`ApplicationId`	String	The WebLogic Web application ID.
`ApplicationName`	String	The name of this Web application.
`ApplicationVersion`	String	The version of this Web application.
`DomainName`	String	The WebLogic domain name on which the application is deployed.
`IsEar`	Boolean	Displays `true` if this Web application is a module of an EAR file.
`IsListenAddressEnabled`	Boolean	Displays `true` if a HTTP port is available on this server.
`IsSSLListenPortEnabled`	Boolean	Displays `true` if a HTTPS port is available on this server.
`ListenAddress`	String	The address on which the server is listening.
`ListenPort`	Integer	The port on which this server listens for HTTP requests.
`ServerName`	String	The WebLogic Server name on which the application is deployed.
`SSLListenPort`	Integer	The port on which this server is listening for HTTPS requests.

5.2 Running Performance Reports

Note:

You can find a detailed discussion of the Reporter, including configuring the Reporter, running preconfigured reports, and creating custom reports, in the chapters under "Using JMX Reporting" in Managing Oracle Coherence.

Coherence includes a JMX-based reporting utility known as the Reporter. The Reporter provides several preconfigured reports that help administrators and developers manage capacity and troubleshoot problems. These reports are specially tuned for Coherence*Web:

Web Session Storage Report, which records statistics about the activity between the cluster and the cache where the cluster's session objects and data are stored.
Web Session Overflow Report, which records statistics about the activity between the cluster and the cache where session objects and data are allowed to overflow from the Web session storage cache.
Web Report, which records information about Coherence*Web activity for the cluster.
WebLogic Web Report, which is intended for WebLogic Server environments. This report provides the same information as Web Report, but includes the name of the WebLogic Server and the WebLogic Server domain.
Web Service Report, which records information about the service running the Coherence*Web application.

The Coherence*Web reports should be run as part of a batch report. They are defined in both the report-web-group.xml and the comprehensive report-all.xml batch reports. You can also include them in a custom batch report. The Coherence*Web reports are not defined in the default report group batch file, report-group.xml.

The Reporter runs the report-group.xml batch report by default. Use the coherence.management.report.configuration system property to run report-web-group.xml, report-all.xml, or a custom batch report instead. Example 5-1 illustrates a command line where the property is used to change the report group batch file that is run to report-web-group.xml.

The report-web-group.xml, report-all.xml, and report-group.xml report group batch files, can be found in the reports folder in the coherence.jar file.

Example 5-1 Specifying a Report Group on the Command Line

java -Dcom.sun.management.jmxremote
-Dcoherence.management=all
-Dcoherence.management.remote=true
-Dcoherence.management.report.autostart=false
-Dcoherence.management.report.distributed=false
-Dcoherence.management.report.configuration=reports/report-web-group.xml
-jar coherence.jar

5.2.1 Web Session Storage Report

The Web Session Storage report records statistics on the activity between the cluster and the cache where session objects and data are stored. The statistics include information about the number of put, get, and prune operations performed on the session storage cache, and the amount of time spent on these operations.

The report is a tab-delimited file that is prefixed with the date in YYYYMMDDHH format and appended with -session-storage.txt. For example 2010013113-session-storage.txt would be created on January 31, 2010 1:00 pm. Table 5-5 describes the contents of the Web Session Storage report.

Table 5-5 Contents of the Web Session Storage Report

Column Title	Data Type	Description
`Batch` `Counter`	long	A sequential counter to help integrate information between related files. This value resets when the reporter restarts and is not consistent across nodes. However, it is helpful when trying to integrate files.
`Cache` `Name`	String	Always `session-storage`. It is used to maintain consistency with the Cache Utilization report.
`Evictions`	long	The total number of sessions that have been evicted for the cache across the cluster since the last time the report was created.
`Report` `Time`	Date	The system time when the report was created.
`Tier`	String	The value can be either `front` or `back`. Describes whether the cache resides in the front tier (local cache) or back tier (remote cache).
`TotalFailures`	long	The total number of session storage write failures for the cache across the cluster since the last time the report was created.
`TotalGets`	long	The total number of session get operations across the cluster since the last time the report was created.
`TotalGetsMillis`	long	The total number of milliseconds spent for each `get()` invocation (`GetsMillis`) to get the sessions across the cluster since the last time the report was created.
`TotalHits`	long	The total number of session hits across the cluster since the last time the report was created.
`TotalHitsMillis`	long	The total number of milliseconds spent for each `get()` invocation that is a hit (`HitsMillis`) for the session storage across the cluster since the last time the report was created.
`TotalMisses`	long	The total number of sessions get operations that returned misses for the cache across the cluster since the last time the report was created.
`TotalMissesMillis`	long	The total number of milliseconds spent for each `get()` invocation that is a miss (`MissesMillis`) for the session storage across the cluster since the last time the report was created.
`TotalPrunes`	long	The total number of times the session storage cache has been pruned across the cluster since the last time the report was created.
`TotalPrunesMillis`	long	The total number of milliseconds spent for the prune operation (`PrunesMillis`) to prune the session storage cache across the cluster since the last time the report was created.
`TotalPuts`	long	The total number of session updates (put operations) across the cluster since the last time the report was created.
`TotalPutsMillis`	long	The total number of milliseconds spent for each `put()` invocation (`PutsMillis`) to update sessions across the cluster since the last time the report was created.
`TotalQueue`	long	The sum of the queue links for the session storage cache across the cluster.
`TotalWrites`	long	The total number of sessions written to an external cache storage for the cache across the cluster since the last time the report was created.
`TotalWritesMillis`	long	The total number of milliseconds spent for each write operation (`WritesMillis`) to update an external cache storage across the cluster since the last time the report was created.

5.2.2 Web Session Overflow Report

The Web Session Overflow report records statistics on the activity between the cluster and the cache where the overflow of session objects and data is stored. The statistics include information about the number of put, get, and prune operations performed on the session overflow cache, and the amount of time spent on these operations.

The report is a tab-delimited file that is prefixed with the date in YYYYMMDDHH format and appended with -cache-session-overflow.txt. For example 2010013113-cache-session-storage.txt would be created on January 31, 2010 1:00 pm. Table 5-6 describes the contents of the Web Session Overflow report.

Table 5-6 Contents of the Web Session Overflow Report

Column Title	Data Type	Description
`Batch` `Counter`	long	A sequential counter to help integrate information between related files. This value does reset when the Reporter restarts and is not consistent across nodes. However, it is helpful when trying to integrate files.
`Cache` `Name`	String	Always `session-overflow`. It is used to maintain consistency with the Cache Utilization report.
`Evictions`	long	The total number of session overflows that have been evicted for the cache across the cluster since the last time the report was created.
`Report` `Time`	Date	The system time when the report executed.
`Tier`	String	The value can be either `front` or `back`. Describes whether the cache resides in the front-tier (local cache) or back tier (remote cache).
`TotalFailures`	long	The total number of session overflows storage write failures for the cache across the cluster since the last time the report was created.
`TotalGets`	long	The total number of session overflows get operations across the cluster since the last time the report was created.
`TotalGetsMillis`	long	The total number of milliseconds spent for each `get()` invocation (`GetsMillis`) to get the session overflows across the cluster since the last time the report was created.
`TotalHits`	long	The total number of session overflow hits across the cluster since the last time the report was created.
`TotalHitsMillis`	long	The total number of milliseconds spent for each `get()` invocation that is a hit (`HitsMillis`) for the session overflow across the cluster since the last time the report was created.
`TotalMisses`	long	The total number of session overflow get operations that returned misses for the cache across the cluster since the last time the report was created.
`TotalMissesMillis`	long	The total number of milliseconds spent for each `get()` invocation that is a miss (`MissesMillis`) for the session overflow across the cluster since the last time the report was created.
`TotalPrunes`	long	The total number of times the session overflow cache has been pruned across the cluster since the last time the report was created.
`TotalPrunesMillis`	long	The total number of milliseconds spent for the prune operations (`PrunesMillis`) to prune the session overflow cache across the cluster since the last time the report was created.
`TotalPuts`	long	The total number of session overflows (put operations) across the cluster since the last time the report was created.
`TotalPutsMillis`	long	The total number of milliseconds spent per `put()` invocation (`PutsMillis`) to update session overflows across the cluster since the last time the report was created.
`TotalQueue`	long	The sum of the queue link size for the session overflow cache across the cluster.
`TotalWrites`	long	The total number of session overflows written to an external cache storage for the cache across the cluster since the last time the report was created.
`TotalWritesMillis`	long	The total number of milliseconds spent for each write operation (`WritesMillis`) to update an external session overflow storage across the cluster since the last time the report was created.

5.2.3 Web Report

The Web Report (report-web.xml) provides information about Coherence*Web activity for the cluster. The report is a tab-delimited file that is prefixed with the date and hour in YYYYMMDDHH format and appended with -web.txt. For example 2009013102-web.txt would be created on January 1, 2009 at 2:00 am. Table 5-7 describes the contents of the Web Report.

Table 5-7 Contents of the Web Report

Column	Data Type	Description
`Application`	String	The application name.
`Batch` `Counter`	long	A sequential counter to help integrate information between related files. This value does reset when the Reporter restarts and is not consistent across nodes. However, it is helpful when trying to integrate files.
`Current` `Overflow` `Updates`	long	The number of overflow updates since the last time the report was created.
`Current` `Session` `Updates`	long	The number of session updates since the last time the report was created.
`LocalAttributeCount`	long	The attribute count on the node.
`LocalSessionCount`	long	The session count on the node.
`Node` `Id`	integer	The node identifier.
`OverflowAvgSize`	float	The average size for attribute overflows.
`OverflowMaxSize`	long	The maximum size for an attribute overflow.
`OverflowUpdates`	long	The total number of attribute overflow updates since the last time statistics were reset.
`Report` `Time`	Date	The system time when the report was created.
`SessionAverageLifetime`	float	The average number of seconds a session is active.
`SessionAverageSize`	float	The average size for a session.
`SessionMaxSize`	long	The maximum size for a session.
`SessionMinSize`	long	The minimum size for a session.
`SessionStickyCount`	long	The number of sticky sessions on the node.
`SessionUpdateCount`	long	The number of session updates since the last time statistics were reset.

5.2.4 WebLogic Web Report

The Weblogic Web Report (report-web-weblogic.xml) provides information on Coherence*Web activity when it is being used in WebLogic Server environments. This report provides the same information as provided by the Web Report (see "Web Report", above), with additional columns for the WebLogic Server name and domain name. The report is a tab-delimited file that is prefixed with the date and hour in YYYYMMDDHH format and appended with -web-weblogic.txt. For example 2009013102-web-weblogic.txt would be created on January 1, 2009 at 2:00 am.

Table 5-8 Contents of the WebLogic Web Report

Column	Data Type	Description
`Application`	String	The application name.
`Batch` `Counter`	long	A sequential counter to help integrate information between related files. This value does reset when the Reporter restarts and is not consistent across nodes. However, it is helpful when trying to integrate files.
`Current` `Overflow` `Updates`	long	The number of overflow updates since the last time the report was created.
`Current` `Session` `Updates`	long	The number of session updates since the last time the report was created.
`DomainName`	String	The name of the WebLogic Server domain in which Coherence*Web is running.
`LocalAttributeCount`	long	The attribute count on the node.
`LocalSessionCount`	long	The session count on the node.
`Node` `Id`	integer	The node identifier.
`OverflowAvgSize`	float	The average size for attribute overflows.
`OverflowMaxSize`	long	The maximum size for an attribute overflow.
`OverflowUpdates`	long	The total number of attribute overflow updates since the last time statistics were reset.
`Report` `Time`	Date	The system time when the report was created.
`ServerName`	String	The name of the WebLogic Server on which Coherence*Web is running.
`SessionAverageLifetime`	float	The average number of seconds a session is active.
`SessionAverageSize`	float	The average size for a session.
`SessionMaxSize`	long	The maximum size for a session.
`SessionMinSize`	long	The minimum size for a session.
`SessionStickyCount`	long	The number of sticky sessions on the node.
`SessionUpdateCount`	long	The number of session updates since the last time statistics were reset.

5.2.5 Web Service Report

The Web Service report provides information about the service running the Coherence*Web application. The report records the requests processed, request failures, and request backlog, tasks processed, task failures, and task backlog. Request Count and Task Count are useful to determine performance and throughput of the service. RequestPendingCount and Task Backlog are useful in determining capacity issues or blocked processes. Task Hung Count, Task Timeout Count, Thread Abandoned Count, Request Timeout Count are the number of unsuccessful executions that have occurred in the system.

The report is a tab-delimited file that is prefixed with the date and hour in YYYYMMDDHH format and appended with -web-session-service.txt. For example 2009013102-web-session-service.txt would be created on January 1, 2009 at 2:00 am. Table 5-9 describes the contents of the Web Service Report.

Table 5-9 Contents of the Web Service Report

Column Title	Data Type	Description
`Batch` `Counter`	Long	A sequential counter to help integrate information between related files. This value does reset when the Reporter restarts and is not consistent across nodes. However, it is helpful when trying to integrate files.
`Node` `Id`	String	The numeric node identifier.
`Refresh` `Time`	Date	The system time when the service information was updated from a remote node.
`Request` `Count`	Long	The number of requests by the Coherence*Web application since the last report was created.
`RequestPendingCount`	Long	The number of pending requests by the Coherence*Web application at the time of the report.
`RequestPendingDuration`	Long	The duration for the pending requests of the Coherence*Web application at the time of the report.
`Request` `Timeout` `Count`	Long	The number of request timeouts by the Coherence*Web application since the last report was created.
`Report` `Time`	Date	The system time when the report executed.
`Service`	String	A static value (`DistributedSessions`) used as the service name if merging the information with the service file.
`Task` `Backlog`	Long	The task backlog of the Coherence*Web application at the time of the report was created.
`Task` `Count`	Long	The number of tasks executed by the Coherence*Web application since the last report was created.
`Task` `Hung` `Count`	Long	The number of tasks that were hung by the Coherence*Web application since the last report was created.
`Task` `Timeout` `Count`	Long	The number of task timeouts by the Coherence*Web application since the last report was created.
`Thread` `Abandoned` `Count`	Long	The number of threads abandoned by the Coherence*Web application since the last report was created.