Installing and Configuring the MAT Plugin

Before installing the MAT plugin, make sure that the following requirements are in place:

• To make optimum use of the available memory, the eG agent on AIX runs the JVM Memory Usage test as a separate process. Sufficient memory should be available to this process to analyze heap dump. This memory size depends upon heap dump size. For instance, to analyse heap dump of size 2 GB, the process needs free memory of size 4 GB. This implies that the process should be sized with 100% more memory than the heap dump size. This can be configured in the following manner:
  • Edit the eg_tests.ini file in the /opt/egurkha/manager/config directory

  • In the [DD_ROWS] section of the file, configure the following parameters:

    Xms = <Initial heap size>

    Xmx=<Maximum heap size>

    By default, both these parameters are set to 2048M. You can change the value of these parameters based on what the heap dump size is.

  • Finally, save the file.

• Next, make sure that the /tmp directory in the AIX system has sufficient free space. This is because, the heap dump files will be stored and analyzed in this folder only. The space requirement of this folder too will vary with heap dump size. For instance, if the heap dump size is 40 MB, then for the MAT plugin to analyze memory usage, 50% more free space is required in the /tmp directory – i.e., 60 MB of free space.

To install the plugin, do the following:

1. Download the MAT plugin and extract it into the egurkha directory on the AIX system hosting the eG agent. The steps in this regard are as follows:

   • Download the MAT plugin, mat_plugin_AIX_PPC64.tar.gz, from the site.
   • Copy the plugin to the /opt/egurkha folder.

   • Next, issue the following command from the AIX shell prompt, to unzip the MAT plugin zip file:

     gunzip mat_plugin_AIX_PPC64.tar.gz

   • Next, issue the following command:

     tar –xvf mat_plugin_AIX_PPC64.tar

   • A folder named 'mat' will now be created in the /opt/egurkha folder.

2. Configure the Java application/container on AIX to perform heap analysis. For this, insert the following in the JVM arguments section of the start-up script of the application/application server, and then save the file:

   -Xdump:java:none -Xdump:heap:file=/tmp/egi_heapdump.%Y%m%d.%H%M%S.%pid.%seq.phd

3. You may also want to fine-tune the following parameters in the [DD_ROWS] section of the eg_tests.ini file:

   • Heap_File_Generation_TimeOut – (Default: 5 minutes) This is the time up to which the eG agent can write to the heap dump file. If the agent tries to continue writing to the file after this duration, then the file will be deleted. This means, that no DD will be reported by the agent. To avoid this, set the timeout period according to the heap dump size. Larger the size of the heap dump, higher should be the timeout value.
   • Heap_Analyzing_TimeOut – (Default: 120 minutes) This is the time up to which the MAT plugin should read and analyze the data in the heap dump file . If the plugin is not able to finish analyzing the data in the heap dump file within the configured duration, then detailed diagnostics will not be reported. To avoid this, set the time period according to the heap dump size. Larger the size of the heap dump, higher should be the timeout value.
4. Finally, restart the application / application server.