AppPulse Trace. Java Agent Guide April 2016

Transcription

1 AppPulse Trace Java Agent Guide April 2016

2 Legal Notices Warranty The only warranties for Hewlett Packard Enterprise products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HPE shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice. Restricted Rights Legend Confidential computer software. Valid license from HPE required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Copyright Notice Copyright Hewlett Packard Enterprise Development LP Trademark Notices Adobe is a trademark of Adobe Systems Incorporated. Google and Google Maps are trademarks of Google Inc. ipad is a trademark of Apple Inc. Java is a registered trademark of Oracle and/or its affiliates. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation. Oracle is a registered trademark of Oracle and/or its affiliates. Red Hat is a registered trademark of Red Hat, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group. AppPulse Trace Page 2 of 70

3 Contents Welcome to This Guide 5 How This Guide Is Organized 5 Part 1: Introduction 6 Chapter 1: Overview and System Requirements 7 Overview 7 System Requirements 7 General Support Notes 7 Supported Operating Systems 8 Supported JVMs 8 Supported Application Servers 9 Part 2: Deployment 10 Chapter 2: Pre-Deployment 11 Deployment Mode Comparison 11 Files Modified by the Deployment Program 12 Chapter 3: Deployment 15 Chapter 4: Post Deployment 20 Setting File Permissions 20 Verifying the Java Agent 20 Verify that the Application Server is Running the Java Agent 20 Verify Java Agent connectivity with the AppPulse Trace server 21 Verify that the Java Agent successfully starts 22 Chapter 5: Preparing Application Servers for Monitoring 23 Examples for Configuring Application Servers 23 JBoss or WildFly 24 Jetty 27 Tomcat 29 WebLogic 30 WebSphere 33 GlassFish 38 TIBCO ActiveMatrix BusinessWorks and Service Bus 39 webmethods 42 Chapter 6: Preparing Application Servers for Client Monitoring 46 About Client Monitoring 46 Enabling Client Monitoring 47 Configuring and Disabling Client Monitoring 47 Client Monitoring System Requirements 47 AppPulse Trace Page 3 of 70

4 Chapter 7: Removing the Java Agent 49 Part 3: Upgrade 51 Chapter 8: Upgrade 52 Upgrading the Java Agent in the Same Location 52 Upgrading the Java Agent in a New Location 52 Application Servers Supported for Auto Deployment 52 Application Servers Not Supported for Auto Deployment and Other Java Processes 53 Part 4: Configuration 54 Chapter 9: Configuring Security 55 Accessing the Java Agent Maintenance Page 55 Privacy Controls 56 Chapter 10: Configuring the app-pulse-agent.properties File 57 To change an agent's name 57 To change an agent's proxy settings 57 Chapter 11: Configure Monitoring of Multiple Java Processes on an Application Server 58 Chapter 12: Adjusting the Heap Size for the Java Agent in the Application Server 61 Chapter 13: Configuring the SOAP Message Handler 62 Chapter 14: Special Considerations for Applications Based on the OSGi Framework 63 Part 5: Troubleshooting 64 Chapter 15: Deployment Troubleshooting 65 Chapter 16: Missing or No Data Troubleshooting 67 Chapter 17: Miscellaneous Troubleshooting 69 Send Documentation Feedback 70 AppPulse Trace Page 4 of 70

5 Welcome to This Guide Welcome to the Hewlett Packard Enterprise (HPE) AppPulse Trace Java Agent Guide. This guide describes how to deploy, configure, and use the AppPulse Trace Java Agent. The AppPulse Trace Java Agent captures events such as method invocations, method parameters, and the beginning and end of business and server transactions. How This Guide Is Organized This guide contains the following parts: Part 1: "Introduction" on page 6 Provides a high level overview of the Java Agent and system requirements. Part 2: "Deployment" on page 10 Describes how to deploy the Java Agent. Part 3: "Upgrade" on page 51 Describes how to upgrade the Java Agent. Part 4: "Configuration" on page 54 Describes additional configuration options for the Java Agent. Part 5: "Troubleshooting" on page 64 Describes troubleshooting issues and possible solutions. AppPulse Trace Page 5 of 70

6 Part 1: Introduction This part provides a high level overview of the Java Agent and lists system requirements. AppPulse Trace Page 6 of 70

7 Chapter 1: Overview and System Requirements Overview The AppPulse Trace Java Agent is deployed on the machine that hosts the application that you want to monitor. The agent captures events such as method invocations, method parameters, and the beginning and end of business and server transactions. The Java Agent and the application environment must be configured to enable monitoring of your application. Instructions for deploying and configuring the Java Agent can be found in the following sections: Deployment Configuration System Requirements General Support Notes Supported Tiers All items are supported without limitations unless otherwise stated. Supported Versions When a sub-version is specified as x (for example ios 8.x), the latest version at the time of documentation is implied. End-of-Life Support All items are supported as long as they have not been declared end-of-life by their vendors. All supported operating systems and JVMs are 64 bit. AppPulse Trace Page 7 of 70

8 Chapter 1: Overview and System Requirements Supported Operating Systems Microsoft Windows 2008 R2* Windows Server 2012 Windows Server 2012 R2 IBM AIX 6.1* AIX 7.1* Linux Red Hat Enterprise Linux 6.x Red Hat Enterprise Linux 7.x SUSE Linux Enterprise Server 11 SUSE Linux Enterprise Server 12 Oracle Enterprise Linux 6.x Oracle Enterprise Linux 7.x Ubuntu Server (LTS) * Supported with possible limitations. Supported JVMs Oracle IBM (MicroSoft and IBM operating systems only) OpenJDK (Linux based operating systems only) 6.x* 7.x 8.x 6.x* 7.x 7 8 * Supported with possible limitations. AppPulse Trace Page 8 of 70

9 Chapter 1: Overview and System Requirements Supported Application Servers Apache Tomcat 7.x 8.x 9.x IBM WebSphere Application Server (WAS) x Note: You must apply Fix Pack 9 or later. Oracle WebLogic 11g 12c WildFly 8.x 9.x JBoss Enterprise Application Platform 6.x JBoss Application Server 6.1.x* 7.x* Jetty** 8.x* 9.x* * Supported with possible limitations. ** Not supported for automatic deployment. AppPulse Trace Page 9 of 70

10 Part 2: Deployment This part describes the options for deploying the Java Agent. AppPulse Trace Page 10 of 70

11 Chapter 2: Pre-Deployment Before you deploy a Java Agent, learn about the following: "Deployment Mode Comparison" below "Files Modified by the Deployment Program" on the next page Deployment Mode Comparison The following table compares the different modes you can use to deploy the Java Agent. Deployment Program in Silent Mode Deployment Program in Interactive Mode Manual Deployment Description Automatic deployment in silent mode, using default settings. Automatic deployment in interactive mode, enabling input during the deployment of the source directory and if necessary, proxy settings. Manual configuration of startup scripts. Usage For Tomcat, JBoss, WildFly, WebSphere, and WebLogic. For Tomcat, JBoss, WildFly, WebSphere, and WebLogic. For any Java process or application server. For details on supported application servers, see "System Requirements" on page 7. AppPulse Trace Page 11 of 70

12 Chapter 2: Pre-Deployment Deployment Program in Silent Mode Notes Recommende d deployment mode. This is the quickest and easiest way to deploy the Java Agent. If necessary, you can configure proxy settings manually after the deployment. Deployment Program in Interactive Mode Use this deployment mode if you did not unzip the deployment package into the Server Home Directory, or if you want to configure proxy settings during the deployment. Manual Deployment Use this deployment mode for: Any other Java process or application server. Tomcat, JBoss, WildFly, WebSphere, and WebLogic if you use custom scripts or procedures. For details, see... "Automatic Deployment in Silent Mode" on page 16 "Automatic Deployment in Interactive Mode" on page 17 "Manual Deployment" on page 18 Files Modified by the Deployment Program The deployment program modifies the startup script (for Tomcat, JBoss, WildFly, and WebLogic), or the xml file (for WebSphere), for the application server, so that the Java Agent will start monitoring the application the next time the application server is started. The original, initial version of the modified file is saved as a backup in the same location. The file is named as follows: HPbackup_year_month_day_originalFileName. For example, HPbackup_2015_5_17_domain.bat. Note: If the deployment program modifies the same file more than once on the same date, a sequential version number is also added to the file name for the additional backup files created. For example, HPbackup_2015_5_17_domain_2.bat. AppPulse Trace Page 12 of 70

13 Chapter 2: Pre-Deployment Details of which files have been modified during deployment can be viewed in the <agent installation directory>\bin\setupmodule.log file. File Modified by the Deployment Backup File For Tomcat: <TOMCAT_HOME>/bin/catalina.[bat sh] For Tomcat when run as a Windows service: When Tomcat is run as a service, the following registry key is modified: HKEY_LOCAL_ MACHINE\SOFTWARE\Wow6432Node\Ap ache Software Foundation\Procrun 2.0\<Tomcat Service Name>\Parameters\Java\Options For JBoss Version 7.x and Wildfly Versions 8.x, 9.x: <JBOSS_HOME>/bin/domain.[bat sh] <JBOSS_HOME>/bin/standalone.[bat sh] <TOMCAT_HOME>/bin//HPbackup_ <date>_catalina.[bat sh] No automatic backup is made. You can manually save the registry for backup purposes and restore the backup as needed. To manually edit the specific registry key, use the regedit command or the <Tomcat HOME>/bin/tomcat7w.exe command (double-click to launch and then select Java tab > Java Options). To restore the registry key to the original, delete the first line -javagent... <JBOSS_HOME>\bin\HPbackup_ <date>_domain.[bat sh] <JBOSS_HOME>\bin\HPbackup_ <date>_standalone.[bat sh] For JBoss Version 6.x: <JBOSS_HOME>/bin/run.[bat sh] For WebLogic: <WebLogic HOME>\user_ projects\domains\<domain>\bin\startweblo gic.[cmd sh] <JBOSS_HOME>/bin/HPbackup_ <date>_run.bat <WebLogic HOME>\user_ projects\domains\<domain>\bin\hpbac kup_<date>_startweblogic.[cmd sh] AppPulse Trace Page 13 of 70

14 Chapter 2: Pre-Deployment File Modified by the Deployment Backup File For WebSphere: <WebSphere HOME>\AppServer\profiles\<PROFILE NAME>\config\cells\<CELL NAME>\nodes\<NODE NAME>\servers\<SERVER NAME>\server.xml <WebSphere HOME>\AppServer\profiles\<PROFILE NAME>\config\cells\<CELL NAME>\nodes\<NODE NAME>\servers\<SERVER NAME>\HPbackup_<date>_server.xml The deployment dialog indicates whether the startup script has been modified successfully. AppPulse Trace Page 14 of 70

15 Chapter 3: Deployment This chapter describes the steps required for downloading and deploying a Java Agent. 1. Prepare the host where the Java Agent is to be deployed. The Java Agent must reside on the same host as the Java application or process to be monitored. The agent cannot monitor an application remotely. The host also must meet the system requirements. For details, see "System Requirements" on page 7. Note: The host on which you are installing the agent must be able to access saas.hpe.com using the standard https port number 443 either directly, through a proxy server, or through a Firewall, depending on your infrastructure configuration. (For details on configuring a proxy server in AppPulse Trace, see "Automatic Deployment in Interactive Mode" on page 17 and "To change an agent's proxy settings" on page 57.) You can view the exact HPE SaaS URL to which you need access in the registration.url parameter in the <agent installation directory>/etc/app-pulseagent.properties file. You can test your connectivity to the AppPulse Trace server. For details, see "Verify Java Agent connectivity with the AppPulse Trace server" on page Add an application for monitoring in AppPulse Trace. When you first log in to AppPulse Trace, you are required to configure an initial, default application. You can add and configure additional applications at any time. 3. Download the Java Agent deployment package. When you configure a new application for monitoring in AppPulse Trace, you are required to specify the type of application server technology you want to monitor (for example, Java) and to download the relevant deployment package (as a zip file). The download is specific for that application and contains embedded data about the application. 4. Unzip the deployment package. Unzip the downloaded Java Agent deployment package to a directory on the machine hosting the application that you want to monitor. Note: We recommend using the Application Server Home directory, as the silent deployment mode searches for this directory by default. AppPulse Trace Page 15 of 70

16 Chapter 3: Deployment A sub-directory called AppPulseJavaAgent is created in the directory to which you unzip the deployment package. Throughout this guide, the term <agent installation directory> refers to <the directory to which you unzip the deployment package>/apppulsejavaagent. For WebSphere, ensure that directory names for the Java Agent do not contain spaces as WebSphere configuration does not support spaces within arguments. If the user who unzips the file does not have the necessary file permissions (for AIX and Linux), you must set the file permissions manually after unzipping the file. For details, see "Setting File Permissions" on page Run the Java Agent deployment. For a description of the different deployment modes and to determine which mode is most suitable for your needs, see "Deployment Mode Comparison" on page 11. Automatic Deployment in Silent Mode This is the recommended deployment mode for Tomcat, Jboss, WildFly, WebSphere, and WebLogic. Note: You cannot configure proxy settings (for connecting to the AppPulse Trace server) as part of a silent deployment, but can configure them manually after the deployment. For details, see "Configuring the app-pulse-agent.properties File" on page 57. Run the following command to start the Java Agent deployment in a silent mode: <agent installation directory>/lib java -jar AppPulseAgent.jar setup Note: By default, the deployment program uses the directory from which it is run to search for the Application Server Home directory. If you did not unzip the downloaded deployment package to the Application Server Home directory, you must then specify the Application Server Home directory in the command. For example: <agent installation directory>/lib java -jar AppPulseAgent.jar setup <Application Server Home directory> Interactive Help AppPulse Trace Page 16 of 70

17 Chapter 3: Deployment To display help about the deployment, run: <agent installation directory>/lib java -jar AppPulseAgent.jar Automatic Deployment in Interactive Mode The interactive deployment of the Java Agent includes the following steps: a. Start the Agent Deployment Run the following command to start the Java Agent deployment in an interactive mode: <agent installation directory>/lib java -jar AppPulseAgent.jar setup -interactive b. Specify the Application Server Home Directory By default, this is the directory from which the deployment is run. c. Configure Proxy Server Settings (optional) If you are using a Proxy server to connect to the AppPulse Trace server, enter 'Y' (Yes) and then configure the following settings: o The Proxy server name. o The Proxy server port (default 8080). o o The Proxy server user name (optional). The Proxy server password (optional). d. Save the Configuration and Exit the Interactive Dialog Enter 'Y' (Yes) to save the configuration and exit the interactive dialog, or enter 'N' (No) to restart the configuration. Interactive Help and Dialog Input Options To display help about the deployment, run: <agent installation directory>/lib java -jar AppPulseAgent.jar During the deployment, you can use any of the following options when prompted for input: Enter. Accept the default value. Minus (-). Previous step. Plus (+). Next step. c. Cancel. f. Finish. AppPulse Trace Page 17 of 70

18 Chapter 3: Deployment Manual Deployment You can manually deploy and configure the Java Agent for any Java process or application server. Note: We recommend that for Tomcat, JBoss, WildFly, WebSphere, and WebLogic you deploy and configure the Java Agent using the deployment program in silent mode. For details, see "Automatic Deployment in Silent Mode" on page 16. A manual deployment of the Java Agent includes the following steps: a. Edit the Java Process Startup Command Add the following parameter to the Java process startup command: -javaagent:<agent installation directory>/lib/probeagent.jar b. Configure Additional Changes Additional configuration changes are required, depending on the type of application server. For details, see "Preparing Application Servers for Monitoring" on page 23. c. Configure Proxy Settings (optional) You can manually configure proxy settings for the Java Agent (if relevant for the machine on which the agent is installed). For details, see "Configuring the apppulse-agent.properties File" on page Verify that the Application Server is running the Java Agent. The automatic deployment process verifies connectivity between the Java Agent and the AppPulse Trace server and displays the result. For a manual deployment, run this verification manually. For details, see "Verify Java Agent connectivity with the AppPulse Trace server" on page 21. Manually verify that the Application Server is running the Java Agent. For details, see "Verify that the Application Server is Running the Java Agent" on page Restart the application server to pick up the changes to the startup script. The automatic deployment process modifies the Application Server startup script and saves a backup of the original. For details, see "Files Modified by the Deployment Program" on page 12. Note: For WebLogic, the startup script is additionally modified to enable secure communications with AppPulse Trace. For details of these changes, see step 3 AppPulse Trace Page 18 of 70

19 Chapter 3: Deployment in "WebLogic" on page 30. Restart the Application Server using the updated startup script. After a few minutes, you will be able to view application performance data in AppPulse Trace. 8. (Optional) Add additional configuration. For details, see "Configuration" on page 54. AppPulse Trace Page 19 of 70

20 Chapter 4: Post Deployment This chapter includes the following topics: "Setting File Permissions" below "Verifying the Java Agent" below Setting File Permissions All installations: As files in the <agent installation directory>/log and <agent installation directory>/etc directories may contain sensitive data, we recommend that you consider restricting access to these directories for other users. AIX and Linux installations only: If the deployment package was unzipped by a user without the required permissions, after deploying the Java Agent make the agent s 'group the same as the application server s group. Then assign the following permissions to files in the <agent installation directory> for the group: Read access to the <agent installation directory> directory and files. Execute access to the <agent installation directory>/bin directory. Read/Write access to the <agent installation directory>/log directory. Read/Write access to the <agent installation directory>/etc directory. Verifying the Java Agent You can run the following verification checks: "Verify that the Application Server is Running the Java Agent" below "Verify Java Agent connectivity with the AppPulse Trace server" on the next page "Verify that the Java Agent successfully starts" on page 22 Verify that the Application Server is Running the Java Agent Start the application server and ensure that it has started successfully. Validate that the <agent installation directory>/log/<probe_name>/probe.log AppPulse Trace Page 20 of 70

21 Chapter 4: Post Deployment contains entries for the current Java Agent run. On the application server, direct your browser to the localhost, using the Java Agent's port number. For example: Note: By default, port is assigned to a single Java Agent on an application server. When there are multiple Java Agents on the same machine, each Java Agent is assigned a different port number. To determine the port number used for a Java Agent, edit the <agent installation directory>/log/<probe_ name>/probe.log file and search for the string Successfully bound to UDP port [nnnnn], owning system metrics, where [nnnnn] is the port number assigned to the Java Agent. The following page is displayed: Verify Java Agent connectivity with the AppPulse Trace server To verify that the Java Agent successfully connects with the AppPulse Trace server, run the following command at any time: <agent installation directory>/lib java -jar AppPulseAgent.jar AppPulse Trace Page 21 of 70

22 Chapter 4: Post Deployment setup -connectivity-test Note: A similar test is automatically run when you deploy the Java Agent for Tomcat, JBoss, WildFly, WebSphere, and WebLogic using the deployment program. The results of the test are displayed as part of the deployment summary. Verify that the Java Agent successfully starts To verify that the Java Agent successfully starts, runs, and is able to communicate, run the following test script at any time: <agent installation directory>\bin\runtestprobe.cmd on Windows <agent installation directory>/bin/runtestprobe.sh on UNIX and Linux This script runs a test agent that attempts to connect to the AppPulse Trace server. The script displays log messages that indicate success, or why the test agent is failing to connect. The failure messages can help you identify why the agent for your monitored application is not connecting to the AppPulse Trace server. Press CTRL-C to stop the test script. AppPulse Trace Page 22 of 70

23 Chapter 5: 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" on page 15), 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" on page 7. 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" on page 15. Use quotes if there are spaces in the files paths that you specify. "JBoss or WildFly" on the next page "Jetty" on page 27 AppPulse Trace Page 23 of 70

24 Chapter 5: Preparing Application Servers for Monitoring "Tomcat" on page 29 "WebLogic" on page 30 "WebSphere" on page 33 "GlassFish" on page 38 "TIBCO ActiveMatrix BusinessWorks and Service Bus" on page 39 "webmethods" on page 42 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" on page 15), 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 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] AppPulse Trace Page 24 of 70

25 Chapter 5: Preparing Application Servers for Monitoring where <JBOSS_HOME> is the path to your JBoss installation directory, such as C:\jboss-as 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 HP 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 HP 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 AppPulse Trace Page 25 of 70

26 Chapter 5: Preparing Application Servers for Monitoring =============================================================== ================ echo. echo JBoss Bootstrap Environment rem Configuring HP 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 HP 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" on page 20. AppPulse Trace Page 26 of 70

27 Chapter 5: Preparing Application Servers for Monitoring 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" on page 20. 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: :59:36.091:INFO::main: Logging :59:37.213:INFO::main: Redirecting stderr/stdout to /tmp/jetty-distribution v /logs/2016_02_ 25.stderrout.log AppPulse Trace Page 27 of 70

28 Chapter 5: Preparing Application Servers for Monitoring OK Thu Feb 25 10:59:38 IST 2016 bin]#./jetty.sh stop Stopping Jetty: OK bin]# vi jetty.sh bin]#./jetty.sh start Starting Jetty: :02:55,336 INFO [com.mercury.opal.common.loader]: Loading modules.properties from: /opt/apppulsejavaagent/lib/modules.properties :02:55,937 INFO [webserver]: AppPulse Trace Web Server listening on / :35000 HP AppPulse Trace Java Agent '<agent name>', version: Development, pid: :02:59.111:INFO:oejs.Server:jetty v :02:59.244:INFO:oejs.AbstractConnector:Started _ SocketListener@ : :03:00.881:INFO::main: Logging :03:03.641:INFO::main: Redirecting stderr/stdout to /tmp/jetty-distribution v /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: :52:13,985 INFO [com.mercury.opal.common.loader]: Loading modules.properties from: C:\ApplicationServers\tomcats\apache-tomcat \AppPulseJavaAgent\lib\modules.properties :52:15,644 INFO [webserver]: AppPulse Trace Web Server listening on / :35000 AppPulse Trace Web Server listening on / :35000 AppPulse Trace Page 28 of 70

29 Chapter 5: Preparing Application Servers for Monitoring HP AppPulse Trace Java Agent '<agent name>', version: , pid: :52:16.685:INFO:oejs.Server:jetty v :52:16.734:INFO:oejs.AbstractConnector:Started _ SocketListener@ : :52:17.382:INFO::main: Logging :52:17.804:INFO:oejs.Server:main: jetty v :52:17.835:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///c:/applicationservers/jetties/jettydistribution v /webapps/] at interval :52:17.851:INFO:oejs.ServerConnector:main: Started ServerConnector@71cb0be4{HTTP/1.1,[http/1.1]}{ :8080} :52:17.851:INFO:oejs.Server:main: 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" on page 15), 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:" below. 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:" on the next page. 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 AppPulse Trace Page 29 of 70

30 Chapter 5: Preparing Application Servers for Monitoring 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 HP 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 HP 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" on page 20. To configure a Tomcat server without a startup script: 1. Run the <Tomcat HOME>/bin/tomcat7w.exe command. 2. Select Java tab > Java Options). 3. 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 4. Restart the Tomcat service. 5. 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" on page 20. 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. AppPulse Trace Page 30 of 70

31 Chapter 5: Preparing Application Servers for Monitoring If you installed the Java Agent using the automatic deployment (for details, see "Deployment" on page 15), 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 HP 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 HP 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% ) AppPulse Trace Page 31 of 70

32 Chapter 5: Preparing Application Servers for Monitoring 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 HP 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 HP 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 HP 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" AppPulse Trace Page 32 of 70

33 Chapter 5: Preparing Application Servers for Monitoring set JAVA_OPTIONS=%JAVA_OPTIONS% %PROBE_OPTS% rem Configuring HP AppPulse Trace Java Agent End Below is an example showing the added lines in a.sh file: # Configuring HP 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 HP 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" on page 20 for more information. WebSphere Note: If you installed the Java Agent using the automatic deployment (for details, see "Deployment" on page 15), 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. AppPulse Trace Page 33 of 70

34 Chapter 5: Preparing Application Servers for Monitoring To configure WebSphere 1. Configure WebSphere for SSL communication with the AppPulse Trace servers: a. Edit the IBM/WebSphere/AppServer/java/jre/lib/security/java.security file: i. Uncomment the following lines (by removing the hash (#) sign): ssl.socketfactory.provider=com.ibm.jsse2.sslsocketfactory Imp ssl.serversocketfactory.provider=com.ibm.jsse2.sslservers ocketfactoryimpl ii. Comment out the following lines (by adding a hash (#) sign): #ssl.socketfactory.provider=com.ibm.websphere.ssl.protoco l.sslsocketfactory #ssl.serversocketfactory.provider=com.ibm.websphere.ssl.p rotocol.sslserversocketfactory b. Download the certificate required for AppPulse Trace: i. Determine the AppPulse Trace server from which to download the certificate. You can see this in the registration.url property in the <agent installation directory>/etc/app-pulse-agent.properties file. ii. 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: use the following URL in your browser: iii. On the URL line of the browser, click the lock icon and select the options for installing or downloading the certificate. (For example, in Mozilla Firefox, select More information > View certificate > Details > Export.) iv. Copy the certificate file to the WebSphere host machine. c. Add the certificate to WebSphere: i. Log in to the WebSphere Application Server Administrative Console. For example: AppPulse Trace Page 34 of 70

35 Chapter 5: Preparing Application Servers for Monitoring 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). ii. Select Security > SSL Certificate and key management > Key stores and certificates > NodeDefaultTrustStore> Signer Certificates > add. iii. Enter the alias and the path to the certificate file for the certificate you downloaded. 2. Additionally configure WebSphere for SSL communication with the AppPulse Trace servers when Java 2 is enabled: If Java 2 security is enabled in WebSphere, edit the <Web_Sphere_Home_ Directory>/java/jre/lib/security/java.policy file (for example: IBM/WebSphere/AppServer/java/jre/lib/security/java.policy) and add the following lines at the end of the file: grant codebase "file:/<agent installation directory>/-" { permission java.security.allpermission; permission java.net.socketpermission "*.saas.hpe.com", "connect,accept,resolve"; Example for Windows: grant codebase "file:/c:/websphere/apppulsejavaagent/-" { permission java.security.allpermission; permission java.net.socketpermission "*.saas.hpe.com", "connect,accept,resolve"; Example for Linux: AppPulse Trace Page 35 of 70

36 Chapter 5: Preparing Application Servers for Monitoring grant codebase "file:/opt/ibm/websphere/appserver/apppulsejavaagent/-" { permission java.security.allpermission; permission java.net.socketpermission "*.saas.hpe.com", "connect,accept,resolve"; Save the file. 3. Configure the JVM parameters: a. Locate the application JVM configuration settings by navigating to the Java Virtual Machine page. For example: Servers > Server Types > WebSphere Application servers. i. Click the application server instance name (such as server1). ii. Under Server Infrastructure > Java and Process Management, click Process Definition. AppPulse Trace Page 36 of 70

37 Chapter 5: Preparing Application Servers for Monitoring iii. Under Additional Properties, click Java Virtual Machine. b. 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 -Xshareclasses:none Note: Ensure that directory names for the Java Agent do not contain spaces as WebSphere configuration does not support spaces within arguments. AppPulse Trace Page 37 of 70

38 Chapter 5: Preparing Application Servers for Monitoring 4. Apply and save your changes, and restart the application server. 5. 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" on page 20. 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 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. AppPulse Trace Page 38 of 70

39 Chapter 5: Preparing Application Servers for Monitoring 1. Locate the GlassFish JVM configuration settings by logging in to the GlassFish Administration Console and navigating to the JVM Options page. For GlassFish 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" on page 20 for more information. 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. AppPulse Trace Page 39 of 70

40 Chapter 5: Preparing Application Servers for Monitoring 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 HP 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" on page 20 for more information. To configure TIBCO ActiveMatrix Service Bus: Note: TIBCO ActiveMatrix Service Bus (AMSB) requires additional, special settings to work properly with the agent. AppPulse Trace Page 40 of 70

41 Chapter 5: Preparing Application Servers for Monitoring Locate the TIBCO ActiveMatrix Service Bus 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 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 HP AppPulse Trace Java Agent tibco.env.agent_home=<agent_install_dir> tibco.env.probe_options=%probe_options% -javaagent:%agent_ HOME%/lib/probeagent.jar AppPulse Trace Page 41 of 70