1. Installing and Configuring Oracle Application Performance Monitoring
  2. Install and Configure APM Java Agent On Oracle Weblogic Server

2 Install and Configure APM Java Agent On Oracle Weblogic Server

Topics:

On Linux: Requirements and Installation Instructions

Prerequisites for Deploying APM Java Agent on an Oracle WebLogic Server

  • Supported versions of Oracle WebLogic Server:

    • Oracle WebLogic Server 12.1.3

    • Oracle WebLogic Server 12.2.1

    • Oracle WebLogic Server 10.3.6, also known as Oracle WebLogic Server 11g Release 1

    Note:

    In the host running Oracle WebLogic Server, you can run the following command from $WLS_HOME/server/lib to check the Oracle WebLogic Server version: 

    java -cp weblogic.jar weblogic.version

  • 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 Oracle WebLogic 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 Oracle WebLogic Server user.

  • The Oracle WebLogic Server user should have read and write permissions to the directories that host the APM Java Agent.

Licensing considerations:

  • If you are installing Application Performance Monitoring on the WebLogic Administration Server, then it will also be automatically installed on all the managed servers. One APM Agent will run on each of your managed servers, and this should be considered while calculating the total licensing cost.

  • If you prefer to run the APM Agent on one or a few selected managed servers only, then install Application Performance Monitoring on only those managed servers.

Set the DOMAIN_HOME Variable

Set the DOMAIN_HOME variable to point to the Oracle WebLogic Server domain.

Example:

export DOMAIN_HOME=<WebLogic Server Domain>

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 the gateway's host and port.

export GW_HOST=<Gateway Host Name>
export 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 Weblogic

  1. From the main Oracle Management Cloud menu, navigate to Administration and Agents.

  2. 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.

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

  4. Click APM Java Agent.

  5. Extract the contents of the installer ZIP file.

  6. 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.

  • 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 created in the extraction.

Install and Provision the APM Java Agent on Linux

  1. Navigate to the directory where you downloaded or copied 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 ${DOMAIN_HOME} -no-wallet
    Silent Installation 
    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} -no-prompt -regkey-file <file name> -no-wallet

    With Gateway

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

    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} -no-wallet -gateway-host {gw_host_value} -gateway-port {gw_port_value} 
-additional-gateways https://<gw_host_2>:<gw_port_2>,https://<gw_host_3>:<gw_port_3>
    In a proxy environment 
    chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${DOMAIN_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 the Oracle WebLogic Server domain. 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 a 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. Enable the APM Java Agent. This enables the APM Agent to be invoked when you restart the Oracle WebLogic Server.

    1. Make a backup copy of your startWebLogic.sh file: 

      cd $DOMAIN_HOME/bin
cp startWebLogic.sh startWebLogic.sh.orig
    2. Edit the startWebLogic.sh script.
      1. If you are installing the APM Java Agent on the WebLogic Administration Server as well as all the Managed Servers:

        Using a text editor, edit the startWebLogic.sh file and add the -javaagent option to the set of JAVA_OPTIONS. Add the following line after the setDomainEnv.sh call: 

        JAVA_OPTIONS=$JAVA_OPTIONS -javaagent:$DOMAIN_HOME/apmagent/lib/system/ApmAgentInstrumentation.jar
      2. If you are installing the APM Java Agent on the Managed Servers only:

        Using a text editor, edit the startWebLogic.sh file and add the -javaagent option to the set of JAVA_OPTIONS within an IF statement similar to that below. Add the following line after the setDomainEnv.sh call: 

        if [ "$SERVER_NAME" != "AdminServer" ] ; then
        set JAVA_OPTIONS=$JAVA_OPTIONS -javaagent:$DOMAIN_HOME/apmagent/lib/system/ApmAgentInstrumentation.jar
fi

        Here, AdminServer is the name of your Administration Server. Use the exact name with the same space and indentation as above.

  5. Restart your Oracle WebLogic application server:

    % cd $DOMAIN_HOME/bin
% stopWebLogic.sh
% cd ..
% startWebLogic.sh > startup.log

    Note:

    Notice that the $DESTINATION version of startWebLogic.sh is used, even though you edited the $DESTINATION/bin version. Invoking the command from one level higher (from $DESTINATION) invokes the command from a lower level (from $DESTINATION/bin). However, the stopWebLogic.sh command will be called from the $DESTINATION/bin directory.

  6. If you have any managed Oracle WebLogic application servers, restart them:

    $ cd $DOMAIN_HOME/bin
$ stopManagedWebLogic.sh {SERVER_NAME} {ADMIN_URL} {USER_NAME} {PASSWORD}
$ startManagedWebLogic.sh {SERVER_NAME} {ADMIN_URL} > {SERVER_NAME}.log

    Run the provisioning script as per your installation preference.

Provision APM Java Agent with a standalone installer

A standalone APM Agent installer is obtained when the Agent zip file is received via email, FTP or similar means (that is, when the agent zip file was not downloaded from an OMC server). To install using the standalone agent installer specify these additional parameters when running the provisioning script:

Option Description
-tenant-id The Oracle Management Cloud tenant name. You can get this value from the Agent Download page.
  • Script for v1 tenant — 
    sh ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} 
-tenant-id <tenant> -omc-server-url <omc server url>
  • Script for v4 tenant — 
    sh ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} 
-tenant-id <service-tenant> -omc-server-url <omc server url>
-omc-server-url The URL of the Oracle Management Cloud server.

If you are using gateways and have specified -gateway-host and -gateway-port, you do not have to specify the value for omc-server-url.
Provisioning script to run the standalone installer:
Installation Preference Provisioning Script
Basic Installation 
sh ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} 
-tenant-id <tenant> -omc-server-url <omc server url> –no-wallet
With Gateway

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

sh ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} -tenant-id <tenant> -no-wallet -gateway-host  -gateway-port
-additional-gateways https://<gw_host_1>:<gw_port_1>,https://<gw_host_2>:<gw_port_2>
With Gateway and additional Gateways 
sh ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} -tenant-id <tenant> -no-wallet -gateway-host -gateway-port -additional-gateways
In a proxy environment 
sh ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME}  -tenant-id <tenant> -no-wallet -gateway-host -gateway-port -ph {http_proxy_host} -pp {http_proxy_port}

Generate a Proxy Token

The APM Java Agent can generate a token for HTTP Basic authentication using a username and password instead of a token that is user-generated. Once the user provides a user name and password as property file entries, the APM Java Agent will automatically generate a HTTP Basic authentication token. To get HTTP Basic authentication token generated by the APM Java Agent:
  1. In the <agent>/config/AgentHttpBasic.properties file, specify the following properties:
    oracle.apmaas.agent.http.proxy.basic.username = myHttpBasicProxyUser
oracle.apmaas.agent.http.proxy.basic.password = myHttpBasicProxyPass

    Note:

    If along with the above properties, an authentication is also specified with the property oracle.apmaas.agent.http.proxy.token, it will take precedence over the username and password properties.
    APM Java Agent uses the user name and password to generate a HTTP Basic authentication token, and authenticate the user.

Set the NTLM Workstation

Administrators can set the Microsoft Windows NT LAN Manager (NTLM) workstation in case your proxy has this requirement. To set the NTLM workstation:
  • Add the following property to the AgentStartup properties file:

    oracle.apmaas.agent.transport.proxy.ntlm.workstation

Configure NTLM Proxy Authentication in the APM Java Agent

You can configure NTLM proxy authentication in the APM Java Agent to support NTLM authentication.

To configure NTLM proxy authentication:
  1. In the <agent>/config/AgentHttpBasic.properties file, specify the oracle.apmaas.agent.http.proxy.token property with a value in this format:
    domain/username:password

    Example: oracle.apmaas.agent.http.proxy.token = testdomain/user1:hello

On Windows: Requirements and Installation Instructions

Prerequisites for Deploying APM Java Agent on an Oracle WebLogic Server

  • Supported versions of Oracle WebLogic Server:

    • Oracle WebLogic Server 12.1.3

    • Oracle WebLogic Server 12.2.1

    • Oracle WebLogic Server 10.3.6, also known as Oracle WebLogic Server 11g Release 1

    Note:

    In the host running Oracle WebLogic Server, you can run the following command from %WLS_HOME%/server/lib to check the Oracle WebLogic Server version: 

    java -cp weblogic.jar weblogic.version

  • JDK version 1.7 or above. If you are using JDK 1.6, either use a JDK 1.6 that supports TLS 1.2, 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 Oracle WebLogic 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 Oracle WebLogic Server user.

  • The Oracle WebLogic Server user should have read and write permissions to the directories that host the APM Java Agent.

Licensing considerations:

  • If you are installing Application Performance Monitoring on the WebLogic Administration Server, then it will also be automatically installed on all the managed servers. One APM Agent will run on each of your managed servers, and this should be considered while calculating the total licensing cost.

  • If you prefer to run the APM Agent on one or a few selected managed servers only, then install Application Performance Monitoring on only those managed servers.

Downloading the APM Java Agent Software for Weblogic

  1. From the main Oracle Management Cloud menu, navigate to Administration and Agents.

  2. 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.

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

  4. Click APM Java Agent.

  5. Extract the contents of the installer ZIP file.

  6. 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.

Installing and Provisioning the APM Java Agent for Windows

  1. Navigate to the directory where you downloaded or copied the APM Java Agent software.

  2. Run the provisioning script as per your installation preference:

    Installation Preference Provisioning Script
    Basic Installation 
    set DOMAIN_HOME=<path to domain home>
ProvisionApmJavaAsAgent.cmd /d %DOMAIN_HOME% /no-wallet
    Silent Installation 
    set DOMAIN_HOME=<path to domain home>
ProvisionApmJavaAsAgent.cmd /d %DOMAIN_HOME% /no-prompt /regkey-file <file name> /no-wallet

    With Gateway

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

    set DOMAIN_HOME=<path to domain home>
ProvisionApmJavaAsAgent.cmd /d %DOMAIN_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 
    set DOMAIN_HOME=<path to domain home>
ProvisionApmJavaAsAgent.cmd /d %DOMAIN_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 the Oracle WebLogic Server domain. 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.

    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.cmd -d mydir -no-prompt < regkey.txt, where regkey.txt contains a single line with the registration key.

  4. Enable the APM Java Agent. This enables the APM Agent to be invoked when you restart the Oracle WebLogic Server.

    1. Make a backup copy of your startWebLogic.cmd file: 

      cd %DOMAIN_HOME%\bin
copy startWebLogic.cmd startWebLogic.cmd.orig
    2. Edit the startWebLogic.cmd script.
      1. If you are installing the APM Java Agent on the WebLogic Administration Server as well as all the Managed Servers:

        Using a text editor, edit the startWebLogic.cmd file and add the -javaagent option to the set of JAVA_OPTIONS. Add the following line after the setDomainEnv.cmd call: 

        set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:%DOMAIN_HOME%\apmagent\lib\system\ApmAgentInstrumentation.jar
      2. If you are installing the APM Java Agent on the Managed Servers only:

        Using a text editor, edit the startWebLogic.cmd file and add the -javaagent option to the set of JAVA_OPTIONS within an IF statement similar to that below. Add the following line after the setDomainEnv.cmd call: 

        if NOT "%SERVER_NAME%"=="AdminServer" (
        set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:%DOMAIN_HOME%\apmagent\lib\system\ApmAgentInstrumentation.jar
)

        Here, AdminServer is the name of your Administration Server. Use the exact name with the same space and indentation as above.

  5. Restart your Oracle WebLogic application server:

            % cd %DOMAIN_HOME%\bin
        % stopWebLogic.cmd
        % cd ..
        % startWebLogic.cmd > startup.log

    Note:

    Notice that the %DESTINATION% version of startWebLogic.cmd is used, even though you edited the %DESTINATION%/bin version. Invoking the command from one level higher (from %DESTINATION%) invokes the command from a lower level (from %DESTINATION%/bin). However, the stopWebLogic.cmd command will be called from the %DESTINATION%/bin directory.

  6. If you have any managed Oracle WebLogic application servers, restart them:

    % cd %DOMAIN_HOME%\bin
        % stopManagedWebLogic.cmd {SERVER_NAME} {ADMIN_URL} {USER_NAME} {PASSWORD}
        % startManagedWebLogic.cmd {SERVER_NAME} {ADMIN_URL} > {SERVER_NAME}.log

Note:

If you are running Oracle WebLogic Server as a Microsoft Windows service, add the -javaagent flag to the JAVA_OPTIONS of your custom registration script, and register your WebLogic Windows service again.

Generating a Proxy Token

The APM Java Agent can generate a token for HTTP Basic authentication using a username and password instead of a token that is user-generated.

Once the user provides a user name and password as property file entries, the APM Java Agent will automatically generate a HTTP Basic authentication token. To get HTTP Basic authentication token generated by the APM Java Agent:

  1. In the <agent>/config/AgentHttpBasic.properties file, specify the following properties: 

    oracle.apmaas.agent.http.proxy.basic.username = myHttpBasicProxyUser
oracle.apmaas.agent.http.proxy.basic.password = myHttpBasicProxyPass

    Note:

    If along with the above properties, an authentication is also specified with the property oracle.apmaas.agent.http.proxy.token, it will take precedence over the username and password properties.

Setting the NTLM Workstation

Administrators can set the Microsoft Windows NT LAN Manager (NTLM) workstation in case your proxy has this requirement. To set the NTLM workstation:
  • Add the following property to the AgentStartup properties file:

    oracle.apmaas.agent.transport.proxy.ntlm.workstation

Configuring NTLM Proxy Authentication in the APM Java Agent

You can configure NTLM proxy authentication in the APM Java Agent to support NTLM authentication.

To configure NTLM proxy authentication:
  1. In the AgentHttpBasic.properties file, specify the oracle.apmaas.agent.http.proxy.token property with a value in this format:
    domain/username:password

    Example: oracle.apmaas.agent.http.proxy.token = testdomain/user1:hello

APM Java Agent Custom Installations

  1. Install on Managed Servers through the Administration Console
  2. Install when the target server is launched with a custom script

Install on Managed Servers through the Administration Console

If nodemanager.properties does not contain StartScriptName=startWebLogic.cmd , StartScriptName=startWebLogic.sh, or a similar startup script, you will need to add the -javaagent flag for managed servers through the WebLogic Server Administration Console.

  1. On the WLS Admin Console, navigate to the configuration page for the target managed server. (Environment, Servers and <server name>).
  2. Click on the Server Start tab. Add the -javaagent flag to the Arguments text box. If the Arguments text box is greyed out, click the Lock & Edit button typically in the upper left of the WebLogic Server Administration Console.

    Example: -javaagent:<full_path>/apmagent/lib/system/ApmAgentInstrumentation.jar.

  3. Click Save .
  4. If the domain configuration is still locked, click the Release Configuration button typically located directly beneath the Lock & Edit button.
  5. Restart the managed server

Install when the target server is launched with a custom script

When installing the APM Java agent on a server launched with a custom startup script, add the -javaagent flag to the command that launches the application you want to monitor.

The custom script usually contains a Java executable, a number of Java options, and then either a Main Class (for example, java $JAVA_OPTIONS Bootstrap) or a jar containing the Main Class (for example, java $JAVA_OPTIONS -jar Bootstrap.jar).

Add the -javaagent flag after the java executable and before the main class jar. Ensure that the -javaagent flag is added as its own standalone flag, and not as part of some other flag's argument. For example, don't add the -javaagent flag directly after a standalone -classpath option, but add after a -classpath <value> combination.

Example: 
java -classpath $CLASSPATH -javagent:<path_to_agent> -jar Bootstrap.jar
To verify if the javaagent was successfully added to the application's custom start script, check the command line arguments of the target Java process once it is running.
  • On Linux: 
    ps -ef | grep java
    This will list all the Java processes, and you can confirm whether the desired server process has a proper -javaagent:<path_to_agent> option
  • On Windows:
    1. In the Task Manager, Processes tab, select the desired Java process.
    2. Right click the process and view the Details tab and check for the commandLine section.
    3. Check the CommandLine section, and confirm if the desired java process has a proper -javaagent:<path_to_agent> option.