This section includes the following topics:

For instructions on remote monitoring of your J2EE instance, refer to the Installing Precise Components.

Installation Types

Before beginning the installation process, review the (JVM) instances you wish to monitor and choose the most applicable type of installation according to your needs.

J2EE instances can be installed in one of the three following ways:

  • Standalone Installation. Standalone installation enables you to install a single instance and define the instance name and configuration. This instance is not connected to or affected by any other instance configuration. After completing the pre-installation tasks, see Installing a standalone J2EE Tier instance.
  • Cluster Installation. Cluster installation defines the configuration parameters for a group of instances in a central location. Once a cluster is defined, a set of startup arguments is created. All instances with these startup arguments will automatically be installed as part of the cluster and share the same configuration.
    Each instance in the cluster is given a name that includes both the user defined cluster name and an automatically generated unique identifier.
    It is recommended to install a cluster when the following conditions apply:
    • The application is deployed on more than one JVM.
    • New JVMs are created automatically.
    • The startup parameters are located in a central location and are shared by all instances in the clusters.
    • There is no need for specific, user-defined instance names.
    After completing the pre-installation tasks, see Installing a J2EE cluster.
  • Shared Configuration. Shared configuration enables the user to use configuration parameters from a different, already installed instance. Each instance using shared configuration is given a user-defined name, but will share all configuration, as defined in the configuration files in the registry. After completing the pre-installation tasks, see Using shared configuration in Precise for J2EE.

Pre-installation tasks

This section describes the pre-installation tasks for the J2EE Collector.

J2EE Collector

  • If the J2EE Collector is hosted on an AIX server, verify that the Precise user limits for the Precise user are unlimited for data.
  • The application server user (regardless of the application server type) must have the following file system permissions:

Table 11-1 File system permissions

FolderPermissionsJustification
<precise_root>/logsRead/WriteWrite log file, log file rotation
<precise_root>/products/j2eeRead/WriteVarious configuration files, status files

J2EE Collector network ports

The Precise for J2EE Collectors uses network ports to communicate with the monitored JVMs. The default port that Precise for J2EE uses is: 20763.

Installing a standalone J2EE Tier instance

This section describes the installation procedure for installing a single, independent J2EE Tier instance. For information on editing or removing an existing instance, see Editing or removing tier instances or clusters.

Adding a J2EE Tier instance

Before adding a Tier instance, create a list of all required inputs based on the screen information below.

To add a Tier instance

  1. From StartPoint, click the AdminPoint tab.
  2. Click the Setup tab.
  3. From the drop-down menu, select Instances & Clusters.
  4. Click the All instances tree item.
  5. At the bottom of the Display Instances & Clusters screen, click Add Instance. The Add New Instance dialog box appears.
  6. Select the required technology from the list.
  7. Select the application from the list.
    If the desired application is not on the list, perform the following steps:
    1. Click Add.
    2. In the Name field, type in the new application name.
    3. In the Node field, select the system application from the list.

    4. Click OK.

      To install an instance in an application, you must have ADMINISTRATE.INSTALL permission for the application in which you want to install the instance. If you only have permission for a specific technology, you will only be able to install in an application that is either empty, or is comprised of only the same technology.

  8. Select a Tier from the list.

  9. Click OK to open the J2EE Instance Installation - Property Settings dialog box. See Defining J2EE property settings.

    Always refresh AdminPoint after adding an instance.

Defining J2EE property settings

To enter J2EE property settings

  1. Click the drop-down menu to select the server where the JVM is running. If you want to add a new server, click Add. For more information, see see Adding a new server.

    This is the name or IP address of the server where you want to install the J2EE Tier Collector. The server name appears in the list only if you previously defined it as a Precise Server. In upgrade mode, the list contains all servers that were installed or upgraded. Choose a server that was upgraded.

  2. Select an auto-detected JVM from the "Detected JVMs" list. The remaining text boxes are auto-filled, but may be edited as needed.
  3. If the JVM you want to monitor is not detected then proceed as follows:

    1. Click the drop-down menu to select the application server type.

      This is the type of the J2EE application server. Precise supports several J2EE application server types, including Oracle WebLogic, IBM WebSphere, Oracle AS, and Apache Tomcat.

    2. Click the drop-down menu to select the application server version.

      The next two items are optional, but are required to enable automatic execution of post-installation action items.

    3. Enter the full path to the Java executable.

    4. Mark the “WebLogic instance configured through admin console” check box.

      For Precise to instrument the JVM, it must modify its startup configuration. A WebLogic instance is configured using either a local file on the instance machine, or settings configured in the WebLogic admin console. Select this option if installing a WebLogic instance that is configured through the WebLogic admin console.

  4. Enter the instance (JVM) name.

    The instance name should be an alphanumeric string to be used by J2EE, Insight, Alerts, and Report Manager to identify the monitored application server instance. The instance name must be unique to the monitored host.

  5. Click Next. A preview of the planned installation will be displayed for approval at the beginning of the installation process.

About the AdminPoint Tier installation preview screen

The preview screen signifies that the AdminPoint Tier installer has gathered enough information to begin the installation phase.

The preview screen displays the following details before installation begins:

  • Server name or IP address
  • The name of the monitored server
  • What actions will be performed in their respective order
  • Installation folder (location)
  • Required disk space
  • Currently available disk space

At this screen, you can still change any of the settings displayed. Click Back to change any of the displayed settings. Click Install to continue installation. Click Cancel to stop the installation process.

About the AdminPoint Tier installation progress screen

This screen appears when the AdminPoint Tier installer is actually performing the installation. Installation may take several minutes. The progress screen visually displays the progress of actual installation on selected servers.

About the AdminPoint Tier installation complete screen

This screen appears when the AdminPoint Tier Installer has completed installation of all Tier instances.

If there are no action items, click Finish (it will be the only option available) to complete the instance installation. If there are action items, click Next (it will be the only option available).

About the AdminPoint Tier Action Items screen

After a Tier instance is installed, you must perform post-installation tasks as may be required. Only after completing any post-installation tasks required can you start using the Tier instances you have just installed.

Perform any tasks displayed on this screen. For Precise to perform the action items, click Execute. If you have performed the action items yourself, click Mark as done.

Installing a J2EE cluster

This section describes the procedures that are needed to install a J2EE cluster. A J2EE cluster is defined as a set of JVMs that share the same instrumentation configuration and are started from a shared location. Installing a J2EE cluster has two parts. The first one, described below, consists of creating a repository for the cluster configuration based on the definition of any of the cluster's JVM and performing the action items on the shared location. Once the action items are performed and JVMs are restarted, the second part of the installation takes place and each JVM instance is installed automatically and Precise starts to monitor it.

When installing a J2EE cluster, verify that Precise is installed on all servers hosting JVMs that are part of the cluster. In the cluster script, the javaagent flag points to the Precise JAR file in each JVM installed as part of the cluster. If a server hosting a JVM that is part of the cluster does not have Precise installed, the JAR file will be missing, and all JVMs on that server will fail to start.

For information on editing or removing an existing cluster, see Editing or removing tier instances or clusters.

Adding a J2EE cluster

Before adding a cluster, create a list of all required inputs based on the screen information below.

To add a cluster

  1. From StartPoint, click the AdminPoint tab.
  2. Click the Setup tab.
  3. From the drop-down menu, select Instances & Clusters.
  4. Click the All clusters tree item.
  5. At the bottom of the Display Instances and Clusters screen, click Add Cluster. The Add New Cluster dialog box appears.
  6. Select the J2EE technology from the list.
  7. Select the application from the list.
    If the desired application is not on the list, use the following steps:
    1. Click Add.
    2. In the Name field, type in the new application name.
    3. In the Node field, select the Tier from the list.

    4. Click OK.

      To install a cluster in an application, you must have explicit ADMINISTRATE.INSTALL permission for the application in which you want to install the cluster. If you only have permission for a specific technology, you will only be able to install in an application that is either empty, or is comprised of only the same technology.

  8. Select a Tier from the list.

  9. Click OK to open the J2EE Cluster Installation - Property Settings dialog box. See Defining J2EE cluster property settings.

    Always refresh AdminPoint after adding a cluster.

Defining J2EE cluster property settings

To enter J2EE property settings

  1. Use a free-text identifier to provide a unique name to be shared by all instances in the cluster. In addition, a unique identifier will automatically be added to each instance.

    For WebSphere and WebLogic, the unique name will be the application server name. For all other technologies, it will be a running number.

  2. Click the drop-down menu to select a server where any of the cluster’s JVMs are running. If you want to add a new server that is not listed, click Add. For more information, see About adding servers. You will have the chance to add more servers later on in the installation process.

    This is the name or IP address of the server where you want to install the J2EE Tier Collector. The server name appears in the list only if you previously defined it as a Precise Server.

  3. Select an auto-detected JVM from the “Detected JVMs” list. The remaining text boxes are auto-filled, but may be edited as needed.
  4. If none of the JVMs that you want to monitor are detected, proceed as follows:

    1. Click the drop-down menu to select the application server type.

      This is the type of the J2EE application server. Precise supports several J2EE application server types, including Oracle WebLogic, IBM WebSphere, Oracle AS, and Apache Tomcat.

    2. Click the drop-down menu to select the application server version.
    3. Enter the full path to the Java executable - optional field.

    4. If installing Oracle WebLogic managed instances, mark the “Managed WebLogic Server” check box.

      The last 2 items are optional, but are required to enable automatic execution of post-installation action items.

  5. Click Next. A preview of the planned installation will be displayed for approval at the beginning of the installation process.

About the AdminPoint cluster installation preview screen

The preview screen signifies that the AdminPoint cluster installer has gathered enough information to begin the installation phase.

The preview screen displays the following details before installation begins:

  • Server name or IP address
  • The Tier on which the cluster will be installed
  • What actions will be performed in their respective order
  • Required disk space
  • Currently available disk space

At this screen, you can still change any of the settings displayed. Click Back to change any of the displayed settings. Click Next to continue installation. Click Cancel to stop the installation process.

At this point, the cluster definitions are saved and an agent is only installed on the specified server. For servers that will be added after this point, the agent will be installed only once the JVM is started.

About the AdminPoint cluster installation progress screen

This screen appears when the AdminPoint Cluster Installer is actually performing installation. Installation may take several minutes.

The progress screen visually displays the progress of actual installation on selected servers.

About adding servers

The Add Servers screen enables you to add more servers running the cluster's JVMs to the cluster. To add servers, first locate them in the left table or add them by pressing the Add button. To associate a server with the cluster, move it to the table on the right. This action will allow you to check the status of the installation of the JVMs on the selected servers. You can also add the servers to the right list at a later time by editing the cluster. See Editing or removing tier instances or clusters. Click Next to continue installation.

About the AdminPoint Cluster Action Items screen

After a cluster is installed, you must perform post-installation tasks as required. Only after completing the post-installation tasks required can you start using the JVMs you have just installed.

Perform all tasks displayed on this screen. Click Copy All to copy the text of the action items to another location. Click Execute for Precise to perform the action items.

If you have two different clusters that are started by the same startup script, execute the action items manually by performing the procedure detailed in Manually executing post-installation action items when multiple clusters share a startup script.

About the AdminPoint Cluster Installation Complete screen

This screen appears when the AdminPoint Cluster Installer has completed installation of the cluster.

Click Finish (it will be the only option available) to complete the cluster installation. For cluster installation, every JVM that will start after all the action items have been applied, will automatically be installed and monitored in the Precise application.

Post-installation action items

After installing Precise agents for the J2EE Tier, post-installation action items must be executed. These action items vary according to the supported application, and can usually be executed automatically from the user interface. In some circumstances, however, these action items must be executed manually.

This section describes the automatic and manual post-installation action items for J2EE Tiers, and includes the following topics:

  • Automatically executing post-installation action items
  • Manually executing post-installation action items

Automatically executing post-installation action items

Most action items automatically appear as part of the installation process in the user interface.

To perform J2EE Tier post-installation tasks

  1. In the J2EE Tier - Installation dialog box, click Next.
  2. In the J2EE Tier - Post-Installation dialog box, follow the instructions to perform all post-installation action items.
  3. Click Finish.

Manually executing post-installation action items

This section describes the following manual procedures:

Manually enabling CPU capturing for IBM AIX version 5.x

If the application server is running on an IBM AIX version 5.x computer, and you want to enable Precise for J2EE to report CPU numbers for each method invocation, set and export the AIXTHREAD_ENRUSG parameter as follows:

AIXTHREAD_ENRUSG=ON

export AIXTHREAD_ENRUSG

Manually enabling Precise for J2EE monitoring

If the automatic execution of the post-installation action items failed, perform the following steps to enable monitoring for the installed instance or cluster:

Verify that the instance (JVM) or cluster name you enter is the same as the instance (JVM) or cluster name that you defined during installation.

  • For Java 1.5
    • Add the following arguments to the Java command line of the JVM to be monitored:
      • For an instance

        -javaagent:<precise_root>\products\j2ee\lib\indepthj2ee-agent.jar=com. precise.javaperf.javaagent.agents.DefaultJavaAgent
        -Dindepth.j2ee.server=<precise_root>\products\j2ee\config\<INSTANCE_NAME> -DisClustered=false

      • For a cluster
        -javaagent:<precise_root>\products\j2ee\lib\indepthj2ee-agent.jar=com. precise.javaperf.javaagent.agents.DefaultJavaAgent
        -Dindepth.j2ee.server=<precise_root>\products\j2ee\config\<CLUSTER_NAME> -DisClustered=true

        Be sure to use the <JAVA_HOME> that the application server uses, not the <JAVA_HOME> located in the Precise product installation folder. The apladmin program will attempt to prevent any use of a JVM located under <precise_root>.

      • For Java 1.4
        1. Configure instrumentation by executing the following command from the <precise_root> folder, replacing <JAVA_HOME> with the path to the Java home of the application to be monitored:
          • Windows. products\j2ee\bin\apladmin modrt --jvm-id=<instance (jvm)_name/cluster_name> "<JAVA_HOME>\bin\java.exe"
            For example:
            products\j2ee\bin\apladmin modrt --jvm-id=<instance (jvm)_name/cluster_name> "c:\j2sdk1.4.2_08\bin\java.exe"

          • UNIX. products/j2ee/bin/apladmin.sh modrt --jvm-id=<instance (jvm)_name/cluster_name> "<JAVA_HOME>/bin/java"
            For example:
            products/j2ee/bin/apladmin.sh modrt --jvm-id=<instance (jvm)_name/cluster_name> "/opt/j2sdk1.4.2_08/bin/java"

            Be sure to use the <JAVA_HOME> that the application server uses, not the <JAVA_HOME> located in the Precise product installation folder. The apladmin program will attempt to prevent any use of a JVM located under <precise_root>.

        2. Follow the instructions in the command output to modify the Java command line of the JVM to be monitored.
        3. Add the -DisClustered=false flag to the arguments from apladmin. For a clustered installation, specify 'true' for this flag.
        4. After executing the apladmin.modrt, add the parameters to the JVM startup command line.
          For example:
          -Xbootclasspath/p:C:\Precise\products\j2ee\etc\apl\jvms\java-vm-TestApp\lib\rt.jar
          -Xbootclasspath/p: C:\Precise\products\j2ee\lib\indepthj2eeboot.jar
          -Xbootclasspath/p: C:\Precise\products\j2ee\classes
          -Dindepth.j2ee.server= C:\Precise\products\j2ee\config\TestApp
          -DisClustered=false

Manually executing post-installation action items when multiple clusters share a startup script

If two different clusters are started by the same startup script, the automatic action items will not work properly. In this case, the user must edit the startup script manually and adjust it to the relevant cluster configuration.

To manually execute the action items

  1. Start the cluster with Precise instrumentation by adding the following parameters to the Java command:
    -javaagent:<precise_root>\products\j2ee\lib\indepthj2ee-agent.jar=com.precise.javaperf.javaagent.agents.DefaultJavaAgent
    -Dindepth.j2ee.server=<precise_root>\products\j2ee\config\<cluster_name>
    -DisClustered=true
  2. Repeat for each cluster started by the startup script.

Manually executing WebSphere post-installation action items in instance and cluster applications

By default, the user can automatically execute the post-installation action items for WebSphere application servers from the action items screen during installation. However, in some cases the automatic execution of the action items will not be possible or will fail. For example, if the WAS is secured, or the auto-detect phase failed (because the server was down, etc.), the automatic action items execution will fail. In such cases, the user will have to execute the action items manually.

To manually instrument a WebSphere instance/cluster

  1. Configure instrumentation by executing the following command from the <precise_root> folder, replacing <JAVA_HOME> with the path to the Java home of the application to be monitored.
    • Windows. products\j2ee\bin\apladmin modrt --jvm-id=<instance (jvm)_name/cluster_name> "<JAVA_HOME>\bin\java.exe"

    • UNIX. ./products/j2ee/bin/apladmin.sh modrt --jvm-id=<instance (jvm)_name/cluster_name> "<JAVA_HOME>\bin\java.exe"

      Be sure to use the <JAVA_HOME> that the application server uses, not the <JAVA_HOME> located in the Precise product installation folder.

  2. Follow the apladmin instructions.
  3. Add the -DisClustered=false flag to the arguments from apladmin. For a cluster, specify 'true' for this flag.

  4. To enable RMI transaction monitoring, add the following text:
    Dorg.omg.PortableInterceptor.ORBInitializerClass.com.precise.javaperf.lib.smartlink.PreciseSmartlinkORBInitializer For example, the user will add the following arguments to WAS java arguments:
    -Xbootclasspath/p:C:\Precise\products\j2ee\etc\apl\jvms\java-vm-TestApp\lib\rt.jar
    -Xbootclasspath/p: C:\Precise\products\j2ee\lib\indepthj2eeboot.jar
    -Xbootclasspath/p: C:\Precise\products\j2ee\classes
    -Dindepth.j2ee.server= C:\Precise\products\j2ee\config\TestApp
    -DisClustered=false

    Generally the <JAVA_HOME> for WebSphere installations can be found in the Application > WebSphere variables section in the WebSphere Administrative Console.

  5. Enable Application Server Metrics by performing the following steps:
    1. Verify that the Performance Monitoring Service is enabled by marking the "Enable Performance Monitoring Infrastructure (PMI)" setting located on the Application Servers > <SERVER_NAME> > Performance Monitoring Infrastructure (PMI) page.
    2. Verify that the initial specification level is "Basic" or "Custom."
    3. After Performance Monitoring Service is confirmed to be enabled at startup, perform the following steps to configure the Application Server Metrics collection:
      1. Select Servers > Application Servers > <SERVER_NAME> > Server Infrastructure > Administration > Custom Services.
      2. Click New.
      3. Mark the "Enable service at service startup" check box.
      4. Leave the External Configuration URL blank.
      5. Set the "Classname" to com.precise.javaperf.extensions.websphere.PreciseMetricPluginLoader
      6. Set the "Display Name" to PreciseMetricPluginLoader
      7. Set the "Classpath" to: <precise_root>/products/j2ee/lib/indepthmetric.jar
      8. Save the changes.
  6. Update the security policy.

    1. Edit the <WAS_INSTALL_ROOT>/profiles/<SERVER>/properties/server.policy file to include the following:
      grant codeBase "file:<precise_root>/-" {
      permission java.security.AllPermission;
      };

      In Windows, change the PATH separator from '\' to the UNIX style separator '/'.

  7. Restart the Application server.

    For clustered applications, the user must verify that the rt.jar generated in step 1, and pointed to by the Xbootclasspath, is located in all the servers that are running as part of the WebSphere cluster. The user can copy the rt.jar to any central location, and update the Xbootclasspath accordingly.


IDERA |  Products | Purchase | Support |  Community |  Resources |  About Us  | Legal