Preparing Application Servers for Monitoring

By adding the Java Agent to your application server start up, your application server will be instrumented and monitored. This is done by adding the -javaagent:<agent installation directory>\lib\probeagent.jar option to your application server JVM parameters.

Note: If you installed the Java Agent for Tomcat, Jboss, WildFly, WebSphere, or WebLogic using the deployment program (for details, see Deployment), you do not need to perform this procedure. Restart the application server to pick up the changes.

For details on supported application servers, see System Requirements.

To continue, find your application server in the section below and follow the instructions for instrumenting and configuring.

Examples for Configuring Application Servers

This section provides examples of how to configure the following commonly used application servers for monitoring.

Note:  

  • When manually deploying the Java Agent for an application server, ensure that the agent has the relevant permissions so that the monitored application can access it.

  • Make sure that you understand the structure of the startup scripts, how the property values are set, and the use of environment variables before you make any application server configuration changes. Always create a backup copy of any file that you plan to update before making the changes.

  • We recommend that for Tomcat, JBoss, WildFly, WebSphere, and WebLogic you install and configure the Java Agent using the deployment program. For details, see Deployment.

  • Use quotes if there are spaces in the files paths that you specify.

GlassFish

The following are the instructions for a generic GlassFish 3.x or 4.x application server implementation. Your site administrator should be able to use these instructions to guide you in making the changes that are appropriate to your specific environment.

Note: GlassFish requires additional, special settings to work properly with the agent.

Locate the property org.osgi.framework.bootdelegation in the GlassFish configuration files and append the text ",com.mercury.opal.capture.proxy" to the end of the property value (do not include the quotes).

In GlassFish 3.1.2 and later, this property is located in <GlassFish_install_dir>/glassfish/config/osgi.properties.

In an earlier version of GlassFish, this property may reside in the following two files:

< GlassFish_install_dir >/osgi/equinox/configuration/config.ini

< GlassFish_install_dir >/osgi/felix/conf/config.properties

You may also need to disable the Monitoring Service on GlassFish to avoid a conflict with the Java Agent monitoring. Go to Configurations > {config_name} > Monitoring and uncheck the Enabled checkbox of the Monitoring Service option.

  1. Locate the GlassFish JVM configuration settings by logging in to the GlassFish Administration Console and navigating to the JVM Options page.

    For GlassFish 3.1.2 and later, in the left-hand tree go to Configurations > {config_name} > JVM Settings, where {config_name} is the name of your server configuration (such as, server-config).

    If you are working with an earlier version of GlassFish, click Application Server in the left-hand tree and then select the JVM Settings tab at the top.

    Then select the JVM Options tab. See the screenshot below as a reference.

  2. Using the Add JVM Option button, add the following JVM parameter. For <agent_install_dir> use the full path to where you installed the agent. On Windows, use forward slashes (/) instead of backward slashes (\).

    -javaagent:<agent_install_dir>/lib/probeagent.jar
  3. Restart the GlassFish application server.

    If the GlassFish application server does not start, you can check and change the JVM parameters in the <GlassFish_install_dir>/glassfish/domains/<domain_name>/config/domain.xml file to resolve the issue, where <domain_name> is the name of your domain (such as, domain1).

    See Verify that the Application Server is Running the Java Agent for more information.

JBoss or WildFly

The following sections provide instructions with specific examples for the JBoss and WildFly application servers for a generic implementation. Your site administrator should be able to use these instructions to /guide you to make these changes in your customized environment.

If you installed the Java Agent using the automatic deployment (for details, see Deployment), you do not need to perform this procedure. Restart the application server to pick up the changes.

Note: JBoss requires an additional, special setting to work properly with the agent.

  • For JBoss 6.x, add the following JVM parameter: -Djava.util.logging.manager=org.jboss.logmanager.LogManager

  • For JBoss 6.x EAP, 7.x and Wildfly 8.x, 9.x, add the following JVM parameter: -Djboss.modules.system.pkgs=org.jboss.byteman,com.mercury.opal

To configure a JBoss application server:

  1. Locate the startup script that is used to start JBoss for the application and locate a convenient point in the file after all options are set but before the java command line (or code block) that starts the application server is executed.

    • On JBoss versions earlier than 7.0:

      The startup script file is typically located in a path similar to the following:

      <JBOSS_HOME>\bin\run.[bat|sh]

      where <JBOSS_HOME> is the path to your JBoss installation directory, such as C:\jboss-6.1.0.Final.

    • On JBoss 7.0 or higher:

      The startup script file is typically located in a path similar to one of the following:

      <JBOSS_HOME>\bin\domain.[bat|sh]

      <JBOSS_HOME>\bin\standalone.[bat|sh]

      where <JBOSS_HOME> is the path to your JBoss installation directory, such as C:\jboss-as-7.1.0.Final.

  2. Insert additional configuration lines as illustrated by the examples. In the example you should replace <agent installation directory> with the value for your environment.

    Below is an example showing the modified .bat file for JBoss 6.x:

    echo ===============================================================================
    echo.
    echo   JBoss Bootstrap Environment
    rem Configuring AppPulse Trace Java Agent Start. Modified on Sun Apr 26 15:11:03 IDT 2015
    set AGENT_HOME="<agent installation directory>"
    set PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar
    rem The following option is for JBoss version 6 only
    set PROBE_OPTS=%PROBE_OPTS% " -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
    set JAVA_OPTS=%JAVA_OPTS% %PROBE_OPTS%
    rem Configuring AppPulse Trace Java Agent End
    echo.
    echo   JBOSS_HOME: "%JBOSS_HOME%"
    echo.
    echo   JAVA: "%JAVA%"
    echo.
    echo   JAVA_OPTS: "%JAVA_OPTS%"
    echo.
    echo ===============================================================================
    

    Below is an example showing the modified .sh file for JBoss 7.x or Wildfly 8.x, 9.x:

    echo ===============================================================================
    echo.
    echo   JBoss Bootstrap Environment
    rem Configuring AppPulse Trace Java Agent Start. Modified on Sun Apr 26 15:11:03 IDT 2015
    AGENT_HOME="<agent installation directory>"
    PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%/lib/probeagent.jar
    rem The following option is for JBoss version 7 only
    PROBE_OPTS=%PROBE_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.mercury.opal
    JAVA_OPTS=%JAVA_OPTS% %PROBE_OPTS%
    rem Configuring AppPulse Trace Java Agent End
    echo.
    echo   JBOSS_HOME: "%JBOSS_HOME%"
    echo.
    echo   JAVA: "%JAVA%"
    echo.
    echo   JAVA_OPTS: "%JAVA_OPTS%"
    echo.
    echo ===============================================================================
    echo.
    

    Note: If your java command line does not use the JAVA_OPTS variable to define the JVM parameters, you need to change the variable name JAVA_OPTS shown in these examples to the correct name.

  3. Save the changes to the startup script and restart the application server using the modified script.

  4. Verify the Connection

    Manually verify Java Agent connectivity with both the application server and the AppPulse Trace server. For details, see Verifying the Java Agent.

Jetty

The following section provides general instructions with specific examples for the Jetty application server for a generic implementation. Your site administrator should be able to use these instructions to show you how to make these changes in your customized environment.

To configure a Jetty server with a startup script:

  1. Locate the startup script used and open it for editing. By default, for a generic Jetty server installed on Linux the following startup script is used:

    <jetty home directory>/bin/jetty.sh
  2. Locate the following line:

    RUN_ARGS=(${JAVA_OPTIONS[@]} -jar "$JETTY_START" ${JETTY_ARGS[*]})

    and add the string -javaagent:<agent installation directory>/lib/probeagent.jar as follows:

    RUN_ARGS=(${JAVA_OPTIONS[@]} -javaagent:<agent installation directory>/lib/probeagent.jar -jar "$JETTY_START" ${JETTY_ARGS[*]})

  3. Save the changes to the startup script and restart the application server using the modified script.

  4. Verify the Connection

    Manually verify Java Agent connectivity with both the application server and the AppPulse Trace server. For details, see Verifying the Java Agent.

Below is an example showing the added lines in the output when running the modified startup script:

[root@my_host_machine bin]# ./jetty.sh start
Starting Jetty: 2016-02-25 10:59:36.091:INFO::main: Logging initialized @1386ms
2016-02-25 10:59:37.213:INFO::main: Redirecting stderr/stdout to /tmp/jetty-distribution-9.3.7.v20160115/logs/2016_02_25.stderrout.log
OK Thu Feb 25 10:59:38 IST 2016
[root@tmbweblogic bin]# ./jetty.sh stop
Stopping Jetty: OK
[root@tmbweblogic bin]# vi jetty.sh
[root@tmbweblogic bin]# ./jetty.sh start
Starting Jetty: 2016-02-25 11:02:55,336 INFO [com.mercury.opal.common.loader]: Loading modules.properties from: /opt/AppPulseJavaAgent/lib/modules.properties
2016-02-25 11:02:55,937 INFO [webserver]: AppPulse Trace Web Server listening on /0.0.0.0:35000 AppPulse Trace Java Agent '<agent name>', version: Development, pid: 2590
2016-02-25 11:02:59.111:INFO:oejs.Server:jetty-8.1.16.v20140903
2016-02-25 11:02:59.244:INFO:oejs.AbstractConnector:Started _SocketListener@0.0.0.0:35000
2016-02-25 11:03:00.881:INFO::main: Logging initialized @5737ms
2016-02-25 11:03:03.641:INFO::main: Redirecting stderr/stdout to /tmp/jetty-distribution-9.3.7.v20160115/logs/2016_02_25.stderrout.log
OK Thu Feb 25 11:03:07 IST 2016
[root@tmbweblogic bin]#

To configure a Jetty server without a startup script:

When starting Jetty from a command line in Windows or Linux, add ‑javaagent:<agent installation directory>\lib\probeagent.jar to the command as follows:

java -javaagent:<agent installation directory>\lib\probeagent.jar -jar start.jar

Below is an example showing the added lines in the output when running the modified command:

2016-02-25 10:52:13,985 INFO [com.mercury.opal.common.loader]: Loading modules.properties from: C:\ApplicationServers\tomcats\apache-tomcat-7.0.34\AppPulseJavaAgent\lib\modules.properties
2016-02-25 10:52:15,644 INFO [webserver]: AppPulse Trace Web Server listening on /0.0.0.0:35000
AppPulse Trace Web Server listening on /0.0.0.0:35000 AppPulse Trace Java Agent '<agent name>', version: 1.30.65, pid: 79024
2016-02-25 10:52:16.685:INFO:oejs.Server:jetty-8.1.16.v20140903
2016-02-25 10:52:16.734:INFO:oejs.AbstractConnector:Started _SocketListener@0.0.0.0:35000
2016-02-25 10:52:17.382:INFO::main: Logging initialized @3529ms
2016-02-25 10:52:17.804:INFO:oejs.Server:main: jetty-9.3.7.v20160115
2016-02-25 10:52:17.835:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///C:/ApplicationServers/jetties/jetty-distribution-9.3.7.v20160115/webapps/] at interval 1
2016-02-25 10:52:17.851:INFO:oejs.ServerConnector:main: Started ServerConnector@71cb0be4{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2016-02-25 10:52:17.851:INFO:oejs.Server:main: Started @3997ms

TIBCO ActiveMatrix BusinessWorks and Service Bus

The following sections describe the steps to configure TIBCO ActiveMatrix BusinessWorks and Service Bus so that the applications can be monitored.

To configure TIBCO ActiveMatrix BusinessWorks:

Configuring a TIBCO BusinessWorks application server involves modifying its configuration files to add JVM parameters. Below are the instructions for a generic server implementation. Your site administrator should be able to use these instructions to guide you in making the changes that are appropritate to your specific environment.

  1. Locate the TIBCO BusinessWorks .tra configuration files. These files are typically located in:

    <tibco_home>\tra\domain\<Domain_Name>\application\<Application_Name>\<Application_Name>.tra

  2. Insert additional configuration lines as illustrated by this example. In the example you should replace <agent_install_dir> with the value for your environment.

    #
    # Other arguments to application, JVM etc.
    #
    tibco.env.APP_ARGS=
    tibco.env.HEAP_SIZE=256M
    
    # Configuring AppPulse Trace Java Agent
    tibco.env.AGENT_HOME=<agent_install_dir>
    JmxEnabled=true
    tibco.env.PROBE_OPTIONS=%PROBE_OPTIONS% -javaagent:%AGENT_HOME%/lib/probeagent.jar
    java.extended.properties=%PROBE_OPTIONS%

    Note: If java.extended.properties already exists in the file, be sure to append the %PROBE_OPTIONS% to the existing definition. Also do not use backslashes (\) for any values. Instead replace them with forward slashes (/).

  3. Save the changes to the startup script and restart the application using the modified script.

    See Verify that the Application Server is Running the Java Agent for more information.

To configure TIBCO ActiveMatrix Service Bus:

Note: TIBCO ActiveMatrix Service Bus (AMSB) 3.1.2 requires additional, special settings to work properly with the agent.

Locate the TIBCO ActiveMatrix Service Bus 3.1.2 machine.xmi file. This file is typically located in a path such as:

<tibco_amx_configuration_dir>\data\tibcohost\<EnterpriseName_ServerName>\tools\machinemodel\machine.xmi

Update the runtimes section of the file for each node you want to monitor. For example:

<runtimes xsi:type="machinemodel:OSGiRuntime" name="Node1"

In the runtimes section for each node locate the frameworkProperties key org.osgi.framework.bootdelegation and append com.mercury.* to the value of the property.

For example:

<frameworkProperties key="org.osgi.framework.bootdelegation" value="com.ibm.*, ....,sun.*,com.mercury.*"/>

  1. Locate the TIBCO ActiveMatrix Service Bus .tra configuration files.

    On TIBCO ActiveMatrix Service Bus (AMSB) 2.0 and 2.3 these files are typically located in:

    <tibco_home>\amx\data\<Node>\<Application\bin

    On TIBCO ActiveMatrix Service Bus 3.1.2 these files are typically located in:

    <tibco_amx_configuration_dir>\tibcohost\<EnterpriseName_ServerName>\nodes\<NodeName>\bin\tibamx_<NodeName>.tra

  2. Insert additional configuration lines as illustrated by this example. In the example you should replace <agent_install_dir> with the value for your environment.

    # NOTE:
    # There must be only one java.extended.properties in the .tra file. Append remote
    # debugging extended properties here to use remote debugging for this process.
    #
    # Configuring AppPulse Trace Java Agent
    tibco.env.AGENT_HOME=<agent_install_dir>
    tibco.env.PROBE_OPTIONS=%PROBE_OPTIONS% -javaagent:%AGENT_HOME%/lib/probeagent.jar
    java.extended.properties=%PROBE_OPTIONS%

    Note: If java.extended.properties already exists in the file, be sure to append the %PROBE_OPTIONS% to the existing definition. Also do not use backslashes (\) for any values. Instead replace them with forward slashes (/).

  3. Save the changes to the startup script and restart the application using the modified script.

    See Verify that the Application Server is Running the Java Agent for more information.

Tomcat

Apache Tomcat is frequently embedded into other applications or servers. As a result, the way to instrument it may vary. The following sections provide instructions on how to configure a Tomcat server in simple scenarios, but it is generic enough to guide you in your particular situation.

If you installed the Java Agent using the automatic deployment (for details, see Deployment), you do not need to perform this procedure. Restart the application server to pick up the changes.

If your Tomcat server is started by a script, follow the instructions in To configure a Tomcat server with a startup script:.

If Tomcat is installed as a Windows service or has no scripts, follow the instructions in To configure a Tomcat server without a startup script:.

To configure a Tomcat server with a startup script:

  1. Locate the startup script that is used to start Tomcat for the application and locate a convenient point in the file after all options are set but before the java command line (or code block) that starts the application server is executed.

    In some scenarios, the startup script will end up calling the following script to start Tomcat:

    <Tomcat_install_dir>/bin/catalina.[bat|sh]

    where <Tomcat_install_dir> is the path to your Tomcat installation directory, such as C:\apache-tomcat-7.0.8.

  2. Insert additional configuration lines as illustrated by the example below. Replace <agent installation directory> with the value for your environment.

    The following is an example showing a modified catalina.bat file:

    :doStart
    
    rem Configuring AppPulse Trace Java Agent Start. Modified on Tue Apr 21 15:46:05 IDT 2015
    set AGENT_HOME="<agent installation directory>"
    set PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar
    set CATALINA_OPTS=%CATALINA_OPTS% %PROBE_OPTS%
    rem Configuring  AppPulse Trace Java Agent End
    
  3. Save the changes to the startup script and restart the application server using the modified script.

  4. Verify the Connection

    Manually verify Java Agent connectivity with both the application server and the AppPulse Trace server. For details, see Verifying the Java Agent.

To configure a Tomcat server without a startup script:

  1. Run the <Tomcat HOME>/bin/tomcat7w.exe command.
  2. Select Java tab > Java Options).
  1. In the Java Options box, add the following JVM parameter, replacing <agent installation directory> with the value for your environment.

    -javaagent:<agent installation directory>\lib\probeagent.jar
  2. Restart the Tomcat service.

  3. Verify the Connection

    Manually verify Java Agent connectivity with both the application server and the AppPulse Trace server. For details, see Verifying the Java Agent.

WebLogic

The following section provides general instructions with specific examples for the WebLogic application server for a generic implementation. Your site administrator should be able to use these instructions to show you how to make these changes in your customized environment.

If you installed the Java Agent using the automatic deployment (for details, see Deployment), you do not need to perform this procedure. Restart the application server to pick up the changes.

To configure a WebLogic application server:

  1. Edit the startup script used to start WebLogic for your domain. The startup script file is typically located in a path similar to the following:

    <DOMAIN_HOME>\bin\startWebLogic.[cmd|sh]

    where <DOMAIN_HOME> is the path to your domain directory, such as C:\bea\user_projects\domains\<Domain_Name>; or C:\bea\wlserver_12.0\samples\domains\<Domain_Name> where <Domain_Name> is the name of your domain.

    For example, if your domain name is MedRec, the path would look like the following:

    C:\bea\wlserver_12.0\samples\domains\medrec\bin\startWebLogic.cmd

  2. Locate a convenient point in the file after all options are set, but before the java command line (or code block) that starts the application server is executed. At this point, insert additional configuration lines as illustrated by the examples below. In both examples you should replace <agent_install_dir> with the value for your environment.

    Below is an example showing the added lines in a .cmd file:

    echo starting weblogic with Java version:
    
    %JAVA_HOME%\bin\java %JAVA_VM% -version
    rem Configuring AppPulse Trace Java Agent Start
    set AGENT_HOME=<agent_install_dir>
    set PROBE_OPTS="%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar"
    set JAVA_OPTIONS=%JAVA_OPTIONS% %PROBE_OPTS%
    rem Configuring AppPulse Trace Java Agent End
    if "%WLS_REDIRECT_LOG%"=="" (
     echo Starting WLS with line:
     echo %JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% …%JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% …
    ) else (
     echo Redirecting output from WLS window to %WLS_REDIRECT_LOG%
     %JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% …
    )

    Below is an example showing the added lines in a .sh file:

    echo "starting weblogic with Java version:"
    
    ${JAVA_HOME}/bin/java ${JAVA_VM} -version
    
    # Configuring AppPulse Trace Java Agent Start
    AGENT_HOME=<agent_install_dir>
    PROBE_OPTS="$PROBE_OPTS -javaagent:$AGENT_HOME/lib/probeagent.jar"
    JAVA_OPTIONS="$JAVA_OPTIONS $PROBE_OPTS"
    # Configuring AppPulse Trace Java Agent End
    if [ "${WLS_REDIRECT_LOG}" = "" ] ; then
     echo "Starting WLS with line:"
     echo "${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} …
     ${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} …
    else
     echo "Redirecting output from WLS window to ${WLS_REDIRECT_LOG}" 
     ${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} …
    fi

    Note: If your java command line does not use the JAVA_OPTIONS variable to define the JVM parameters, you need to change the variable name JAVA_OPTIONS shown in these examples to the correct name.

  3. Enable wildcard host name verification. Add the following, additional configuration line in the startup script as described in the above step:

    -DUseSunHttpHandler=true

    Below is an example showing the added lines in a .cmd file:

    rem Configuring AppPulse Trace Java Agent Start
    set AGENT_HOME=<agent_install_dir>
    set PROBE_OPTS="%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar"
    set PROBE_OPTS="%PROBE_OPTS% -DUseSunHttpHandler=true"
    set JAVA_OPTIONS=%JAVA_OPTIONS% %PROBE_OPTS%
    rem Configuring AppPulse Trace Java Agent End

    Below is an example showing the added lines in a .sh file:

    # Configuring AppPulse Trace Java Agent Start
    AGENT_HOME=<agent_install_dir>
    PROBE_OPTS="$PROBE_OPTS -javaagent:$AGENT_HOME/lib/probeagent.jar"
    PROBE_OPTS="$PROBE_OPTS -DUseSunHttpHandler=true"
    JAVA_OPTIONS="$JAVA_OPTIONS $PROBE_OPTS"
    # Configuring AppPulse Trace Java Agent End
  4. Save the changes to the startup script and restart the application server using the modified script.

    See Verify that the Application Server is Running the Java Agent for more information.

webMethods

There are two types of webMethods servers discussed in this example:

  • webMethods Integration Server

  • My webMethods Server

The following sections provide general instructions with specific examples for webMethods Integration Server and My webMethods Server. Your site administrator should be able to use these instructions to show you how to make these changes in your customized environment.

To configure a webMethods Integration Server started without the configuration wrapper:

  1. Locate the startup script used to start the webMethods Integration Server and locate a convenient point in the file after all options are set but before the java command line (or code block) that starts the application server is executed. There are two possible scripts based on how the server is started:

    <software_ag_home>\IntegrationServer\bin\server.bat

    <software_ag_home>\profiles\IS\bin\runtime.bat

  2. Insert additional configuration lines as illustrated by these examples. In both examples you should replace <agent_install_dir> with the value for your environment.

    Below is an example showing the modified server.bat file:

    if exist "%JAVA_DIR%\bin\jre.exe" (
    set JAVA_EXEC="%JAVA_DIR%\bin\jre.exe"
    set JAVA_CP="%JAVA_DIR%\lib\classes.zip;%JAVA_DIR%\lib\i18n.jar"
    ) else (
    set JAVA_EXEC="%JAVA_DIR%\bin\java.exe"
    set JAVA_CP="%JAVA_DIR%\lib\rt.jar;%JAVA_DIR%\lib\i18n.jar"
    )
    
    rem Configuring AppPulse Trace Java Agent
    
    set AGENT_HOME=<agent_install_dir>
    set PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar
    set JAVA_OPTS=%JAVA_OPTS% %PROBE_OPTS%

    Below is an example showing the modified runtime.bat file:

    rem Configuring AppPulse Trace Java Agent
    set AGENT_HOME=<agent_install_dir>
    set PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar
    set JAVA_OPTS=%JAVA_OPTS% %PROBE_OPTS%
  3. Save the changes to the startup script and restart the application server using the modified script.

    See Verifying the Java Agent for more information.

To configure a webMethods Integration Server started with the configuration wrapper:

Use this method if the application server is started as a service using <software_ag_home>\profiles\IS\bin\service.bat.

  1. Locate the webMethods Integration Server custom_wrapper.conf file. This file is typically located in:

    <software_ag_home>\profiles\IS\configuration\custom_wrapper.conf.

  2. Insert additional configuration lines as illustrated by this example. In the example you should replace <agent_install_dir> with the value for your environment.

    Add the wrapper.java.additional entry near the other wrapper.java.additional parameters, changing number 777 as needed for your configuration.

    Below is an example showing the modified custom_wrapper.conf file:

    # Put here your custom properties.
    
    # Configuring AppPulse Trace Java Agent
    set.AGENT_HOME=<agent_install_dir>
    set.PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar
    wrapper.java.additional.777=%PROBE_OPTS%
  3. Save the changes to the configuration wrapper and restart the application server using the modified wrapper.

    See Verifying the Java Agent for more information.

To configure the My webMethods Server started without the configuration wrapper:

Use this method if you start the application server by using the run command.

  1. Locate the startup script used to start the My webMethods Server and locate a convenient point in the file after all options are set but before the java command line (or code block) that starts the application server is executed.

    The script file is: <ag_software_home>\MWS\bin\mws.bat.

  2. Insert additional configuration lines as illustrated by this example. In the example you should replace <agent_install_dir> with the value for your environment.

    The following is an example of the modified mws.bat file:

    rem Configuring AppPulse Trace Java Agent
    set AGENT_HOME=<agent_install_dir>
    set PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar
    set JAVA_OPTIONS=%JAVA_OPTIONS% %PROBE_OPTS%
    
    set JAVA_OPTIONS=%JAVA_OPTIONS% -Dserver.name=%SERVER_NAME% ...
    set PARAMS=
    set MAIN_CLASS=com.webmethods.portal.system.PortalSystem
    set RUN_CMD=%JAVA% -cp %CLASSPATH% %JAVA_ARGS% %JAVA_OPTIONS% ...
  3. Save the changes to the startup script and restart the application server using the modified script.

See Verifying the Java Agent for more information.

To configure the My webMethods Server started with the configuration wrapper:

Use this method if you start the application server as a service or by using the start command.

Note: This method requires customizations to the wrapper.conf file, which which may be overridden when the application server is upgraded or patched.

  1. Locate the My webMethods Server wrapper.conf file. This file is typically located in:

    <ag_software_home>\MWS\server\<server_name>\config\wrapper.conf.

  2. Insert additional configuration lines as illustrated by this example. In the example you should replace <agent_install_dir> with the value for your environment.

    Add the wrapper.java.additional entry near the other wrapper.java.additional parameters, changing number 777 as needed for your configuration.

    Below is an example showing the modified wrapper.conf file:

    # Java Additional Parameters
    …
    # Configuring AppPulse Trace Java Agent
    set.AGENT_HOME= <agent_install_dir>
    set.PROBE_OPTS=%PROBE_OPTS% -javaagent:%AGENT_HOME%\lib\probeagent.jar
    wrapper.java.additional.777=%PROBE_OPTS%
    #NOTE: wrapper.java.additional.300 to 310 is reserved for debug configuration !
  3. Save the changes to the configuration wrapper and restart the application server using the modified wrapper.

See Verify that the Application Server is Running the Java Agent for more information.

WebSphere

Note:  

  • If you installed the Java Agent using the automatic deployment (for details, see Deployment), steps 2 and 3 of the following procedure have already been done.

  • For WebSphere Application Server (WAS) 8.x, you must apply Fix Pack 9 or later.

The following section provides general instructions with specific examples for the WebSphere application server for a generic implementation. Your site administrator should be able to use these instructions to show you how to make these changes in your customized environment.

To configure WebSphere

  1. Configure WebSphere for SSL communication with the AppPulse Trace servers:
    1. Download the Public CA's certificates required for AppPulse Trace:

      1. Determine the AppPulse Trace server from which to download the certificates. You can see this in the registration.url property in the <agent installation directory>/etc/app-pulse-agent.properties file.

      2. Using the host and port from the registration.url property, browse to the AppPulse Trace server. For example, if the registration.url contains the string: https://apppulse-trace-server.saas.hpe.com:443/probe-controller/registrar, use the following URL in your browser:

        https://apppulse-trace-server.saas.hpe.com:443
      3. On the URL line of the browser, click the lock icon and select the options for viewing certificates. (For example, in Internet Explorer, select View certificates > Certification Path.)

      4. Export all of the certificates that are listed above the *.saas.hpe.com certificate to the WebSphere host machine. In the example below, these are the three certificates whose name begins with Entrust.

        (For example, in Internet Explorer, highlight the certificate and select View Certificate > Details > Copy to File.)

        When copying the certificates, save them in the format of Base-64 encoded X.509 (.CER).

    2. Add the certificates to WebSphere:

      1. Log in to the WebSphere Application Server Administrative Console. For example:

        http://<App_Server_Host>:9060/ibm/console

        Replace <App_Server_Host> with the machine name for the application server host and 9060 with the correct administrative port number (such as 9060, 9061, and so on).

      2. Select Security > SSL Certificate and key management > Key stores and certificates > NodeDefaultTrustStore> Signer Certificates > add.

      3. Enter the alias and the path to the certificate files for the certificates you downloaded.

  2. Configure the JVM parameters:

    1. Locate the application JVM configuration settings by navigating to the Java Virtual Machine page. For example: Servers > Server Types > WebSphere Application servers.
      1. Click the application server instance name (such as server1).

      1. Under Server Infrastructure > Java and Process Management, click Process Definition.

      1. Under Additional Properties, click Java Virtual Machine.

    2. On the Java Virtual Machine page, in the Generic JVM Arguments box, enter the JVM parameters.

      For WebSphere running on any IBM Java Runtime supported by the Java Agent, enter the following JVM parameters. In the example replace <agent installation directory> with the value for your environment.

      -javaagent:<agent installation directory>\lib\probeagent.jar
      -Djava.security.properties=<agent installation directory>\etc\ibm.default.java.security
      -Xshareclasses:none

      Note: Ensure that directory names for the Java Agent do not contain spaces as WebSphere configuration does not support spaces within arguments.

  3. Apply and save your changes, and restart the application server.

  4. Verify the Connection.

    Manually verify Java Agent connectivity with both the application server and the AppPulse Trace server. For details, see Verifying the Java Agent.

WebSphere Application Server Liberty

The following section provides instructions with specific examples for a generic implementation of the Liberty Profile of WebSphere Application Server (WAS) 8.5. Your site administrator should be able to use these instructions to assist you in making these changes in your customized environment.

To configure a WAS Liberty Profile Server with a startup script:

  1. In the directory <application_server>/usr/servers/<server_name> (for example, WebSphere_8.5/Liberty/usr/servers/defaultServer) create a text file named jvm.options with the following content:

    -javaagent:<agent installation directory>/lib/probeagent.jar
    -Xshareclasses:none

    If you have enabled SSL, also add the following line:

    -Djava.security.properties=<agent installation directory>/etc/ibm.default.java.security
  1. In the same directory, create another text file named bootstrap.properties with the following content:

    org.osgi.framework.bootdelegation=com.mercury.opal.capture.*

Note: For a WebSphere Liberty Server that uses CICS 5.2+ on z/OS, additionally add the following line to the xxx.jvmprofile file:

org.osgi.framework.bootdelegation=com.mercury.opal.capture.*