Installing the APM Insight Java Agent


APM Insight relies on the agent-based instrumentation technology for data aquisition and transmission.

Requirements : Application Server(s) running on Java 1.5 & above

Application Servers supported :

Glassfish 3.x & above Oracle Weblogic 10.3.x & above
IBM Websphere 7.x & above Resin 3.1.x & above
JBoss AS 4.x & above Tomcat 6.x & above
JBoss EAP 6.2.x & above WildFly 8.x & above
Jetty  

JDBC Drivers supported :

MySQL Sybase - jconn2, jconn3, jconn4
Postgres MS-SQL
IBM DB2 - db2jcc, jt400 Generic JDBC drivers
Oracle - ojdbc14, ojdbc5, ojdbc6  

Frameworks and Components supported :

Struts 1.x, 2.x Hibernate 3.x, 4.x
Spring IBatis
Servlets EJB
Filter JSP
Play 2.0 framework Portlets

Click on the links below to learn how to install the APM Insight Java Agent in different servers:

Uninstalling the Agent

  • Remove the arguments present in Java_Opts of the Applications server or from the UI of the Application (Based on how you deployed the agent)
  • Delete the complete APM Insight folder
  • Restart the Application server once.
Note: To restart the Java Agent, simply restart the Application Server in which the agent is installed. Restarting the Application Server will restart the Agent.

Deploying APM Insight Java Agent in Apache Tomcat 6.x & above:

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • For Tomcat as non-service installation,
    In Windows, Edit <TOMCAT_HOME>\bin\catalina.bat and add the following entry to the top and save the fileset JAVA_OPTS=%JAVA_OPTS% -javaagent:<agent_directory_full_path>/apminsight-javaagent.jarIn Linux, Edit <TOMCAT_HOME>/bin/catalina.sh and add the following entry to the top and save the fileexport JAVA_OPTS="$JAVA_OPTS -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar"
  • For Tomcat as service installation, Navigate to Configure Tomcat and to JAVA tab and add the entry -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar in Java Options box.
  • After adding the entry, click Apply and then OK.

Configure tomcat Apache Tomcat Properties

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Deploying APM Insight Java Agent in IBM WebSphere 7.x servers & above

  • Download the latest APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • Open administrative console of your IBM Websphere server, Select Servers >ServerType > WebSphere Application ServersAPM Insight Java Agent for Websphere
  • Select <Your Server Name> > Java and Process Management > Process DefinitionAPM Insight Java Agent for Websphere
  • Under Additional Properties, select Java Virutal Machine.
    APM Insight Java Agent for Websphere
  • Locate Generic JVM Argumnets textbox and enter the following parameter -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
    APM Insight Java Agent for Websphere
  • Save the settings and start the Websphere server.

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Deploying APM Insight Java Agent in JBoss AS 4.2.x & above

Note:
There is a bug in JBoss AS 7.2.x with a hindrance to deploy our APM Insight Java Agent in this server. We suggest to upgrade the JBoss server and try our APMInsight

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • For JBoss AS 4.x, 5.x, 6.x servers,
    • For Windows, open <JBOSS_HOME>\bin\run.bat in any text editor and add the following entry at the top and save itset JAVA_OPTS=-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar %JAVA_OPTS%
    • For Linux, open <JBOSS_HOME>/bin/run.sh in any text editor and add the following entry at the top and save itexport JAVA_OPTS="$JAVA_OPTS -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar"
  • For JBoss AS 7.x servers,
    • In standalone setup:Edit <JBOSS_HOME>/bin/standalone.bat(In Linux, standalone.sh) file to add the following java arguments to the existing JAVA_OPTS-Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
    • In domain setup:Edit <JBOSS_HOME>/domain/configuration/Host.xml file and locate <servers> tag and add the mentioned tags under your desired <server name="your_server" ...> tag.<system-properties>
      <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,com.manageengine" boottime="true"/>
      </system-properties>
      <jvm name="insight">
      <jvm-options>
      <option value="-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar" />
      </jvm-options>
      </jvm>
  • Save the file and start the JBoss Application Server

To know more about configuration go to the APM Insight Java Agent ConfigurationOptions page.

Installing Java Agent in JBoss EAP 6.2.x & above

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • For Standalone setup, Edit <JBOSS_HOME>/bin/standalone.bat(In Linux, standalone.sh) file to add the following java arguments to the existing JAVA_OPTS

-Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar

  • For Domain setup, Edit <JBOSS_HOME>/domain/configuration/Host.xml file and locate <servers> tag and add the mentioned tags under your desired<server name="your_server" ...> tag.
    <system-properties>
    <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,com.manageengine" boottime="true"/>
    </system-properties>
    <jvm name="insight">
    <jvm-options>
    <option value="-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar" />
    </jvm-options>
    </jvm>
  • Save the file and start the JBoss EAP server

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Installing Java Agent in JBoss EAP through Management Console

Open the management console through localhost:9990/console and login as “Management Realm” user.

  • Select Hosts Tab > Server Configurations > Server instance in which you like to install the agent > JVM Configuration TabAdmin Console
  • Click on Edit button to create a JVM Configuration for the server. In JVM options text box, add the following lines (each JVM option must be separated by a new line)
    -javaagent:AGENT_HOME/apminsight-javaagent.jar
  • Click on save button, you will see “Added/Modified JVM Config” message at top of the page. If the message doesn't appear, check your configuration carefully and save it again.
  • Now, select “System Properties” tab and Click “Add” button.
Admin Console
  • In the newly opened dialog box, fill in the following values

Name : jboss.modules.system.pkgs
Value : org.jboss.byteman,com.manageengine
Boot-Time : Check

  • And click “Save” button.
  • Finally, start/restart your configured server instance from “Runtime” tab at top left corner of the page.

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Deploying APM Insight Java Agent in Oracle Weblogic 10.3.x & above

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • If server start/stop is done using shell/bash script, please add the following content to startManagedWeblogic.sh (.bat) file:

    JAVA_OPTIONS="$JAVA_OPTIONS -DUseSunHttpHandler=true -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar"

  • Open the administrative console of Weblogic server, Select Environment > Servers > Configuration tab.
  • Select <Your Server Name> > Configuration > Server Start tab.
  • Locate Arguments textbox and enter the following argument:

    -DUseSunHttpHandler=true -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar

Admin Console

  • Save the settings and start the Weblogic server.

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Deploying APM Insight Java Agent in Glassfish 3.x & above

APM Insight Java Agent can be deployed in Glassfish Server through Admin Console as follows:

Example: -javaagent:D:/apminsight/apminsight-javaagent.jar

Admin Console

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • For standalone setup,
    • Extract the zip file to a new directory outside the glassfish server directory
    • Open the apminsight.conf file in any text editor and include the following keys:
      license.key=[LICENSE KEY]
      apm.host=https://[HOST]:[PORT]/

      Example:

      license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
      apm.host=http://app-w8-test:9007/
      To learn more about the configurations, visit our Configuration Guide page.
    • Open the administrative console of your glassfish server. Select Configurations and select the configuration used by the server
    • Select JVM Settings > Add JVM Option, then add the following parameter -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
    • Click Save button and start the glassfish server
  • For cluster setup,
    • Extract the zip file to a new directory outside the glassfish server directory
    • Copy the apminsight-javaagent.jar file from above directory to <GLASSFISH_HOME>\glassfish\domains\<domain>\lib\ext directory of the domain server
    • Create a new directory named "apminsight" under <GLASSFISH_HOME>\glassfish\nodes\<node>\<instance> in instance server and copy only theagent conf files from directory created in step 1 to this directory.
    • Open the apminsight.conf file in any text editor and include the following keys:
      license.key=[LICENSE KEY]
      apm.host=https://[HOST]:[PORT]/

      Example:

      license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
      apm.host=http://app-w8-test:9007/
      To learn more about the configurations, visit our Configuration Guide page.
    • Repeat the above two steps for every instance you like to add the java agent
    • Open the administrative console of your glassfish server. Select Configurations and select the configuration used by the cluster.
    • Select JVM Settings > Add JVM Option, then add the following parameters as such
      -javaagent:${com.sun.aas.instanceRoot}/lib/ext/apminsight-javaagent.jar-Dapminsight.home=${com.sun.aas.instanceRoot}/apminsight
  • Click Save button and start the glassfish cluster.

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Deploying APM Insight Java Agent in Resin 3.1.x servers & above

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • For Resin 3.x servers, Open <RESIN_HOME>/conf/resin.conf file in any text editor. Locate your <cluster> tag and the <server> tag of the server you need to monitor and add the following tag, <jvm-arg>-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar</jvm-arg>
  • For Resin 4.x servers, Open <RESIN_HOME>/conf/resin.xml file in any text editor. Locate your <cluster> tag and the <server> tag of the server you need to monitor and add the following tag, <jvm-arg>-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar</jvm-arg>
  • Save the file and start the Resin server.

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Deploying APM Insight Java Agent in WildFly 8.x servers & above

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • For Standalone setup, Edit <WILDFLY_HOME>/bin/standalone.conf.bat (In Linux, standalone.conf) fileto add the following java arguments to the existing JAVA_OPTS
    -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar
  • For Domain setup, Edit <WILDFLY_HOME>/domain/configuration/Host.xml file and locate <servers> tag and add the mentioned tags under your desired<server name="your_server" ...>tag
    <system-properties>
    <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,com.manageengine" boottime="true"/>
    </system-properties>
    <jvm name="insight">
    <jvm-options>
    <option value="-javaagent:<agent_directory_full_path>/apminsight-javaagent.jar" />
    </jvm-options>
    </jvm>
  • Save the file and start the Wildfly server

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

Deploying APM Insight Java Agent in Other Servers

  • Download latest the APM Insight java agent zip file (apminsight-javaagent.zip) here
  • Extract the zip file to a new directory to find agent jar and its configuration files
  • Open the apminsight.conf file in any text editor and include the following keys:
    license.key=[LICENSE KEY]
    apm.host=https://[HOST]:[PORT]/

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://app-w8-test:9007/
    To learn more about the configurations, visit our Configuration Guide page.
  • For Windows, open <your application server startup scipt>.bat using a text editor and add the following entry at the top of the startup scriptSET JAVA_OPTS=%JAVA_OPTS% -javaagent:"<agent_directory_full_path>/apminsight-javaagent.jar"
    Example: SET JAVA_OPTS=%JAVA_OPTS% -javaagent:"D:/apminsight/apminsight-javaagent.jar"
  • For Linux, open <your application server startup scipt>.sh using a text editor and add the following entry at the top of the startup script
  • export JAVA_OPTS="$JAVA_OPTS -javaagent:<agent_directory_full_path>/apminsight-javaagent.jar"
    Example: export JAVA_OPTS="$JAVA_OPTS -javaagent:/home/local/softwares/apminsight/apminsight-javaagent.jar"
  • Save the file and start the server

To know more about the configurations, go to the APM Insight Java Agent Configuration options page.

 Note:

  • For older versions of Java (v2.3 & below), data collection might not happen after upgrading Applications Manager to version 14440 & above. To enable, include the following keys in the apminsight.conf file after extracting the APM Insight Java agent zip (apminsight-javaagent.zip) file:
      license.key=[LICENSE KEY]
      apm.host=https://[HOST]:[PORT]/
    Example:
      license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
      apm.host=http://app-w8-test:9007/
  • After including the above keys, save the file and restart the application.

Troubleshooting:

For troubleshooting tips, go to our Support Portal.