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

Follow the steps given below to install Java agent in WildFly servers v8.x & above:

  1. Download the latest APM Insight Java agent (apminsight-javaagent.zip) file.
  2. Extract the zip file to a new directory to find agent jar and its configuration files.
  3. Open the apminsight.conf file in any text editor and include/modify the following keys:

    license.key=[LICENSE KEY]
    apm.host=http://[HOST]:[PORT]
    application.name=[APPLICATION NAME]

    where

    • [LICENSE KEY] - License key obtained from Applications Manager under APM Insight tab.
    • [HOST] - Host at which Applications Manager is running.
    • [PORT] - Port number at which Applications Manager is running.
    • [APPLICATION NAME] - Name of your application.

    Example:

    license.key=APMI_74447444b666d7ab5174cc3021a9b68dd4b3364d50f99c2969360810313e8fac
    apm.host=http://apm-prod-server:9090
    application.name=Wildfly_Server

    To learn more about the configurations, visit our Configuration Guide page.
Note:
  • You can also configure a secure APM URL. Ensure that the connection is stable and free from certificate-related issues.
    Example: https://apm-prod-server:8443
  • For an Applications Manager failover setup, you can specify multiple hosts in a comma-separated format (supported from Java Agent v6.8), as shown below:
    apm.host=http://apm-prod-server-A:9090, http://apm-prod-server-B:9090

Using Applications Manager's Wildfly monitoring software, agent can be configured based on the following installation types:

Standalone agent installation

Windows based installation

For standalone agent setup in Windows, follow the steps given below:
  1. Open the standalone.bat file under <WILDFLY_HOME>/bin/ directory in any text editor.
  2. Copy the following JAVA_OPTSargument:

    set JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine -javaagent:<Agent_directory_full_path>\apminsightjavaagent.jar

    where <Agent_directory_full_path> refers to the directory where the java agent is extracted.

  3. Now paste the copied JAVA_OPTS argument (in bold text) above the mentioned section in the standalone.batfile as below:

    set JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine -javaagent:<Agent_directory_full_path>\apminsight-javaagent.jar
    echo ==============================================================================
    echo.
    echo JBoss Bootstrap Environment
    echo.
    echo JBOSS_HOME: "%JBOSS_HOME%"
    echo.
    echo JAVA: "%JAVA%"
    echo. echo JAVA_OPTS: "%JAVA_OPTS%"
    echo.
    echo ==============================================================================
    echo.

  4. Finally, restart the Applications Manager.

After adding Java agent and performing a restart of Jboss server, if there are any Logger / Log Manager exceptions in logs, proceed to do the following step:

For JDK 8 & below: Modify the JAVA_OPTS argument set previously in Step 1 as below:

set JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine,org.jboss.logmanager -javaagent: <Agent_directory_full_path>\apminsight-javaagent.jar -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/<path_to_jbosslogmanager_jar>/jboss-logmanager-<version>.jar

For JDK 9 & above: Modify the JAVA_OPTS argument set previously in Step 1 as below:

set JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine,org.jboss.logmanager -javaagent: <Agent_directory_full_path>\apminsight-javaagent.jar -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/<path_to_jbosslogmanager_jar>/jboss-logmanager-<version>.jar

Note: Make sure to modify the JAR filename and path in <JBOSS_HOME>/<path_to_jboss-logmanager_jar>/jboss-logmanager-<version>.jar to the correct jboss-logmanager JAR as the name and path differ with different versions of JBoss. Learn more

Linux based installation

For standalone agent setup in Linux, follow the steps given below:
  1. Open the standalone.sh file under <WILDFLY_HOME>/bin/ directory in any text editor.
  2. Copy the following JAVA_OPTSargument:

    JAVA_OPTS=$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine -javaagent:<Agent_directory_full_path>\apminsightjavaagent.jar

    where <Agent_directory_full_path> refers to the directory where the java agent is extracted.

  3. Now paste the copied JAVA_OPTS argument (in bold text) above the mentioned section in the standalone.shfile as below:

    JAVA_OPTS=$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine -javaagent:<Agent_directory_full_path>\apminsight-javaagent.jar
    echo "=============================================================================="
    echo ""
    echo "JBoss Bootstrap Environment"
    echo ""
    echo "JBOSS_HOME: %JBOSS_HOME%"
    echo ""
    echo "JAVA: %JAVA%"
    echo "" echo "JAVA_OPTS: %JAVA_OPTS%"
    echo ""
    echo "=============================================================================="
    echo ""

  4. Finally, restart the Applications Manager.

After adding Java agent and performing a restart of Jboss server, if there are any Logger/Log Manager exceptions in logs, perform the following step:

For JDK 8 & below: Modify the JAVA_OPTS argument set previously in Step 1 as below:

JAVA_OPTS=$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine,org.jboss.logmanager -javaagent: <Agent_directory_full_path>\apminsight-javaagent.jar -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/<path_to_jbosslogmanager_jar>/jboss-logmanager-<version>.jar

For JDK 9 & above: Modify the JAVA_OPTS argument set previously in Step 1 as below:

JAVA_OPTS=$JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.manageengine,org.jboss.logmanager -javaagent: <Agent_directory_full_path>\apminsight-javaagent.jar -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:<JBOSS_HOME>/<path_to_jbosslogmanager_jar>/jboss-logmanager-<version>.jar

Note: Make sure to modify the JAR filename and path in <JBOSS_HOME>/<path_to_jboss-logmanager_jar>/jboss-logmanager-<version>.jar to the correct jboss-logmanager JAR as the name and path differ with different versions of JBoss. Learn more

Domain Based Installation

For domain based installation, the installation may vary depends on the environment of the Wildfly Server through any of the following methods:

  • Global Configuration : Applying the configuration at the global level to manage all the connected hosts using the domain.xml configuration file.
  • Host-specific Configuration : Applying the configuration for an individual host using the host.xml configuration file.

Note: You can also add the configuration settings to both domain.xml and host.xml depending upon the global configuration and the host-specific configuration.

Global Configuration

Follow the steps given below to apply the configuration at a global level:
  1. Open the domain.xml file located under <WILDFLY_HOME>/domain/configuration/ directory in any text editor.
  2. Find the <server-group>element where you want to add your agent and add the following JVM properties (in bold text) inside the element:

    <server-groups>
    <server-group name="main-servergroup" profile="full">
    <jvm name="default">
    <heap size="64m" max-size="512m" />
    </jvm>
    <jvm name="insight">
    <jvm-options>
    <option value="-javaagent: <agent_directory_full_path>/apminsight-javaagent.jar" />
    </jvm-options>
    </jvm>
    <socket-binding-group ref="full-sockets" />
    </server-group> <server-group name="other-server-group" profile="fullha">
    <jvm name="default">
    <heap size="64m" max-size="512m" />
    </jvm>
    <socket-binding-group ref="full-ha-sockets" />
    </server-group>
    </server-groups>

  3. Find the <system-properties>element and add the following properties (in bold text) inside the element:

    <system-properties>
    <property name="java.net.preferIPv4Stack" value="true"/>
    <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,com.manageengine" boot-time="true"/>
    </system-properties>

  4. Save the file and start the Wildfly server.

Note: Changes in the domain.xml file require complete restart of both management host and the server host to take full effect.

Host-specific Configuration

Follow the steps given below to apply the configuration for an individual host:
  1. Open the host.xml file located under <WILDFLY_HOME>/domain/configuration/ directory in any text editor.
  2. Find the <servers>element where you want to add your agent and add the following JVM properties (in bold text) inside the element:

    <servers>
    <server name="server-one" group="main-server-group"/>
    <server name="server-two" group="main-servergroup" auto-start="true">
    <jvm name="default"/>
    <jvm name="insight">
    <jvm-options>
    <option value="-javaagent: <agent_directory_full_path>/apminsight-javaagent.jar" />
    </jvm-options>
    </jvm>
    <socket-bindings port-offset="150"/>
    </server>
    <server name="server-three" group="other-servergroup" auto-start="false">
    <jvm name="default"/>
    <socket-bindings port-offset="250"/>
    </server>
    </servers>

  3. Find the <system-properties>element and add the following properties (in bold text) inside the element:

    <system-properties>
    <property name="java.net.preferIPv4Stack" value="true"/>
    <property name="jboss.modules.system.pkgs" value="org.jboss.byteman,com.manageengine" boot-time="true"/>
    </system-properties>

  4. Save the file and start the Wildfly server.

Note: Changes in the host.xml file require complete restart of both management host and the server host to take full effect.