Tests Disabled by Default for a Tomcat Server

The eG agent can be optionally configured to execute a few tests that report critical statistics related to CPU usage, thread usage, and the uptime of the Tomcat JVM. To enable one/more of these tests, go to the enable / disable tests page using the menu sequence : Agents -> Tests -> Enable/Disable, select Tomcat as the Component type, set Performance as the Test type, choose the test from the disabled tests list, and click on the < button to move the test to the ENABLED TESTS list. Finally, click the Update button.

To enable one/more of these tests, open the agents – tests configuration page using the Agents -> Tests -> Configure menu sequence, select Tomcat from the Component type list, scroll down the test list that appears to view the disabled tests section, select the check box corresponding to the JVM test of interest to you, and then, click the Update button. These tests have been discussed below.

Java Business Transactions Test

The responsiveness of a transaction is the key determinant of user experience with that transaction; if response time increases, user experience deteriorates. To make users happy, a Java business transaction should be rapidly processed by each of the JVM nodes in its path. Processing bottlenecks on a single JVM node can slowdown/stall an entire business transaction or can cause serious transaction errors. This in turn can badly scar the experience of users. To avoid this, administrators should promptly identify slow/stalled/errored transactions, isolate the JVM node on which the slowness/error occurred, and uncover what caused the aberration on that node – is it owing to SQL queries executed by the node? Or is it because of external calls – eg., async calls, SAP JCO calls, HTTP calls, etc. - made by that node? The Java Business Transactions test helps with this!

This test runs on a BTM-enabled JVM in an IT infrastructure, tracks all the transaction requests received by that JVM, and groups requests based on user-configured pattern specifications. For each transaction pattern, the test then computes and reports the average time taken by that JVM node to respond to the transaction requests of that pattern. In the process, the test identifies the slow/stalled transactions of that pattern, and reports the count of such transactions and their responsiveness. Detailed diagnostics provided by the test accurately pinpoint the exact transaction URLs that are slow/stalled, the total round-trip time of each transaction, and also indicate when such transaction requests were received by that node. The slowest transaction in the group can thus be identified.

For this test to run and report metrics on Tomcat, you first need to BTM-enable the Tomcat JVM. To know how, refer to the Installing eG Java BTM on an Apache Tomcat Server topic .

Then, proceed to configure this test. Refer to the Java Business Transactions Test topic to know how to configure this test and learn about the metrics it reports.

JVM Details Test

This reveals the health of the Tomcat class loaders and daemon threads, and also indicates JVM availability.

Target of the test : A Tomcat Server

Agent deploying the test : An internal agent

Outputs of the test : One set of results for the Tomcat server being monitored.

Configurable parameters for the test
Parameter	Description
Test Period	How often should the test be executed.
Host	The IP address of the host for which this test is to be configured.
Port	Refers to the port at which the specified host listens to.
Measurement Mode	This test can extract metrics from Tomcat using either of the following mechanisms: By deploying the egtomcat.war file in the <EG_INSTALL_DIR>\lib directory of the eG agent host on the Tomcat server; By contacting the Java runtime (JRE) of Tomcat via JMX To configure the test to use egtomcat.war file, first select the War file option. Then, refer to the How Does eG Enterprise Monitor Tomcat Servers? to know how to deploy the WAR file on the target Tomcat server. On the other hand, if you want the test to use JMX instead, then first, select the JMX option. Then, follow the procedure detailed in the How Does eG Enterprise Monitor Tomcat Servers? to configure the test to use jmx. By default, the JMX option is chosen here.
JMX Remote Port	This parameter appears only if the Measurement Mode is set to JMX. Here, specify the port at which the JMX listens for requests from remote hosts. Ensure that you specify the same port that you configured in the catalina.sh (or catalina.bat) file in the <CATALINA_HOME_DIR>/bin folder of the target Tomcat server (refer to the How Does eG Enterprise Monitor Tomcat Servers? for more details).
JMX User, JMX Password, and Confirm Password	These parameters appear only if the Measurement Mode is set to JMX. If JMX equires authentication only (but no security), then ensure that the JMX User and JMX Password parameters are configured with the credentials of a user with read-write access to JMX. To know how to create this user, refer to the How Does eG Enterprise Monitor Tomcat Servers?. Confirm the password by retyping it in the Confirm Password text box.
JNDIName	This parameter appears only if the Measurement Mode is set to JMX. The JNDIName is a lookup name for connecting to the JMX connector. By default, this is jmxrmi. If you have registered the JMX connector in the RMI registery using a different lookup name, then you can change this default value to reflect the same.
JMX Provider	This parameter appears only if the Measurement Mode is set to JMX. This test uses a JMX Provider to access the MBean attributes of the target Java application and collect metrics. Specify the package name of this JMX Provider here. By default, this is set to com.sun.jmx.remote.protocol.
SSL	This parameter appears only if the Measurement Mode is set to War File. Indicate Yes if the Tomcat server is SSL-enabled.
URL	This parameter appears only if the Measurement Mode is set to War File. Specify the URL of the managed Tomcat server to enable the test to connect to it and extract measures from it. The URL specification should be of the format: http://{TomcatIP}:{TomcatPort}.
UserName, Password, and Confirm Password	These parameters appear only if the Measurement Mode is set to War File. In the UserName text box, specify a name of a user who has been assigned the Manager role on the Tomcat server to be monitored; these users are typically allowed to control web applications deployed on the Tomcat server. Specify the Password of this user, and confirm the password by retyping it in the Confirm Password text box.
EncryptPass	This parameter appears only if the measurement modeis set to War File. Select Yes if you want to encrypt the password.
Timeout	Specify the duration (in seconds) for which this test should wait for a response from Tomcat. If there is no response from Tomcat beyond the configured duration, the test will timeout. By default, this is set to 240 seconds.

Measurements made by the test
Measurement	Description	Measurement Unit	Interpretation
Total classes loaded	Refers to the total number of classes that have been loaded since the Java virtual machine started execution.	Number
Classes loaded	Indicates the number of classes that have been loaded in the Java virtual machine since the last measurement period.	Number	Classes are fundamental to the design of Java programming language. Like many server applications, Tomcat installs a variety of class loaders (that is, classes that implement java.lang.ClassLoader) to allow different portions of the container, and the web applications running on the container, to have access to different repositories of available classes and resources. A consistent decrease in the number of classes loaded and unloaded could indicate a road-block in the loading/unloading of classes by the class loader. If left unchecked, critical resources/classes could be rendered inaccessible to web applications, thereby severely affecting application performance.
Classes unloaded	Indicates the total number of classes that have been unloaded in the Java virtual machine since the last measurement period.	Number
Total daemon threads	Indicates the current number of live daemon threads.	Number	The main function of the daemon threads is to provide service to other threads, running in the same process as the daemon thread. If the value of this measure is equal to that of the Live_threads measure, then JVM would stop executing; in other words, when the only remaining threads are the daemon threads, then JVM shuts down and so does Tomcat.
Live threads	Indicates the current number of live daemon and non-daemon threads.	Number
Deadlock threads	The current number of deadlock threads	Number	Ideally, the value of this measure should be 0. A non-zero value indicates the occurrence of a deadlock. When a thread attempts to acquire a resource that is already locked by another thread, a deadlock situation arises.
Server uptime	The uptime of Java virtual machine	Mins	To ensure that the JVM is up and running for a long time, you need to make sure that at least one non-daemon thread is executing at all times. This is because, without any non-daemon threads, the daemon threads have no recipients for the service it provides; it hence brings down both the JVM and Tomcat.

Tomcat JVM Garbage Collection Test

Manual memory management is time consuming, and error prone. Most programs still contain leaks. This is all doubly true with programs using exception-handling and/or threads. Garbage collection (GC) is a part of Tomcat's JVM that automatically determines what memory a program is no longer using, and recycles it for other use. It is also known as "automatic storage (or memory) reclamation''. This test reports the performance statistics pertaining to the JVM's garbage collection.

Target of the test : A Tomcat Server

Agent deploying the test : An internal agent

Outputs of the test : One set of results for the Tomcat server being monitored.

Configurable parameters for the test
Parameter	Description
Test Period	How often should the test be executed.
Host	The IP address of the host for which this test is to be configured.
Port	Refers to the port at which the specified host listens to.
Measurement Mode	This test can extract metrics from Tomcat using either of the following mechanisms: By deploying the egtomcat.war file in the <EG_INSTALL_DIR>\lib directory of the eG agent host on the Tomcat server; By contacting the Java runtime (JRE) of Tomcat via JMX To configure the test to use egtomcat.war file, first select the War file option. Then, refer to the How Does eG Enterprise Monitor Tomcat Servers? to know how to deploy the WAR file on the target Tomcat server. On the other hand, if you want the test to use JMX instead, then first, select the JMX option. Then, follow the procedure detailed in the How Does eG Enterprise Monitor Tomcat Servers? to configure the test to use jmx. By default, the JMX option is chosen here.
JMX Remote Port	This parameter appears only if the Measurement Mode is set to JMX. Here, specify the port at which the JMX listens for requests from remote hosts. Ensure that you specify the same port that you configured in the catalina.sh (or catalina.bat) file in the <CATALINA_HOME_DIR>/bin folder of the target Tomcat server (refer to the How Does eG Enterprise Monitor Tomcat Servers? for more details).
JMX User, JMX Password, and Confirm Password	These parameters appear only if the Measurement Mode is set to JMX. If JMX equires authentication only (but no security), then ensure that the JMX User and JMX Password parameters are configured with the credentials of a user with read-write access to JMX. To know how to create this user, refer to the How Does eG Enterprise Monitor Tomcat Servers?. Confirm the password by retyping it in the Confirm Password text box.
JNDIName	This parameter appears only if the Measurement Mode is set to JMX. The JNDIName is a lookup name for connecting to the JMX connector. By default, this is jmxrmi. If you have registered the JMX connector in the RMI registery using a different lookup name, then you can change this default value to reflect the same.
JMX Provider	This parameter appears only if the Measurement Mode is set to JMX. This test uses a JMX Provider to access the MBean attributes of the target Java application and collect metrics. Specify the package name of this JMX Provider here. By default, this is set to com.sun.jmx.remote.protocol.
SSL	This parameter appears only if the Measurement Mode is set to War File. Indicate Yes if the Tomcat server is SSL-enabled.
URL	This parameter appears only if the Measurement Mode is set to War File. Specify the URL of the managed Tomcat server to enable the test to connect to it and extract measures from it. The URL specification should be of the format: http://{TomcatIP}:{TomcatPort}.
UserName, Password, and Confirm Password	These parameters appear only if the Measurement Mode is set to War File. In the UserName text box, specify a name of a user who has been assigned the Manager role on the Tomcat server to be monitored; these users are typically allowed to control web applications deployed on the Tomcat server. Specify the Password of this user, and confirm the password by retyping it in the Confirm Password text box.
EncryptPass	This parameter appears only if the measurement modeis set to War File. Select Yes if you want to encrypt the password.
Timeout	Specify the duration (in seconds) for which this test should wait for a response from Tomcat. If there is no response from Tomcat beyond the configured duration, the test will timeout. By default, this is set to 240 seconds.

Measurements made by the test
Measurement	Description	Measurement Unit	Interpretation
No of collections	Indicates the number of garbage collections that were performed by the JVM since the last measurement period.	Number	If adequate memory is not allotted to the JVM, then the value of this measure would be very high. A high value of this measure is indicative of a high frequency of GC. This is not a good sign, as GC, during its execution, has the tendency of reducing the performance for applications, and a high frequency of GC would only adversely impact the application's performance. To avoid this, it is recommended that you allot sufficient memory to the JVM.
Time taken	Indicates the time taken for GC execution, since the last measurement period.	Secs	A shorter GC execution time is desired to avoid issues in application performance and database connection bottlenecks.
Elapsed time	Indicates the percentage of time spent on GC execution.	Percent	By carefully examining the application behavior in terms of memory utilization, you should arrive at an optimal ratio of the number of times the GC needs to run and how long it should take to complete. Accordingly, you can fine-tune the GC activity.

JVM Memory Test

The memory system of the Java Virtual machines manages two types of memory, which are Heap and Non Heap. To define Heap, the Java virtual machine is a heap that is the runtime data area from which memory for all class instances and arrays are allocated. It is created at the Java Virtual Machine start-up and the memory for the objects is reclaimed by an automatic memory management systems known as Garbage collector. The Heap may be of fixed size or may be expanded and shrunk.

The Java virtual machine has a method area that is shared among all threads. This method area is called non heap. It stores per class structures such as runtime constant pool field and method data, and the code for methods and constructors. It is created at the Java Virtual Machine start up.

In order to ensure the uninterrupted functioning of the Tomcat server, sufficient memory resources need to be made available to the JVM memory pools. Inadequacies in memory allocations could lead to slow start up issues or intermittent application failures. This test periodically reports usage statistics of the JVM memory pools, so that memory bottlenecks are promptly detected and resolved.

Target of the test : A Tomcat Server

Agent deploying the test : An internal agent

Outputs of the test : One set of results for the Tomcat server being monitored.

Configurable parameters for the test
Parameter	Description
Test Period	How often should the test be executed.
Host	The IP address of the host for which this test is to be configured.
Port	Refers to the port at which the specified host listens to.
Measurement Mode	This test can extract metrics from Tomcat using either of the following mechanisms: By deploying the egtomcat.war file in the <EG_INSTALL_DIR>\lib directory of the eG agent host on the Tomcat server; By contacting the Java runtime (JRE) of Tomcat via JMX To configure the test to use egtomcat.war file, first select the War file option. Then, refer to the How Does eG Enterprise Monitor Tomcat Servers? to know how to deploy the WAR file on the target Tomcat server. On the other hand, if you want the test to use JMX instead, then first, select the JMX option. Then, follow the procedure detailed in the How Does eG Enterprise Monitor Tomcat Servers? to configure the test to use jmx. By default, the JMX option is chosen here.
JMX Remote Port	This parameter appears only if the Measurement Mode is set to JMX. Here, specify the port at which the JMX listens for requests from remote hosts. Ensure that you specify the same port that you configured in the catalina.sh (or catalina.bat) file in the <CATALINA_HOME_DIR>/bin folder of the target Tomcat server (refer to the How Does eG Enterprise Monitor Tomcat Servers? for more details).
JMX User, JMX Password, and Confirm Password	These parameters appear only if the Measurement Mode is set to JMX. If JMX equires authentication only (but no security), then ensure that the JMX User and JMX Password parameters are configured with the credentials of a user with read-write access to JMX. To know how to create this user, refer to the How Does eG Enterprise Monitor Tomcat Servers?. Confirm the password by retyping it in the Confirm Password text box.
JNDIName	This parameter appears only if the Measurement Mode is set to JMX. The JNDIName is a lookup name for connecting to the JMX connector. By default, this is jmxrmi. If you have registered the JMX connector in the RMI registery using a different lookup name, then you can change this default value to reflect the same.
JMX Provider	This parameter appears only if the Measurement Mode is set to JMX. This test uses a JMX Provider to access the MBean attributes of the target Java application and collect metrics. Specify the package name of this JMX Provider here. By default, this is set to com.sun.jmx.remote.protocol.
SSL	This parameter appears only if the Measurement Mode is set to War File. Indicate Yes if the Tomcat server is SSL-enabled.
URL	This parameter appears only if the Measurement Mode is set to War File. Specify the URL of the managed Tomcat server to enable the test to connect to it and extract measures from it. The URL specification should be of the format: http://{TomcatIP}:{TomcatPort}.
UserName, Password, and Confirm Password	These parameters appear only if the Measurement Mode is set to War File. In the UserName text box, specify a name of a user who has been assigned the Manager role on the Tomcat server to be monitored; these users are typically allowed to control web applications deployed on the Tomcat server. Specify the Password of this user, and confirm the password by retyping it in the Confirm Password text box.
EncryptPass	This parameter appears only if the measurement modeis set to War File. Select Yes if you want to encrypt the password.
Timeout	Specify the duration (in seconds) for which this test should wait for a response from Tomcat. If there is no response from Tomcat beyond the configured duration, the test will timeout. By default, this is set to 240 seconds.

Measurements made by the test
Measurement	Description	Measurement Unit	Interpretation
Used	Indicates the amount of memory currently in use.	MB
Free	Indicates the amount of unused memory currently available in a server.	MB	Ideally, this value should be high. An unusually low value for the available memory can indicate a memory bottleneck. Check the memory utilization of individual processes to figure out the process(es) that has (have) maximum memory consumption and look to tune their memory usages and allocations accordingly.
Initial	Indicates the initial amount of memory that Java virtual machine requests from the operating system (OS) for memory management during startup.	MB	An unusually high usage of memory by the Java Virtual machine from the OS is a cause of concern. Further analysis is required to determine if specific applications or queries are consuming excess memory.
Pending objects	Indicates the number of objects in the heap/non-heap memory for which finalization is pending.	Number	Finalization allows an object to gracefully clean up after itself when it is being collected. When the garbage collector detects that an object is garbage, the garbage collector calls the object's Finalize method (if it exists) and then the object's memory is reclaimed - in other words, the garbage collector frees the memory allocated to the object. This measure is available only for the Heap_Memory and Nonheap_Memory descriptors of this test. A high value for this measure indicates that a chunk of heap / non-heap memory (as the case may be) in the JVM is awaiting reclamation. Object finalization facilitates efficient memory re-use, and thus ensures that the JVM memory pools do not run out of memory. If the value of this measure grows continuously, it could imply that objects are not releasing the memory resources properly. This in turn could be because the Finalize method does not exist for some objects, or there could be a bottleneck in the invocation of the method. Either way, thorough investigation can only provide pointers to the source of the problem.