1. Installing and Configuring Oracle Application Performance Monitoring
  2. Install and Configure APM Java Agent on JBoss

5 Install and Configure APM Java Agent on JBoss

Here are the requirements and instructions to install APM Java Agent on JBoss.

JBoss: Requirements and Installation Instructions

Prerequisites for Deploying APM Java Agent on a JBoss Server

  • Supported versions:

    • JBoss EAP 6.1.1+

    • Wildfly 9.0.2

  • JDK version 1.7 or above. If you are using JDK 1.6, either use a JDK 1.6 that supports TLS 1.2 security protocol, or connect to OMC through a Gateway.

  • If the JDK version you are running doesn't support TLS 1.2 security protocol, refer to My Oracle Support Doc ID 2703411.1 before proceeding with the APM agent installation.

  • Other considerations:

    • The machine hosting the JBoss Server should be able to establish an HTTPS connection either directly or indirectly (using a proxy server or an Oracle Management Cloud gateway) to Oracle Management Cloud. For more information about Oracle Management Cloud gateway, see Install a Gateway.

    • The HTTPS connection must use TLS 1.2 security protocol.

    • The install user of APM Java Agent should be the same as the JBoss user.

    • The JBoss Server user should have read and write permissions to the directories that host the APM Java Agent, as well as the JBOSS Home.

Set the JBOSS_HOME Variable

Set the JBOSS_HOME variable to point to the JBoss home directory.

  • If you're using a Bash shell:

    export JBOSS_HOME=<JBoss home directory>

  • If you're using a C shell:

    setenv JBOSS_HOME "<JBoss home directory>"

Deploy a Gateway (Optional)

Gateway is not a mandatory component while deploying Oracle Application Performance Monitoring; you can use a gateway in the following scenarios:

  • If you have an application server that does not support Transport Layer Security (TLS) protocol 1.2

  • If you have older versions of Java Application Servers with JDK less than 1.7 (for example, Oracle WebLogic 10.3.6)

For instructions on how to deploy a gateway, see Install a Gateway.

Set the Gateway Variables (Optional)

Set the values for Gateway host and port.

  • If you're using a Bash shell:

    export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>

  • If you're using a C shell:

    setenv GW_HOST "<Gateway Host Name>"
setenv GW_PORT "<Gateway Port>"

If you are using more than one gateway, use the -additional-gateways option with the provisioning script.

Download the APM Java Agent Software for JBoss

  1. On the Oracle Management Cloud home page, click the Oracle Management Cloud Navigation icon on the top-left corner to view the Management Cloud navigation pane.

  2. Select Administration and Agents.

  3. On the Oracle Management Cloud Agents page, click the Action Menu on the top right corner of the page and select Download Agents.

    The Agent Software Download page is displayed.

  4. From the Agent Type dropdown list, select APM Agent.

  5. Click APM Java Agent.

  6. Extract the contents of the installer ZIP file.

  7. Create a registration key that will be used during the time of installing a new agent. Oracle Application Performance Monitoring Cloud Service verifies this key before accepting any data sent by APM Java Agent deployed on your on-premises hosts. For more information about creating a registration key, see Manage Registration Keys in Installing and Managing Oracle Management Cloud Agents.

Install and Provision APM Java Agent on JBoss

  • Before you install the APM Java Agent, log in to the machine running the application server as a user who installed the application server.

  • The application server user should have Read-Write access to the APM Java Agent directories.

To install and provision the APM Java Agent:
  1. Navigate to the directory where you downloaded the APM Java Agent software.
  2. Run the provisioning script as per your installation preference:
    Installation Preference Provisioning Script
    Basic Installation 
    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${JBOSS_HOME} -no-wallet
    Silent Installation 
    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${JBOSS_HOME} -no-prompt

    With Gateway

    If you are using more than one gateway, use the -additional-gateways option. 

    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${JBOSS_HOME} -no-wallet -gateway-host {gw_host_value}, -gateway-port {gw_port_value}, 
-additional-gateways https://<gw_host_1>:<gw_port_1>,https://<gw_host_2>:<gw_port_2>
    In a Proxy Environment 
    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${JBOSS_HOME} -no-wallet -ph {http_proxy_host} -pp {http_proxy_port} -pt {http_proxy_auth_token}

    • -d is the absolute path of the home directory of your JBoss installation. The APM Java Agent will be installed under this directory.

    • -ph {http_proxy_host} (Optional) — the proxy server’s host name.

    • -pp {http_proxy_port} (Optional) — the proxy server’s port.

    • -pt {http_proxy_auth_token}(Optional) — the authorization token that the agent will use if the proxy server requires authentication. This parameter will be passed literally as the proxy authorization header to the proxy server.

      If you are using HTTP Basic authentication, it is recommended that you omit this parameter. For details on HTTP Basic authentication, see Generate Proxy Token. You can also specify the proxy wallet entry or NTLM credentials token in the following format: domain/username:password. For example: exampledomain/sampleuser:welcome

    The command line displays your tenant name and the value you specified.
  3. When prompted, provide the value of the registration key that you've created or downloaded earlier.
    If you are running the provisioning script with the -no-prompt option, create a text file containing the value of registration key, and provide the path to the file.

    Example: ./ProvisionApmJavaAsAgent.sh -d mydir -no-prompt < regkey.txt where regkey.txt contains a single line with the registration key.

  4. Review the values and confirm. To change the values, enter n and run the script again with new values. 
  5. To proceed with the installation, enter y.
    The APM Java Agent is installed.
Provisioning APM Java Agent with Offline Installer

You can install and provision the APM Java Agent from an offline installer that you have received over email.

To install from the emailed ZIP, the provisioning script needs to download the configuration file from Oracle Management Cloud. Specify these additional options while running the provisioning script:

Option Description
-tenant-id The Oracle Management Cloud tenant name.
-omc-server-url The URL of the Oracle Management Cloud server. Example: https://omchost:port

Modify the Startup Script of Your JBoss Server

Modify the startup script of your application server to invoke Oracle Application Performance Monitoring, when you start your JBoss/WildFly server.

To modify the standalone.conf script of your JBoss/WildFly server:
  1. Make a copy of your standalone.conf file:
    % cd $JBOSS_HOME/bin
% cp standalone.conf standalone.conf.orig
  2. Move to the end of the standalone.conf file, and add the following Java option:
     JAVA_OPTS="$JAVA_OPTS
-Djboss.modules.system.pkgs=org.jboss.byteman,oracle.security.pki,oracle.apmaas.agent,oracle.apmaas.repackaged"
JAVA_OPTS="$JAVA_OPTS -javaagent:$JBOSS_HOME/apmagent/lib/system/ApmAgentInstrumentation.jar"
  3. Stop and restart the JBoss Server:
    % cd $JBOSS_HOME/bin                      
% ./jboss-cli.sh -c :shutdown                        
% nohup ./standalone.sh -b 0.0.0.0&> startup.log &

    You can check the entries present in the $JBOSS_HOME/startup.log file to verify that the JBoss Server has started.

  4. If you have any managed JBoss application servers, stop and restart them.

Install and Provision APM Java Agent on JBoss on Microsoft Windows

You can install and provision the APM Java Agent on your JBoss domain installed on a Microsoft Windows machine.

Before you install:

  • Log in to the machine running the application server, as the same user who installed the application server.

  • Ensure that the application server user has Read-Write access to the APM Java Agent directories.

To install and provision APM Java Agent on JBoss Server on Microsoft Windows:

  1. Run the following command to provision the APM Java Agent:

    set the DOMAIN HOME : set JBOSS_HOME=<JBoss_Home Path>
ProvisionApmJavaAsAgent.cmd /d %JBOSS_HOME% /no-wallet

  2. Provision the APM Java agent. This enables the APM Agent to be invoked when you restart the JBoss Server.

    1. Make a backup copy of your standalone.conf.bat file: 

      %cd %JBOSS_HOME%\bin
%cp standalone.conf.bat standalone.conf.bat.orig

  3. Edit the standalone.conf.bat file, add the following lines at the end of the file: 

     
set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,oracle.security.pki,oracle.apmaas.agent,oracle.apmaas.repackaged"
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:%JBOSS_HOME%\apmagent\lib\system\ApmAgentInstrumentation.jar"

  4. Stop and restart the JBoss Server:

    % cd <JBOSS_HOME>\bin                      
% ./standalone.conf.bat -b 0.0.0.0
    You can check the entries present in the <JBOSS_HOME>\startup.log file to verify that the JBoss Server has started.

  5. If you have any managed JBoss application servers, stop and restart them.

Verify APM Java Agent Installation

See Verify APM Java Agent Installation.