Foglight

®

5.2.3

Installing the Java EE Management Capabilities

© 2008 Quest Software, Inc. ALL RIGHTS RESERVED. This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of Quest Software, Inc. If you have any questions regarding your potential use of this material, contact: Quest Software World Headquarters LEGAL Dept 5 Polaris Way Aliso Viejo, CA 92656 www.quest.com email: [email protected] Refer to our Web site for regional and international office information.

Trademarks Quest, Quest Software, the Quest Software logo, Aelita, AppAssure, Benchmark Factory, Big Brother, DataFactory, DeployDirector, ERDisk, Foglight, Funnel Web, I/Watch, Imceda, InLook, IntelliProfile, InTrust, IT Dad, I/Watch, JClass, Jint, JProbe, LeccoTech, LiteSpeed, LiveReorg, NBSpool, NetBase, Npulse, PerformaSure, PL/Vision, Quest Central, RAPS, SharePlex, Sitraka, SmartAlarm, Spotlight, SQL LiteSpeed, SQL Navigator, SQL Watch, SQLab, Stat, Stat!, StealthCollect, Tag and Follow, Toad, T.O.A.D., Toad World, Vintela, Virtual DBA, Xaffire, and XRT are trademarks and registered trademarks of Quest Software, Inc in the United States of America and other countries. Other trademarks and registered trademarks used in this guide are property of their respective owners.

Disclaimer The information in this document is provided in connection with Quest products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Quest does not make any commitment to update the information contained in this document.

Installation and Configuration Guide August 2008 Version 5.2.3

Table of Contents Introduction to this Guide ...................................................................................................................................7 About Foglight .................................................................................................................................................................. 8 About this Guide............................................................................................................................................................... 8 Foglight Documentation Suite .......................................................................................................................................... 9 Core Documentation Set ......................................................................................................................................... 9 Cartridge Documentation Sets .............................................................................................................................. 10 Feedback on the Documentation........................................................................................................................... 10 Text Conventions ........................................................................................................................................................... 10 About Quest Software, Inc. ............................................................................................................................................ 11 Contacting Quest Software.................................................................................................................................... 12 Contacting Quest Support ..................................................................................................................................... 12

Introducing the Cartridge for Java EE .............................................................................................................13 Overview ........................................................................................................................................................................ 14 Key Concepts and Terms............................................................................................................................................... 14 Cartridge for Java EE Environment................................................................................................................................ 15 Service Requests .................................................................................................................................................. 16 What Does the Cartridge for Java EE Do?..................................................................................................................... 16 Key Components of the Cartridge for Java EE .............................................................................................................. 17 Instrumented Agent for Java EE............................................................................................................................ 17 Nexus .................................................................................................................................................................... 18 Foglight.................................................................................................................................................................. 18

Installing the Cartridge and the Agent .............................................................................................................19 Overview ........................................................................................................................................................................ 20 System Requirements .................................................................................................................................................... 20 Installing the Cartridge for Java EE................................................................................................................................ 20

4

Foglight Cartridge for Java EE Installation and Configuration Guide Enabling a Cartridge .............................................................................................................................................. 21 Uninstalling a Cartridge.......................................................................................................................................... 22 Nexus Services ...................................................................................................................................................... 22 Installing the Instrumented Agent for Java EE................................................................................................................ 23 Silent Installation.................................................................................................................................................... 24 Uninstalling the Instrumented Agent for Java EE .................................................................................................. 26 Upgrading the Cartridge and the Instrumented Agent for Java EE ................................................................................ 26

Configuring the Cartridge for Java EE ............................................................................................................ 27 Configuring the Instrumented Agent for Java EE ........................................................................................................... 28 Configuring Connection Details ............................................................................................................................. 28 Configuration Lookup Sequence............................................................................................................................ 30 Configuring Logging Properties ............................................................................................................................. 32 Configuring the Foglight Management Server ................................................................................................................ 32 Configuring the Nexus ........................................................................................................................................... 33 Configuring Data Collection Options...................................................................................................................... 35 Filtering Topology Objects ..................................................................................................................................... 37 Configuring the Cartridge for Java EE in a Federated Environment............................................................................... 41 Editing the Federation Configuration File............................................................................................................... 41 Configuring Advanced Settings ...................................................................................................................................... 43

Configuring Application Servers for the Cartridge for Java EE .................................................................. 45 Before You Begin............................................................................................................................................................ 46 About PerformaSure Home and User Permissions ........................................................................................................ 46 BEA WebLogic Server and WebLogic Express .............................................................................................................. 47 Configuring WebLogic Server or WebLogic Express Startup ................................................................................ 47 Configuring the WebLogic Server or WebLogic Express Startup Using the Node Manager ................................. 49 Configuring a WebLogic Server Running as a Windows Service .......................................................................... 51 Configuring the WebLogic Node Manager to run as a Windows Service .............................................................. 53 Deactivating the Instrumented Agent for Java EE in WebLogic ............................................................................ 54 JVM Versions and Metrics Collection for WebLogic 9.x and 10.0 ......................................................................... 54 IBM WebSphere Application Server .............................................................................................................................. 56 Configuring the IBM WebSphere Application Server 5.1 and 5.1 ND.................................................................... 56 Configuring IBM WebSphere Application Server 6.0, 6.0 ND, 6.1, and 6.1 ND..................................................... 64 Deactivating the Instrumented Agent for Java EE in WebSphere ......................................................................... 70

Table of Contents

5

Oracle® Application Server.............................................................................................................................................71 Configuring the Oracle Application Server 10g R2 (V10.1.2) and 10g R3 (V10.1.3) .............................................71 Deactivating the Instrumented Agent for Java EE in OracleAS ............................................................................75 JBoss Application Server ................................................................................................................................................76 Before You Begin ...................................................................................................................................................76 Enabling JTA Metrics for JBoss Application Server Version 4.2 ............................................................................76 Configuring the JBoss Application Server Versions 4.0 and 4.2 ............................................................................77 Deactivating the Instrumented Agent for Java EE in JBoss ...................................................................................79

Configuration FAQ and Troubleshooting ........................................................................................................81 Application Servers in General........................................................................................................................................81

Index....................................................................................................................................................................85

6

Foglight Cartridge for Java EE Installation and Configuration Guide

Introduction to this Guide This chapter provides information about what is contained in the Installation and Configuration Guide. It also provides information about the Foglight documentation suite and Quest Software. This chapter contains the following sections: About Foglight ...............................................................................................................................8 About this Guide............................................................................................................................8 Foglight Documentation Suite .......................................................................................................9 Text Conventions .........................................................................................................................10 About Quest Software, Inc........................................................................................................... 11

8

Foglight Cartridge for Java EE Installation and Configuration Guide

About Foglight Foglight is an application management solution that reduces or eliminates service disruptions to unify IT and the business. Unlike other solutions, it provides a correlated, 360 degree view of your applications from end user to database and from service levels to infrastructure—to source the root cause of every incident impacting your business and fix them quickly. Foglight correlates data from multiple perspectives into a single version of the truth to provide deep insight into the service relationships that exist between end users, the business and infrastructure components. Its unique adaptive technology rapidly adjusts to change for improved application performance and service levels, reduced operational cost and risk, and enhanced visibility for all stakeholders.

About this Guide This Installation and Configuration Guide provides installation and configuration instructions for the Cartridge for Java EE and the Instrumented Agent for Java EE. This guide is intended for any user who wants to install and configure the Foglight Cartridge for Java EE. The Installation and Configuration Guide is organized as follows: Chapter 1, Introducing the Cartridge for Java EE — Provides background information on the concepts and terms specific to the Cartridge for Java EE. Chapter 2, Installing the Cartridge and the Agent — Contains step-by-step procedures for installing the Cartridge for Java EE and the Instrumented Agent for Java EE. Chapter 3, Configuring the Cartridge for Java EE — Provides information on how to configure the Instrumented Agent on the monitored application server and the Cartridge for Java EE on the Foglight Management Server. Chapter 4, Configuring Application Servers for the Cartridge for Java EE — Covers instructions for configuring the supported application servers to work with the Cartridge for Java EE. Chapter 5, Configuration FAQ and Troubleshooting — Covers common questions and answers related to installation and configuration.

Introduction to this Guide Foglight Documentation Suite

9

Foglight Documentation Suite The Foglight documentation suite is made up of the core documentation set plus the documentation set for each Foglight cartridge that you deploy. Documentation is provided in a combination of online help, PDF, and HTML. • Online Help: You can open online help by selecting the Help tab in the action panel. • PDF: The Getting Started Guide, What’s New Guide, System Requirements and Platform Support Guide, Installation and Setup Guide set, Administration and Configuration Guide, Foglight User Guide, Command-Line Reference Guide, Transition Guide, Web Component Guide, and Web Component Tutorial, are provided as PDF files. In addition, the cartridges ship with PDF guides. The PDF guides are installed in the docs directory of your Foglight installation directory. Adobe® Reader® is required. • HTML: Release Notes are provided in HTML.

Core Documentation Set The core documentation set consists of the following: • Release Notes (HTML) • Getting Started Guide (PDF) • What’s New Guide (PDF) • System Requirements and Platform Support Guide (PDF) • Installation and Setup Guide set (all in PDF format): • Installation and Setup Guide — Installing on Windows with an Embedded MySQL Database • Installation and Setup Guide — Installing on Windows with an External MySQL Database • Installation and Setup Guide — Installing on Windows with an External Oracle Database • Installation and Setup Guide — Installing on a UNIX System with an Embedded MySQL Database • Installation and Setup Guide — Installing on a UNIX System with an External MySQL Database

10

Foglight Cartridge for Java EE Installation and Configuration Guide • Installation and Setup Guide — Installing on a UNIX System with an External Oracle Database • Administration and Configuration Guide (PDF and online help) • Foglight User Guide (PDF and online help) • Command-Line Reference Guide (PDF and online help) • Transition Guide (PDF) • Web Component Guide (PDF and online help) • Web Component Tutorial (PDF and online help) • Web Component Reference (online help)

Cartridge Documentation Sets When you deploy a cartridge, the documentation set for the cartridge is installed. The online help for the cartridge is integrated automatically with the core Foglight help. When you open the help, the name of the cartridge is displayed in a top level entry within the table of contents. Some cartridges include additional PDF guides, which may be one or more of the following: a Getting Started Guide, a Reference Guide, an Installation Guide, or the online help as a User Guide.

Feedback on the Documentation We are interested in receiving feedback from you about our documentation. For example, did you notice any errors in the documentation? Were any features undocumented? Do you have any suggestions on how we can improve the documentation? All comments are welcome. Please submit your feedback to the following email address: [email protected] Please do not submit Technical Support related issues to this email address.

Text Conventions This section outlines an approach for using this guide, reviews the text conventions that are used, and summarizes the rest of the documentation set.

Introduction to this Guide About Quest Software, Inc.

11

The following table summarizes how text styles are used in this guide: Convention

Description

Code

Monospace text represents code, code objects, and commandline input. This includes: • Java language source code and examples of file contents • Classes, objects, methods, properties, constants, and events • HTML documents, tags, and attributes

Variables

Monospace-plus-italic text represents variable code or command-line objects that are replaced by an actual value or parameter.

Interface

Bold text is used for interface options that you select (such as menu items) as well as keyboard commands.

Files, components, and documents

Italic text is used to highlight the following items: • Pathnames, file names, and programs • The names of other documents referenced in this guide

About Quest Software, Inc. Quest Software, Inc. delivers innovative products that help organizations get more performance and productivity from their applications, databases, and Windows infrastructure. Through a deep expertise in IT operations and a continued focus on what works best, Quest helps more than 18,000 customers worldwide meet higher expectations for enterprise IT. Quest Software can be found in offices around the globe and at www.quest.com.

12

Foglight Cartridge for Java EE Installation and Configuration Guide

Contacting Quest Software Email

[email protected]

Mail

Quest Software, Inc. World Headquarters 5 Polaris Way Aliso Viejo, CA 92656 USA

Web site

www.quest.com

Refer to our web site for regional and international office information.

Contacting Quest Support Quest Support is available to customers who have a trial version of a Quest product or who have purchased a commercial version and have a valid maintenance contract. Quest Support provides around the clock coverage with SupportLink, our web self-service. Visit SupportLink at: http://support.quest.com. From SupportLink, you can do the following: • Quickly find thousands of solutions (Knowledgebase articles/documents). • Download patches and upgrades. • Seek help from a Support engineer. • Log and update your case, and check its status. View the Global Support Guide for a detailed explanation of support programs, online services, contact information, and policy and procedures. The guide is available at: http://support.quest.com/pdfs/Global Support Guide.pdf.

1 Introducing the Cartridge for Java EE The Cartridge for Java EE monitors your application servers and reports on applications, servers, and groups of servers such as domains, clusters, and cells. It fires alarms when any component falls outside of its predefined conditions. This chapter introduces concepts and terms specific to the Cartridge for Java EE and provides an overview of the environment. This chapter contains the following sections: Overview......................................................................................................................................14 Key Concepts and Terms ............................................................................................................14 Cartridge for Java EE Environment .............................................................................................15 What Does the Cartridge for Java EE Do?..................................................................................16 Key Components of the Cartridge for Java EE............................................................................17

14

Foglight Cartridge for Java EE Installation and Configuration Guide

Overview Many Java™ EE system developers and production specialists need a Java EE analysis tool because their application is not meeting specific performance requirements. The Cartridge for Java EE is designed to help you diagnose and solve performance issues in pre-production and production environments.

Key Concepts and Terms This section provides a short list of terms used to describe concepts and components specific to the Cartridge for Java EE.

Term

Definition

Instrumented Agent for Java EE

The software that instruments the platform or the application server. These software sensors collect low-level events, perform some preliminary processing, and send data to the Nexus over a TCP/IP connection.

Nexus

The central data-organizing component of the Cartridge for Java EE. Agents connect through TCP/IP to the Nexus to report their data. The Nexus filters, organizes, and aggregates the data before Foglight stores it. The data then appears in Foglight.

service request

Quest Software’s Tag and Follow® technology defines a service request as anything that enters the agent-instrumented system, like a HTTP-based request, an RMI call, a JMS call, a direct method call, or a defined interface. This gives you the ability to track any request as it progresses through the various containers in your distributed application.

Tag and Follow

Quest Software’s Tag and Follow technology instruments the Java EE environment so that service requests can be tracked from inception to completion.

Introducing the Cartridge for Java EE Cartridge for Java EE Environment

15

Cartridge for Java EE Environment Large business applications are usually spread across distributed systems. Such systems may consist of a hardware or software load-balancer front end that forwards requests to a Web tier consisting of one or more HTTP servers. If the request is for a servlet or a JSP, it is processed in the application server’s servlet container. The servlets and JSPs will likely call EJBs (collectively called the middle tier), which in turn retrieve data from a back-end database. In many cases the application servers are clustered, which means that there are many possible execution paths through the system. Image 1

As you drill down into the operation of your system, you are likely to require accurate information about many aspects of system performance, such as: • Service request times: the time that requests spend in various containers. The Cartridge for Java EE can track a service request through a distributed application. This helps you focus on the parts of the application that contribute most to performance loss from the user’s perspective.

16

Foglight Cartridge for Java EE Installation and Configuration Guide • Java Virtual Machine (JVM) metrics: heap and garbage collection information. • Application server metrics: among many others, these include: • Servlet/JSP metrics: response times, number of servlet/JSP instances • RMI invocations • EJB metrics • JDBC metrics • JMS bytes transferred The Cartridge for Java EE measures all the quantities listed above and allows you to make sense out of the collected data. This helps you to isolate the parts of your application that are contributing to overly-long processing times.

Service Requests The Cartridge for Java EE instruments application servers. Service requests usually arrive via HTTP, RMI, or JMS calls as the starting points. These requests initiate a chain of events, probably invoking numerous EJB methods and database calls before returning a result. The Cartridge for Java EE defines the entire related chain of events as a service request. Because many end-users may be sending the same, or very similar, requests to your application almost simultaneously, the Cartridge for Java EE reports aggregated information for each request type or single trace. The Cartridge for Java EE breaks request timing down by tier for actual end-user request types, allowing you to isolate problems quickly with the Java EE Requests dashboard which shows logical execution paths and timings.

What Does the Cartridge for Java EE Do? The Cartridge for Java EE provides 24x7 monitoring of your application servers to help you detect and resolve performance problems in your application server infrastructure and the applications running in that infrastructure. It analyzes the data that it receives and refines it to useful information you need to determine the overall health and performance of your application server instances. The Cartridge for Java EE also: • includes an Instrumented Agent for Java EE that collects performance data on the application server and deployed applications, including JVM usage, JMS, EJB, and JDBC metrics.

Introducing the Cartridge for Java EE Key Components of the Cartridge for Java EE

17

• monitors the state of each cluster and standalone managed server in WebLogic domains, WebSphere cells, OracleAS cluster topologies, and JBoss partitions. • communicates this information to you by displaying a hierarchical set of views that provide increasing levels of detail about the area in which you are interested. Information is stored in the Foglight Management Server database. • includes a number of predefined rules to notify application and system administrators of performance problems for diagnosis and resolution.

Key Components of the Cartridge for Java EE There are a number of key components that comprise the Cartridge for Java EE: • Instrumented Agent for Java EE • Nexus • Foglight

Instrumented Agent for Java EE Instrumented Agents for Java EE are the performance data collection objects in the Cartridge for Java EE architecture. They attach themselves to application servers and collect metrics from the Java virtual machines and servers. These metrics are passed to the Nexus. At the application level, Service Request Agents use byte-code instrumentation to measure method-level performance information. At the server level, agents monitor the Cartridge for Java EE application server metrics through vendor-provided interfaces. At the JVM level, agents monitor various JVM metrics; at the operating system level, they monitor platform-level metrics. Some Instrumented Agents run inside the application’s JVM, others run as separate processes in their own JVM. When the agent monitors data for an application running inside a JVM, the agent runs inside that same JVM. When the application is native, the agent runs as a separate process. There is only one agent per JVM and one agent per monitored application server on a given machine. Specifically, if there is more than one monitored application server running on a given machine, there is an agent attached to each of those application servers, and typically two or more agents running on that machine. Agents are instantiated from command files or shell scripts, usually as part of launching the server.

18

Foglight Cartridge for Java EE Installation and Configuration Guide Since agents perform various monitoring tasks, they need the close cooperation of the underlying JVM and Java Runtime Environment (JRE). When you install an agent on a target machine using the installer, the JVM/JRE needed by that agent is installed as well.

Nexus The Nexus is essential to the data management facilities of the Cartridge for Java EE. Its major functions are to collect information from all communicating agents and process this information. The Nexus reconstructs the full application-level execution path by organizing the collected data into service requests using Tag and Follow technology. It receives data collected from the agents, then combines and converts agent-based event information into a cohesive information set that can be queried and presented graphically by Foglight. The Nexus’ central analytical engine correlates data sent from multiple agents, restores and preserves the temporal order of events across all servers, and provides other basic analysis of the data.

Foglight Foglight allows you to view performance data graphically, start and stop the Instrumented Agent for Java EE, and send other types of requests to the Nexus. A number of Cartridge for Java EE dashboards and portlets are available with Foglight, each providing insight into your system’s performance. They include: • Services dashboard • Java EE Requests dashboard • Java EE Systems dashboard • Java EE Systems portlet • Java EE Applications portlet For further information, refer to the appropriate sections in the Foglight Managing Java Enterprise Systems User Guide.

2 Installing the Cartridge and the Agent This chapter contains the following sections: Overview......................................................................................................................................20 System Requirements .................................................................................................................20 Installing the Cartridge for Java EE .............................................................................................20 Installing the Instrumented Agent for Java EE ............................................................................23 Upgrading the Cartridge and the Instrumented Agent for Java EE .............................................26

20

Foglight Cartridge for Java EE Installation and Configuration Guide

Overview The Cartridge for Java EE includes a set of standard dashboards as well as a number of rules that notify application and system administrators about performance problems. These dashboards display data that is stored in the Foglight Management Server. The Cartridge for Java EE is shipped with an Instrumented Agent, which monitors entire groups of servers. Refer to the following sections for information on installing Instrumented Agents: • “Installing the Cartridge for Java EE” on page 20 • “Installing the Instrumented Agent for Java EE” on page 23

System Requirements To install the Cartridge for Java EE you need to ensure that you have the correct environment. Before installing, refer to the Requirements and Guidelines section in the Foglight Installation and Setup Guide for the database and platform at your environment. Note

Additional hard drive disk space is required to install the cartridge file.

Installing the Cartridge for Java EE Installation is the first step in adding a cartridge to the Foglight Management Server. A cartridge file has the extension .car. Installing the .car file causes the Foglight Management Server to be aware of all cartridges in the .car file. You can install a .car file located in a local directory on the machine hosting the Foglight Management Server or you can upload a .car file from your local machine to the Foglight Management Server using an Administration dashboard. A cartridge must also be enabled before it can be used by the Foglight Management Server. You can enable a cartridge upon installation, or you can enable it after installation. See Enabling Cartridges in the Foglight Administration and Configuration Guide for additional instructions on cartridge configuration.

Installing the Cartridge and the Agent Installing the Cartridge for Java EE

21

To install a cartridge: 1 Open the Foglight Home page (by default at http://:8080/console). 2 Hover over the vertical bar containing the arrow icon on the far left of the page.

The navigation panel slides open. 3 Select Dashboards > Administration > Cartridges > Cartridge Inventory.

The Cartridge Inventory dashboard appears. 4 In the Install Cartridge area, type the path to the .car file for the cartridge you

want to install. The format of the Foglight is Java_EE-.car • Type the path in the File on Local Machine field if you want to upload a .car file from your local machine to the Foglight Management Server. Alternatively, you can click the Browse button to navigate to a .car file on your local machine using a file chooser. Click OK in the file chooser when you have selected the .car file you want to install. • Type the path in the File on Server field if you want to install a .car file located in a local directory on the machine hosting the Foglight Management Server. 5 The check box Enable on install is selected by default.

• If you would like the cartridge to be enabled when it is installed, leave this check box selected. • If you would like to enable the cartridge after installation, clear this check box. 6 Click Install Cartridge.

If the installation is successful, the message Cartridge has been installed successfully appears in the Install Cartridge area and the cartridge is listed in the Cartridge Inventory. If Enable on install was not selected (see step 5 above), a symbol ( ) appears in the row for that cartridge in the Cartridge Inventory. This indicates that the cartridge needs to be enabled manually.

Enabling a Cartridge Enabling a cartridge completes the process of adding it to the Foglight Management Server by making the cartridge’s components available for use.

22

Foglight Cartridge for Java EE Installation and Configuration Guide To enable a cartridge: 1 Navigate to the Cartridge Inventory dashboard as described in Installing the

Cartridge for Java EE. 2 In the table in the Cartridge Inventory area, select the check box that corresponds

with the cartridge that you want to enable. 3 Click Enable Selected.

If the cartridge is enabled successfully, a success message appears in the Cartridge Inventory area and the Activated icon (

) appears in the row for that cartridge.

Uninstalling a Cartridge Uninstalling a cartridge removes it from the Foglight Management Server by making the cartridge’s components unavailable for use. To uninstall a cartridge: 1 Navigate to the Cartridge Inventory dashboard as described in Installing the

Cartridge for Java EE. 2 In the table in the Cartridge Inventory area, select the check box that corresponds

with the cartridge that you want to uninstall. 3 Click Uninstall Selected. 4 When prompted, click OK.

If the cartridge is uninstalled successfully, a success message appears in the Cartridge Inventory area. The cartridge is removed from the Cartridge Inventory table.

Nexus Services The Foglight uses PerformaSure technology including portions of the Nexus (data collection server) which are loaded as JBoss® services. As this service is part of the cartridge, disabling and enabling the cartridge causes the Nexus services to be stopped and restarted.

Installing the Cartridge and the Agent Installing the Instrumented Agent for Java EE

23

Installing the Instrumented Agent for Java EE You need to install the Instrumented Agent for Java EE on the servers hosting the application that you want the Foglight Management Server to monitor. You can install the agent from either the Foglight Administration dashboard or in silent mode (described in “Silent Installation” on page 24). Note

If you are using a browser that is running on the UNIX/Linux operating system, you will be unable to install the downloaded Agent for Java EE using the procedure described below, because the file does not include the execute permission. Instead, use the UNIX/Linux chmod command to set the execute permission on the file, and then run the installer.

Agents should be installed using an account that has administrator privileges. For more information see the Foglight Administration and Configuration Guide. To install the Instrumented Agent for Java EE: 1 Open the Foglight Home page (by default at http://:8080/console/admin/

main.action). 2 Hover over the vertical bar containing the arrow icon on the far left of any

Foglight page. The left panel slides open. 3 Select Dashboards > Administration > Cartridges > Components for

Download. The Components for Download dashboard appears. Note

Disregard the message “Not all components are meant to be downloaded by endusers.” This message does not apply to Foglight end-users.

4 Click the Instrumented Agent for Java EE that you want to install. Note

To determine which Instrumented Agent to install, refer to the columns, Cartridge Name, Component Name, OS, and Architecture for details.

The File Download dialog box appears. 5 Click Open to continue downloading the self-extracting file. 6 Select a directory to where the files will be extracted. 7 Click Extract to extract all of the files to a folder.

The decompressed files are now located in the directory you chose in step 5.

24

Foglight Cartridge for Java EE Installation and Configuration Guide For information about configuring Instrumented Agents, see “Configuring the Cartridge for Java EE” on page 27.

Silent Installation The default mode for the Instrumented Agent for Java EE installer is the graphical user interface mode. There are also other installation modes that are supported for the Instrumented Agent for Java EE: one is using the command line and the other is silent mode. These additional modes can be helpful on Unix systems that do not include a graphics display. To execute in command-line mode, type the following command: javaee_agent-. -i console

To execute in silent mode, type the following command: javaee_agent-. -i silent -DUSER_INSTALL_DIR= -DUSER_SHORTCUTS= -DAGENT_HOST= -DAGENT_PORT= Note

If any file or path contains spaces, you need to enclose it in quotation marks regardless of the platform (Windows or Unix/Linux).

For example: javaee_agent-windows-ia32-5.2.3.exe -i silent -DUSER_INSTALL_DIR=”C:\Quest_Software\Quest_Agents\Java_EE-5_2_3” -DUSER_SHORTCUTS=”C:\Documents and Settings\All Users\Start Menu\Programs\Quest Software\Java EE 5.2.3” -DAGENT_HOST=localhost -DAGENT_PORT=41705

Refer to the table below to learn more about the installer parameters. Note

Unlike UNIX, there is no console output when running a silent installation on a Windows system.

Installing the Cartridge and the Agent Installing the Instrumented Agent for Java EE

25

Property

Description

Default

USER_INSTALL_DIR

The Java EE agent installation directory

Windows: C:\Quest_Software\Quest_Ag ents\Java_EE-5_2_3 Unix: $UNIX_USER_HOME/ Quest_Software/ Quest_Agents/Java_EE5_2_3

USER_SHORTCUTS

Sets the shortcut location

Windows: C:\Documents and Settings\All Users\Start Menu\Programs\Quest Software\Java EE 5.2.3 Unix/Linux: $UNIX_USER_HOME/ Quest_Software/ Quest_Agents/Java_EE5_2_3/Shortcuts

AGENT_HOST

User-defined host name for Foglight Management Server

localhost

AGENT_PORT

User-defined port for Foglight Management Server

41705

Alternatively, you can create a properties file to feed in the above installer parameters. To use a properties file, type the following command: javaee_agent-. -f property_file

26

Foglight Cartridge for Java EE Installation and Configuration Guide If a parameter is not specified, the value that is shown during installation in GUI mode is used as the default.

Uninstalling the Instrumented Agent for Java EE To uninstall the Instrumented Agent for Java EE, use the uninstaller for your platform for each instance of the Instrumented Agent for Java EE. The uninstaller can be found in the directory \UninstallerData. For example, to uninstall the 5.1 Instrumented Agent for Java EE on Windows, run Uninstall_Java_EE-5_1.exe. The version number in the file name changes according to the release for both Windows (.exe) and UNIX (.bin), i.e, Uninstall_Java_EE-.exe. To remove configuration changes made to the application server startup routine, refer to the applicable procedure: • “Deactivating the Instrumented Agent for Java EE in WebLogic” on page 54 • “Deactivating the Instrumented Agent for Java EE in WebSphere” on page 70 • “Deactivating the Instrumented Agent for Java EE in OracleAS” on page 75

Upgrading the Cartridge and the Instrumented Agent for Java EE For instructions on how to upgrade to the latest version of the Cartridge for Java EE and the Instrumented Agent for Java EE, refer to the Foglight Cartridge Upgrade Field Guide which can be found on SupportLink.

3 Configuring the Cartridge for Java EE There are two types of configuration available in the Cartridge for Java EE: Instrumented Agent configuration and Foglight Management Server configuration. • Instrumented Agent configuration is done on the monitored host, that is, the location where you installed the agent to monitor an application server. • Foglight Management Server configuration is done in the Foglight Administration dashboards. Configuration of the Cartridge for Java EE may also be required if you are using the cartridge in a federated environment. This chapter contains the following sections: Configuring the Instrumented Agent for Java EE ........................................................................28 Configuring the Foglight Management Server.............................................................................32 Configuring the Cartridge for Java EE in a Federated Environment ...........................................41 Configuring Advanced Settings ...................................................................................................43

28

Foglight Cartridge for Java EE Installation and Configuration Guide

Configuring the Instrumented Agent for Java EE Agents can be configured using the agent.config file, which is found on each monitored application server. Normally, all the installed agents share a common agent.config file. Edit this file if you need to: • change the default values for settings such as Nexus Host and Nexus Port (which set the location of the Nexus) • modify the timeout intervals • change the retry intervals for connecting to the Nexus • create a custom name for the agent (if you do not want to use the default name)

Configuring Connection Details Note

When you install the Instrumented Agent for Java EE, you are prompted for the Nexus Host and Port. If you need to change the host and port after installation, use the information provided below.

The Instrumented Agent for Java EE collects service request metrics and other metrics, such as application and application server metrics, from monitored application servers. If multiple instances of an application server exist on a single machine, there are multiple Instrumented Agents for Java EE, one for each application server. Once the Instrumented Agent collects the data, it sends it to the Nexus services running within the Foglight Management Server. The NexusConnections variable in the agent.config file indicates to the agent which Nexus Host and Port to connect. For example: NexusConnections = ( { "Host": "localhost", "Port": 41705 }, # { "Host": "nexus-2", "Port": 41705 }, # { "Host": "nexus-3", "Port": 41705 }, ) To modify connection details: 1 From the monitored host, change the host name to the new name or IP address of

the server hosting the Foglight Management Server.

Configuring the Cartridge for Java EE Configuring the Instrumented Agent for Java EE

29

2 Change the port number to the new Foglight Management Server port number. 3 Click Save to save your updates. 4 Restart the agent and the monitored application server.

For more information, see the comments in the agent.config file. Using Another agent.config File While it is not normally needed, you can specify that an Instrumented Agent use a different agent.config file at runtime by adding the following to the arguments in the Administration Console of each application server: -Dquest.agent.config= where is the path to the alternate configuration file You might want to use more than one agent.config file if: • you have more than one Foglight Management Server and you want to change the one to which the Instrumented Agent connects. • you have more than one application server on a single machine and you want each agent to have separate properties, such as its own name.

Attempting to Restore the Agent-Foglight Connection If the connection between an agent and the Foglight Management Server is broken or if the agent fails on its initial attempt to connect to Foglight, the agent tries to reconnect at regular intervals. The default setting is 20000 milliseconds (20 seconds). You can increase or decrease this interval. You can also turn off automatic reconnection attempts by setting the interval to zero. Property

NexusRetryInterval

Example usage

# Attempt to reconnect every 10 seconds NexusRetryInterval = 10000;

Attempting to Reconnect After an Authentication Failure If the agent fails on its initial attempt to connect to the Foglight Management Server due to an authentication failure (such as a build number mismatch or expired licensing), it tries to connect at regular intervals. The default setting is 120000 milliseconds (120

30

Foglight Cartridge for Java EE Installation and Configuration Guide seconds or two minutes). You can increase or decrease this interval. You can also turn off automatic reconnection attempts by setting the interval to zero. Property

NexusAuthFailureRetryInterval

Example usage

# Attempt to reconnect every two minutes NexusAuthFailureRetryInterval = 120000;

Setting the Authentication Timeout When an agent attempts to connect to the Foglight Management Server, by default it will wait up to 30 seconds for an authentication response from Foglight before dropping the connection. You can change the length of time that the agent waits for authentication. Property

AuthenticateTimeout

Example usage

# Wait up to one minute for authentication AuthenticateTimeout = 60000;

Specifying An Agent Name You can specify a unique agent name. By default, the agent name is constructed automatically from the host or server name. In most cases you do not need to change it. Property

AgentName

Example usage

# Change the agent name AgentName = "Some Agent Name";

Configuration Lookup Sequence The Cartridge for Java EE has a four-stage configuration lookup sequence that provides the ability to locally override agent configurations and allows the Instrumented Agent for Java EE to look for configuration information in several locations, including a default location. The lookup sequence is as follows: 1 Override: The Instrumented Agent for Java EE looks locally in

/config/agent-override/.

Configuring the Cartridge for Java EE Configuring the Instrumented Agent for Java EE

31

2 Global: If the Instrumented Agent for Java EE is connected to Foglight, it asks

the Nexus to send the agent/ file and waits for a reply. The Cartridge for Java EE maps this (under Administration > Agents > Agent Properties > JavaEE-Cartridge > Shareables) to . The agent saves the result locally in /state/ /config-cache/. 3 If the Nexus fails to provide the requested configuration file, or if the

Instrumented Agent for Java EE fails to connect to the Nexus at agent startup for those files in the agent/type or agent/instrumentation paths, then the following sequence occurs: a Cached: The Instrumented Agent for Java EE looks locally in

/state//config-cache/agent-configfile>. b Default: The Instrumented Agent for Java EE looks locally in

/config/agent/. 4 Each time the Instrumented Agent for Java EE re-establishes communication with

the Nexus, or establishes communication after initially loading locally cached files, the Global lookup sequence described in step 2 is performed again, followed by the lookup sequence described in step 3, if necessary. Some files will have no effect after being loaded the first time, regardless of where the file was loaded from. These files include: • instrumentation.config • most files in the type path The Instrumented Agent for Java EE will log a WARN message if any such files (in use by the Instrumented Agent) are found to be different on a subsequent reload. Note

In the steps described above, indicates a relative path portion as well as a file name, for example, collector/jvm-generic.config or type/system.config. The variable replaces the path-separator character with an underscore which creates a longer file name with no relative path portion, for example, agent_collector_jvm-generic.config or agent_type_system.config.

If the Instrumented Agent for Java EE does not find anything after performing all the steps in the lookup sequence, the Cartridge for Java EE will log an ERROR message (which is written to the log target that you specified) and the agent may be shut down.

32

Foglight Cartridge for Java EE Installation and Configuration Guide See “Configuring Logging Properties” on page 32 for more information about configuring log targets and setting the log level. Important If there are multiple files in the locations described above, only the first one in the lookup order will be used; multiple files will not be merged. If an overriding configuration file (for example, a file in /config/agent-override or on the Nexus machine) needs to be based on the default configuration file, the contents of the default file must be copied to the overriding configuration file.

Caution

The /state directory does not contain any user-editable files. Do not edit any of the files in the /state directory or in any of its subdirectories.

Configuring Logging Properties The logs that the Instrumented Agent for Java EE produces can be configured using the file /config/log.config, (where JAVA_EE_HOME identifies the installation directory of the Instrumented Agent for Java EE on the monitored host). For example, you can use log.config to set: • a locale setting for changing the language in which log messages are written • log targets, for forwarding log messages to different outputs • the log level (ALL, DEBUG, VERBOSE, INFO, WARN, ERROR, FATAL, and OFF) for each log target • the directory in which log files are created (if you would like them to be created in a location other than the default directory, /logs) For more information, see the comments in log.config.

Configuring the Foglight Management Server You can configure how the Foglight Management Server interacts with the Cartridge for Java EE by modifying the nexus.config or recording.config files.

Configuring the Cartridge for Java EE Configuring the Foglight Management Server

33

Configuring the Nexus When you installed the Cartridge for Java EE, you specified some options, including the host and port that Foglight should use to listen for requests from agents. This information is saved in nexus.config. Edit this file if you need to: • configure connection information • change runtime parameters for the Nexus such as timeout settings

Updating Where Foglight Listens for Agent Connections By default, Foglight listens for connections on all available IP addresses. You can specify that Foglight listens on a single IP address. For example, if you have multiple network cards on the Foglight machine, you may only want to allow connections to Foglight through one of them. Foglight listens on port 41705. If you are using this port number for some other purpose, you can change the port that Foglight uses. Choose a port that is greater than 1024. To update the host or port: 1 Hover over the vertical bar containing the arrow icon on the far left of any

Foglight page. The navigation panel slides open. 2 Select Administration > Agents > Agent Properties. 3 From the Adapter menu, select JavaEE-Cartridge. The agent properties are

displayed in the Shareables list. 4 In the Shareables list, scroll down to select nexus.config. The contents of the file

are displayed in a text window. 5 In the text window, locate ListenHost. Review the comments about this

property and its sister property ListenPort. 6 Update the value of the ListenHost to the new IP address or use an asterisk to

listen on all IP addresses. If you are also updating the port, change the value of ListenPort to point to the new port. 7 Click Save.

Specifying the Agent Order Interval The Foglight Management Server regularly places orders with the agents to collect a certain number of service request samples. After Foglight places an order, the agents

34

Foglight Cartridge for Java EE Installation and Configuration Guide determine which service requests to sample. By default, the sampling interval is 12000 milliseconds. You can increase or decrease the sampling interval by changing the value of AgentOrderInterval. Property

AgentOrderInterval

Example usage

# Default value AgentOrderInterval = 12000;

Changing the Commit Timeout Setting A service request usually spends time in various containers. The part of the request that is processed in a specific container is called a request fragment. The Foglight Management Server starts a timer when a request enters a container and it waits for that part of the request to finish. The timer is reset whenever an agent reports data for the service request. By default, Foglight waits at most four seconds before committing a service request to the session data even if there is missing performance information from an external system. In your environment, some request fragments may be slow. You can increase the value of CommitTimeout if you are seeing a number of fragmented requests. If your application calls out to an uninstrumented server, however, such requests are always fragmented. The reason for this is that Foglight records the call from the instrumented component, but after that the correlation is lost because the information coming back from the uninstrumented server can’t be correlated with the call. The request completes, and Foglight notes the completion, but recognizes that part of the request tracking data is unavailable. In this case, increasing the value of CommitTimeout is not helpful, so it should not be changed. Tip

Foglight is more efficient when the value of CommitTimeout is only slightly greater than the longest service request being instrumented. If you expect to make repetitive tests on a relatively stable environment, it may be worthwhile to decrease the value of CommitTimeout until you begin to see fragmented requests and then specify 150% of this value as the timeout.

Property

CommitTimeout

Example usage

# Change the commit time to 15000 milliseconds CommitTimeout = 15000;

Configuring the Cartridge for Java EE Configuring the Foglight Management Server

35

Preventing a Firewall from Closing Foglight Connections Some firewalls and NAT devices automatically close connections after a certain period of inactivity. Uncommenting and setting MessageTrafficTimeout configures both endpoints of a Foglight connection to communicate periodically to ensure that the idle timeout is not exceeded. A connection is closed if it is idle for longer than this timeout. The value that you specify in milliseconds for MessageTrafficTimeout should be equivalent to the firewall’s timeout for idle connections. You can leave this setting commented out if there is no firewall between the Foglight Management Server and agents or if the firewall does not close idle connections. Property

MessageTrafficTimeout

Example usage

# Default value is 120011 milliseconds MessageTrafficTimeout = 120011;

Configuring Data Collection Options You can change how Foglight records data about Java EE Request applications by changing the default settings in recording.config. You can also change other default data collection options in agent_url_transformation.config. The recording.config and agent_url_transformation.config files can be found on the Agent Properties dashboard (Dashboards > Administration > Agents > Agent Properties).

Service Request Separation By default, Foglight groups all requests that have the same base URL into a single request and provides aggregate statistics for it. The Cartridge for Java EE allows you to use separators to separate requests with the same base URL into distinct request types based on the requests’ URL parameters and cookies. By allowing service request separation, the Cartridge for Java EE gives you the option of treating each parameter as if it were a separate request. Separation occurs if any of the parameters in a request match the request separation rule (SeparationRules) for that URL, meaning that a request may be separated based on more than one parameter. SeparationRules can be found in the recording.config file.

36

Foglight Cartridge for Java EE Installation and Configuration Guide Foglight first performs a separation, followed by: 1 URL Transformation 2 Service Request Filtering

URL Transformation It may be necessary to transform or remove parts of an incoming URL request so that different URLs can be combined. This configuration can be used to define transformations on the path part of a URL. Please note that because the defined URL transformations occur before request filtering, your request filtering criteria will need to be defined in terms of the transformed URLs. To make changes to URL transformation (URLPathTransform), edit the agent_url_transformation.config file. This configuration file is read each time a new session recording is started. Example To transform the following URLs: • /Live/control/musictype=newsthisweek&textid=1158104250058&DL=_DL • /Live/control/musictype=musicdances&textid=115216893517&DL=_ST into the following URLs • /Live/control/musictype=newsthisweek&DL=_DL • /Live/control/musictype=musicdance&DL=_ST Define the following URLPathTransform: URLPathTransform = { /\/Live\/control\/musictype=.*/ : { /&textid=[0-9]+/: "", }, }

Service Request Filtering Filtering can be configured to include some requests and exclude others. Regular expression pattern matching can be used to determine which requests are included and which are excluded. You can also match requests using literal strings.

Configuring the Cartridge for Java EE Configuring the Foglight Management Server

37

Many types of requests can safely be ignored once you have determined that they have no costly effects on performance. By default, the Cartridge for Java EE excludes requests for .gif, .jpg, .png, .js, and .ico files. Modify the FilteringRules defined in the recording.config file if you want to filter for these types of files. After you have measured the request times for certain objects and you are satisfied that there are no problems with them, you can use service request filtering to remove them from view.

Filtering Topology Objects You can filter the topology objects for which metrics are collected by modifying the agent_modelfilters.config file that can be found on the Agent Properties dashboard (Dashboards > Administration > Agents > Agent Properties). Filters are applied by the Instrumented Agent for Java EE that resides in each application server, and are set by creating rules that define the object to be filtered and the level of detail of the filter. Rules that apply to all application server types can be set up as well as rules that are specific to one or more monitored application servers. It is recommended that broad rules should appear first in the list, followed by more specific rules. Note

Unless otherwise specified, each rule filters the output of the previous rule as well as objects that were not matched by the previous rule.

Rules are set up using the following format: selector : filter where: selector is a name attribute for a topology object (for example, "servlet"). These attributes can be expressed as either a literal string value or as a regular expression pattern. The literal string or regular expression is compared against the value of the attribute. For further information on selector, refer to “Selector” on page 37. filter is a string that describes the action to be taken with topology objects that match the rule. The level of detail for metric collection can be provided in the filter. For further information, refer to “Filter” on page 38. Selector The literal string that is defined must match the attribute value exactly. If a regex pattern is used, it must match a substring of the attribute value.

38

Foglight Cartridge for Java EE Installation and Configuration Guide Valid name attributes include: • agent type • application • ejb • entityejb • jdbcDataSource • jmsDestination • messageDrivenEjb • server • servlet • statefulSessionEjb • statelessSessionEjb • webApp • webService The ejb attribute can be used as a wildcard to match all ejb attributes. Filter The actions that can be taken are: • include - Includes the objects matched by the rule. Objects matched by this rule are not affected by subsequent rules and are always collected. • exclude - excludes the objects matched by the rule. Objects matched by this rule are not affected by subsequent rules and are never collected. • top [per [+[...]]] - excludes all but the top objects ordered by . Optionally group by the value of one or more s so that top applies within each group. There is an implicit "per server" if none is specified. For example: top 5 invocationCount per webApp+application • min - Excludes objects whose value is less than . • max - Excludes objects whose value is greater than .

Configuring the Cartridge for Java EE Configuring the Foglight Management Server

39

The level of collection includes "full" and "config". Full collects configuration data as well as the runtime metric data (for example, the number of active sessions for the web application), while config collects only configuration data. The following table lists the valid metrics that are collected for each application server type (BEA WebLogic® , IBM WebSphere® , OracleAS, and JBoss).

Selector

Filter

Application Server Compatibility

entityEjb:

avgExcecutionTime

WebSphere

beansInUseCount

All

cacheAccess Count

WebLogic

poolAccessCount

WebLogic WebSphere

jdbcDataSource

poolWaiterCount

WebLogic

connectionsTotalCount

All

poolsize

WebSphere WebLogic

waitingCount

WebSphere WebLogic OracleAS (10.1.3)

jmsDestination

messagesReceivedCount

WebLogic WebSphere

40

Foglight Cartridge for Java EE Installation and Configuration Guide

Selector

Filter

Application Server Compatibility

messageDriven Ejb

avgExecutionTime

WebSphere

beansInUseCount

All

cacheAccess Count

WebLogic WebSphere

poolAccessCount

WebLogic WebSphere

servlet

statefulSession Ejb

poolWaiterCount

WebLogic

avgExecutionTime

All

invocationCount

All

avgExecutionTime

WebSphere

beansInUseCount

WebSphere OracleAS

statelessSession Ejb

cacheAccess Count

WebLogic

avgExecutionTime

WebSphere

beansInUseCount

All

poolAccessCount

WebLogic WebSphere

webApp

poolWaiterCount

WebLogic

activeSessonCount

All

Configuring the Cartridge for Java EE Configuring the Cartridge for Java EE in a Federated Environment

Selector

Filter

Application Server Compatibility

webService

avgExecutionTime

WebLogic

41

WebSphere invocationCount

WebLogic WebSphere

Refer to the agent_modelfilters.config file for examples.

Configuring the Cartridge for Java EE in a Federated Environment Federation enables the concept of using one Foglight Management Server (Federation Server) to operate, while using other Foglight Management Servers (Federated Servers) as the data source. For more detailed background information on Foglight Federation, please refer to the Foglight Federation Field Guide, which can be found on SupportLink. There are a number of steps that you should perform to set up the Cartridge for Java EE in a federated environment. These include: • setting up the Federation Server and the Federated Servers as described in the Foglight Installation and Setup Guides. • installing the Cartridge for Java EE on the Federation and Federated Servers. Follow the procedures provided in “Installing the Cartridge for Java EE” on page 20. • configuring the Cartridge for Java EE on the Federated Servers as described below.

Editing the Federation Configuration File Federation can be configured by modifying the settings in the federation.config file, which can be found on each Federated Server where the Cartridge for Java EE has been installed. Editing this file allows the Cartridge for Java EE instances to detect and communicate with each other. Note that the settings in the federation.config file on each

42

Foglight Cartridge for Java EE Installation and Configuration Guide Federated Server must be the same for the Cartridge for Java EE instance to participate in the federated environment. To edit the federation.config file: 1 On a Federated Server, hover over the vertical bar containing the arrow icon on

the far left of any Foglight page. The navigation panel slides open. 2 Select Dashboards > Administration > Agents > Agent Properties. 3 From the Namespace menu, select JavaEE-Cartridge.

The agent properties are displayed in the Shareables list. 4 In the Shareables list, scroll down to select federation.config.

The contents of the file are displayed in a text window. 5 In the text window, locate the DirectoryService setting. This setting enables

federation for the Cartridge for Java EE instance. By default, federation is disabled. To enable it, change the DirectoryService setting to Automatic. 6 If you enabled federation in step 5, you may need to review and possibly modify

the MulticastHost, Group, Port and TTL settings. MulticastHost - the default setting ("*") indicates that the Nexus listens on all available IP addresses for multicasts. If you want the Nexus to listen on a specific IP address or host, enter that IP address or hostname. This is useful if you have multiple network cards on a Federated Server and you want to allow federation on only one. MulticastGroup - must be a valid Internet Protocol version 4 (IPv4) multicast address. MulticastPort - this is the port that the Nexus uses for multicasting. MulticastTTL - this is the time-to-live setting for the multicast group. Each time a multicast network packet crosses a network boundary, the TTL is decreased by at least one. Once it reaches zero, the packet will no longer be forwarded. A value of zero means that only Cartridge for Java EE instances running on the same machine will find each other, while the default value of 1 means that only Cartridge for Java EE instances on the same subnet will find each other. 7 Click Save. 8 Repeat steps 1 — 7 for each Cartridge for Java EE instance on a Federated Server.

Configuring the Cartridge for Java EE Configuring Advanced Settings

43

Configuring Advanced Settings Instrumentation is an advanced setting that allows you to focus on a few crucial methods with the intent of localizing a potential trouble spot. You can instrument an agent in various ways by modifying the agent_instrumentation.config file. This file can be found on the Agent Properties dashboard (Dashboards > Administration > Agents > Agent Properties). Caution

Changing any of these settings requires advanced knowledge of Foglight and the Cartridge for Java EE. Please do not modify any of the settings if you are unfamiliar with either of these two products.

44

Foglight Cartridge for Java EE Installation and Configuration Guide

4 Configuring Application Servers for the Cartridge for Java EE This chapter contains the following sections: Before You Begin.........................................................................................................................46 About PerformaSure Home and User Permissions .....................................................................46 BEA WebLogic Server and WebLogic Express...........................................................................47 IBM WebSphere Application Server ............................................................................................56 Oracle® Application Server .........................................................................................................71 JBoss Application Server.............................................................................................................76

46

Foglight Cartridge for Java EE Installation and Configuration Guide

Before You Begin Depending on the size and complexity of your distributed application, you may need to follow these instructions on several different machines that may be running on different platforms. Before you configure your application server for the Instrumented Agent for Java EE, review the Installing the Foglight section in the Foglight Installation and Setup Guide that is appropriate for your environment.

About PerformaSure Home and User Permissions Because the Instrumented Agent for Java EE uses Quest PerformaSure technology, many of the scripts and utilities use an environment variable called PERFORMASURE_HOME. This variable is equivalent to the JAVA_EE_HOME variable. Both variables point to the following default location:

UNIX $HOME/Quest_Software/Quest_Agents/Java_EE-5_2_3

where Quest_Software/Quest_Agents/Java_EE-5_2_3 is the JAVA_EE_HOME variable

Windows C:\Program Files\Quest Software\Quest_Agents\Java_EE-5_2_3

where Quest Software/Quest_Agents/Java_EE-5_2_3 is the JAVA_EE_HOME variable

Agents require access to system-level resources to be able to collect data from the host machine(s) and system(s) on which they are installed. In addition, when configuring agents, the user running the application server(s) must have read/execute permissions on all directories under and including JAVA_EE_HOME and read/write/execute permissions on the following directories: JAVA_EE_HOME/bootstrap JAVA_EE_HOME/logs

Configuring Application Servers for the Cartridge for Java EE BEA WebLogic Server and WebLogic Express

47

JAVA_EE_HOME/state

where JAVA_EE_HOME identifies the installation directory of the Instrumented Agent for Java EE on the monitored host. Note

The recommended strategy on Solaris is to create a Quest user group and give it read/ write/execute access to the network devices.

BEA WebLogic Server and WebLogic Express This section contains instructions for integrating the Instrumented Agent for Java EE with a WebLogic Server versions 8.1, 9.0, 9.1, 9.2, and 10.0. You need to modify your WebLogic startup script by adding lines that set the variables required by the Instrumented Agent for Java EE. Topics discussed are: • “Configuring WebLogic Server or WebLogic Express Startup” on page 47 • “Configuring the WebLogic Server or WebLogic Express Startup Using the Node Manager” on page 49 • “Configuring a WebLogic Server Running as a Windows Service” on page 51 • “Configuring the WebLogic Node Manager to run as a Windows Service” on page 53

Configuring WebLogic Server or WebLogic Express Startup Use the following steps to configure a WebLogic Server. For variations, note the exception list presented at the end of the procedure. To configure WebLogic Server or WebLogic Express Startup: 1 Make a backup copy of your WebLogic Server startup script before proceeding

with the steps below.

48

Foglight Cartridge for Java EE Installation and Configuration Guide 2 Copy the following block of code to your WebLogic Server startup script. Insert

the block just before the WebLogic startup line. Tip

Ensure that all environment variables are set, including JAVA_HOME, WL_HOME, and

JAVA_OPTIONS, before you configure the server. Note

For WebLogic 9 and 10, modify the startup script in /bin.

Code Block for UNIX PERFORMASURE_HOME=***SET THIS*** PerformaSure Home Directory *** if [ -f "$PERFORMASURE_HOME/scripts/quest-java-env.sh" ] then QUEST_JAVA_ENV_OPTS=WEBLOGIC . "$PERFORMASURE_HOME/scripts/quest-java-env.sh" else echo PerformaSure Agent not enabled fi

Code Block for Windows set PERFORMASURE_HOME=***SET THIS*** PerformaSure Home Directory *** set QUEST_JAVA_ENV_OPTS=WEBLOGIC call "%PERFORMASURE_HOME:"=%\scripts\quest-java-env.cmd" || ( echo PerformaSure Agent not enabled ) 3 Set the PERFORMASURE_HOME variable to the Java_EE installation directory.

In UNIX quote this path if it contains spaces. 4 Before saving this new startup script, ensure your environment does not meet any

of the exceptions listed at the end of this section, then save the new script. 5 If it is not already running, start the Foglight Management Server, because the

instrumented WebLogic Server will attempt to connect to it when launched using the new script. 6 Start the WebLogic Server using the new script.

The Foglight Management Server console confirms that a WebLogic Server Agent has connected by displaying a message such as: INFO Accepted connection from Agent “ (WebLogic)”, (WebLogic ) on host:

Configuring Application Servers for the Cartridge for Java EE BEA WebLogic Server and WebLogic Express

49

In addition, the log file for the WebLogic Server Agent will contain an INFO message stating that it has connected to the Nexus. Note

By default, Agent log files are created in the logs subdirectory of the Foglight home directory on the Agent machine.

Exception List: 1 If you have spaces in the PERFORMASURE_HOME path and your WebLogic

application server is on UNIX, the following additional changes apply. If one or both of these conditions are not true, this exception does not apply. Edit the startup script and insert the following code in the Java command line before {SERVER_CLASS} or weblogic.Server: For WebLogic 9.x and 10.x "${PERFORMASURE_BOOTSTRAP}" "${PERFORMASURE_JAVA5}" ${PERFORMASURE_OPTIONS}

For WebLogic 8.x "${PERFORMASURE_BOOTSTRAP}" ${PERFORMASURE_OPTIONS} 2 For WebLogic 8.1, JRockit JDK, edit the startup script and insert the following

code on the Java command line before weblogic.Server: UNIX: ${PERFORMASURE_BOOTAGENT}

Windows: %PERFORMASURE_BOOTAGENT%

Configuring the WebLogic Server or WebLogic Express Startup Using the Node Manager If you use WebLogic Server’s Node Manager to control your system of servers remotely, you need to use a specially-configured version of the Node Manager so that Instrumented Agent for Java EE can optionally be started along with the WebLogic Servers. By default, all servers managed by the Node Manager are instrumented. If you would like to specify which servers are instrumented, edit the InstrumentedProcesses configuration option in the /config/agent/processlauncher.config file. For more information, see the comments in processlauncher.config for details.

50

Foglight Cartridge for Java EE Installation and Configuration Guide The appropriate command files must be run on every machine hosting WebLogic servers. For variations, note the exception list presented at the end of the steps. To configure the WebLogic Server or WebLogic Express Startup using the Node Manager: 1 Make a backup copy of your WebLogic Node Manager Server startup script

before proceeding with the steps below. 2 Copy the following block of code to your WebLogic Node Manager startup script.

Insert the block just before the WebLogic startup line. Tip

Ensure that all environment variables are set, including JAVA_HOME, WL_HOME, and

JAVA_OPTIONS, before you configure the server.

Code Block for UNIX PERFORMASURE_HOME=***SET THIS*** PerformaSure Home Directory *** if [ -f "$PERFORMASURE_HOME/scripts/quest-java-env.sh" ] then QUEST_JAVA_ENV_OPTS=WEBLOGIC:NODEAGENT . "$PERFORMASURE_HOME/scripts/quest-java-env.sh" else echo PerformaSure Agent not enabled fi

Code Block for Windows set PERFORMASURE_HOME=***SET THIS*** PerformaSure Home Directory *** set QUEST_JAVA_ENV_OPTS=WEBLOGIC:NODEAGENT call "%PERFORMASURE_HOME:"=%\scripts\quest-java-env.cmd" || ( echo PerformaSure Agent not enabled ) 3 Set the PERFORMASURE_HOME variable to the Java_EE installation directory.

In UNIX, quote this if it contains spaces. 4 Before saving this new startup script, ensure your environment does not meet any

of the exceptions listed at the end of this section, then save the new script. Tip

The quest-java-env script does not need to connect to the Foglight Management Server, but the Foglight Management Server needs to run so that the instrumented servers that are associated with the Node Manager can connect.

5 Start the WebLogic Node Manager using the new script. Managed servers started

by this Node Manager connects to the Foglight Management Server by displaying a message such as:

Configuring Application Servers for the Cartridge for Java EE BEA WebLogic Server and WebLogic Express

51

INFO Accepted connection from Agent “ (WebLogic)”, (WebLogic ) on host:

In addition, the log file for the WebLogic Server Agent will contain an INFO message stating that it has connected to the Nexus.

Exception List: 1 If you have spaces in the PERFORMASURE_HOME path and your WebLogic

application server is on UNIX, the following additional changes apply. If one or both of these conditions are not true, this exception does not apply. Edit the startup script and insert the following code in the Java command line before weblogic.nodemanager.NodeManager: For WebLogic 9.x and 10.x "${PERFORMASURE_BOOTSTRAP}" "${PERFORMASURE_JAVA5}" ${PERFORMASURE_OPTIONS}

For WebLogic 8.x "${PERFORMASURE_BOOTSTRAP}" ${PERFORMASURE_OPTIONS} 2 For WebLogic Node Managers running under a JRockit JDK, edit the startup

script and insert the following code on the Java command line before weblogic.NodeManager: UNIX: ${PERFORMASURE_BOOTAGENT}

Windows: %PERFORMASURE_BOOTAGENT%

Configuring a WebLogic Server Running as a Windows Service Use a copy of installSvc.cmd located in the \server\bin directory. To install a WebLogic Server as a Windows Service follow the instructions provided on the BEA website:

52

Foglight Cartridge for Java EE Installation and Configuration Guide For WebLogic 8.1 http://e-docs.bea.com/wls/docs81/adminguide/winservice.html Caution

Do not run the script.

To configure a WebLogic Server Running as a Window Service: 1 Make a backup copy of your InstallSvc.cmd startup script before proceeding with

the steps below. 2 Insert the block just before the command that sets the %CMDLINE% variable. Tip

Ensure that all environment variables are set, including JAVA_HOME, WL_HOME, and

JAVA_OPTIONS, before you configure the server.

set PERFORMASURE_HOME=***SET THIS*** PerformaSure Home Directory *** set QUEST_JAVA_ENV_OPTS=WEBLOGIC set START_AS_SERVICE=Yes set APPSERVER_CLASS=weblogic.Server call "%PERFORMASURE_HOME:"=%\scripts\quest-java-env.cmd" || ( echo PerformaSure Agent not enabled - installation of service aborted exit ) 3 Set the PERFORMASURE_HOME variable to the Java_EE installation directory. 4 For JRockit, in the command line that sets the %CMDLINE% variable, replace weblogic.Server with %PERFORMASURE_BOOTAGENT%. 5 Save the new script. 6 If it is not already running, start the Foglight Management Server.

The instrumented WebLogic server attempts to connect to it when the new service is started. 7 Use the script to have an instrumented version of the WebLogic server installed as

a Windows Service. 8 Start the Windows service.

The Foglight Management Server console confirms that a WebLogic Server Agent has connected by displaying a message such as: INFO Accepted connection from Agent “ (WebLogic)”, (WebLogic ) on host:

In addition, the log file for the WebLogic Server Agent contains an INFO message stating that it has connected to the Nexus.

Configuring Application Servers for the Cartridge for Java EE BEA WebLogic Server and WebLogic Express

53

Configuring the WebLogic Node Manager to run as a Windows Service Use a copy of the installNodeMgrSvc.cmd located in the \server\bin directory. To install a WebLogic Node Manager as a Windows Service, follow the instructions provided on the BEA website: For WebLogic 8.1 http://e-docs.bea.com/wls/docs81/adminguide/nodemgr.html Caution

Do not run the script.

To configure a WebLogic Node Manager to run as a Window Service: 1 Make a backup copy of your InstallNodeMgrSvc.cmd start up script before

proceeding with the steps below. 2 Insert the block just before the command that sets the %CMDLINE% variable. Tip

Ensure that all environment variables are set, including JAVA_HOME, WL_HOME, and

JAVA_OPTIONS, before you configure the server.

set PERFORMASURE_HOME=***SET THIS*** PerformaSure Home Directory *** set QUEST_JAVA_ENV_OPTS=WEBLOGIC:NODEAGENT set START_AS_SERVICE=Yes call "%PERFORMASURE_HOME:"=%\scripts\quest-java-env.cmd" || ( echo PerformaSure Agent not enabled - installation of service aborted exit ) 3 Set the PERFORMASURE_HOME variable to the Java_EE installation directory. 4 In the command line that sets the %CMDLINE% variable, insert the following before weblogic.NodeManager. %QUEST_JAVA_OPTIONS% 5 Save the new script. 6 If it is not already running, start the Foglight Management Server. Tip

The quest-java-env script does not need to connect to the Foglight Management Server, but the Foglight Management Server needs to run so that the instrumented servers that are associated with the Node Manager can connect.

7 Use the script to have an instrumented version of the WebLogic Node Manager

installed as a Windows Service.

54

Foglight Cartridge for Java EE Installation and Configuration Guide 8 Start the Windows service.

The Foglight Management Server console confirms that a WebLogic Server Agent has connected by displaying a message such as: INFO Accepted connection from Agent “ (WebLogic)”, (WebLogic ) on host:

In addition, the log file for the WebLogic Server Agent contains an INFO message stating that it has connected to the Nexus.

Deactivating the Instrumented Agent for Java EE in WebLogic The instructions below refer to WebLogic Server, but apply to both WebLogic Server and WebLogic Express. To restore your BEA WebLogic Server to its original state, either undo the code changes made during the integration process, or revert to the original backup script. • If you made a backup copy of the original script, use the original file to start your server or • revert the WebLogic Server to its original state by removing the additions to the Java command line described in the following procedures: • “Configuring WebLogic Server or WebLogic Express Startup” on page 47 • “Configuring the WebLogic Server or WebLogic Express Startup Using the Node Manager” on page 49 • “Configuring a WebLogic Server Running as a Windows Service” on page 51 • “Configuring the WebLogic Node Manager to run as a Windows Service” on page 53

JVM Versions and Metrics Collection for WebLogic 9.x and 10.0 For the JRockit JDK that ships with WebLogic 9.x and 10.0, the JMX implementation is problematic, which causes the JVM metrics collector to fall back to using APIs that do not provide as much information as is normally collected from a 1.5 JDK. To help determine the level of metrics that are being collected for your JVM version, refer to the following table.

Configuring Application Servers for the Cartridge for Java EE BEA WebLogic Server and WebLogic Express

Level of Metrics Collected

JVM Version

Limited

IBM 1.4 BEA JRockit 1.5.0_[05-07]

Many

Sun 1.4 BEA JRockit 1.4 BEA JRockit 1.5.0_[01-04]

Full

IBM 1.5 Sun 1.5 BEA JRockit 1.5.0_08 (R27.1.0) and above

55

56

Foglight Cartridge for Java EE Installation and Configuration Guide

IBM WebSphere Application Server Running WebSphere with security enabled This procedure applies to both WebSphere 5.1 and 6.x. If you want to run WebSphere while J2EE security or Global security is enabled, you need to make changes to WebSphere's server.policy file to prevent problems within the interaction between WebSphere and the Instrumented Agent for Java EE. Make the change listed below to the server.policy file, which is located in /properties or in /properties. Note

In the following code block, replace with the full path name for the Instrumented Agent for Java EE home directory.

Add the following block to the WebSphere server.policy file: grant codeBase "file:/lib/-" { permission java.security.AllPermission; };

Configuring the IBM WebSphere Application Server 5.1 and 5.1 ND This section contains instructions for integrating the Instrumented Agent for Java EE with WebSphere Server versions 5.1 and 5.1 ND. You need to modify the startup scripts for your WebSphere servers, NodeAgents, and Deployment Managers. Integration with the NodeAgent is necessary for instrumenting the servers that are started by that NodeAgent. Integration with the Deployment Manager is necessary to collect cell-wide configuration information and application server states. Topics discussed are: • “Running WebSphere with security enabled” on page 56 • “Configuring a WebSphere 5.1 environment” on page 57 • “Modifying the WebSphere 5.1 startup scripts” on page 58 • “Configuring a WebSphere 5.1 NodeAgent for the Instrumented Agent for Java EE” on page 59 • “Configuring a WebSphere 5.1 Deployment Manager for the Instrumented Agent for Java EE” on page 60

Configuring Application Servers for the Cartridge for Java EE IBM WebSphere Application Server

57

• “Configuring a WebSphere 5.1 Service for the Instrumented Agent for Java EE (Windows only)” on page 61 • “Starting your WebSphere 5.1 Servers with the Instrumented Agent for Java EE” on page 62 • “Collecting WebSphere 5.1 Performance Metrics (PMI)” on page 63 Caution

Ensure the Disable JIT checkbox is not selected on the Java Virtual Machine page in the WebSphere Administrative Console before integrating WebSphere with the Instrumented Agent for Java EE. Disabling the JIT slows the server's startup and operation.

Configuring a WebSphere 5.1 environment Use the following steps to configure a WebSphere 5.1 environment. To configure a WebSphere 5.1 environment: 1 Make a back-up copy of your original /bin/setupCmdLine

script (.bat or .sh). 2 Open the /bin/setupCmdLine script in a text editor and make

the following modifications: Windows: Add the following code to the end of the script: set PERFORMASURE_HOME=*** SET THIS WITHOUT USING QUOTES *** if defined QUEST_JAVA_ENV_OPTS ( call "%PERFORMASURE_HOME%\scripts\quest-java-env.cmd" if ERRORLEVEL 1 echo Quest agent NOT enabled )

58

Foglight Cartridge for Java EE Installation and Configuration Guide UNIX: Add the following code to the end of the script:

PERFORMASURE_HOME=*** SET THIS WITHOUT USING QUOTES**** export PERFORMASURE_HOME if [ -f "$PERFORMASURE_HOME/scripts/quest-java-env.sh" -a -n "$QUEST_JAVA_ENV_OPTS" ]; then . "$PERFORMASURE_HOME/scripts/quest-java-env.sh" if [ $? -gt 0 ]; then echo Quest agent NOT enabled; fi fi

3 Save your modified setupCmdLine script file.

Modifying the WebSphere 5.1 startup scripts Use the steps in this section to modify the WebSphere 5.1 startup scripts. To modify the WebSphere 5.1 startup scripts: 1 Make a back-up copy of your original /bin/startServer script

(.bat or .sh) 2 Open the original /bin/ startServer script in a text editor and

make the following modifications: Windows: Add the following code to startServer immediately before the call (%~dp0setupCmdLine.bat) to setupCmdLine: set ARGS=%* if NOT "%ARGS:-Dquest.agent.websphere=%" == "%ARGS%" ( set QUEST_JAVA_ENV_OPTS=WEBSPHERE ) if NOT "%ARGS:-Dquest.agent.websphere.nodeagent=%" == "%ARGS%" ( set QUEST_JAVA_ENV_OPTS=WEBSPHERE:NODEAGENT ) if NOT "%ARGS:-Dquest.agent.websphere.dmgr=%" == "%ARGS%" ( set QUEST_JAVA_ENV_OPTS=WEBSPHERE:DMGR )

Configuring Application Servers for the Cartridge for Java EE IBM WebSphere Application Server

59

UNIX: No changes are necessary to the original startServer.sh. 3 Save your modified startServer script file. 4 Create a new file named startServerFgl. Add the following content:

Windows: Add the following code to the new file startServerFgl.bat: @REM The following line contains one zero %~dp0startServer.bat %* -Dquest.agent.websphere

UNIX: Add the following code to the new file startServerFgl.sh: #!/bin/sh QUEST_JAVA_ENV_OPTS=WEBSPHERE export QUEST_JAVA_ENV_OPTS binDir=`dirname $0` $binDir/startServer.sh "$@" 5 Save your startServerFgl script file.

Use the new startServerFgl script to start a single server from the command line with the Quest monitoring agent enabled. Alternatively, revert to your original backup startServer script to start a single server without Quest monitoring.

Configuring a WebSphere 5.1 NodeAgent for the Instrumented Agent for Java EE Use the steps in this section to configure a WebSphere 5.1 NodeAgent for the Instrumented Agent for Java EE.

60

Foglight Cartridge for Java EE Installation and Configuration Guide To configure a WebSphere 5.1 NodeAgent: 1 Create a new file named startNodeFgl. Add the following content:

Windows: Add the following to the new file startNodeFgl.bat: setlocal set QUEST_JAVA_ENV_OPTS=WEBSPHERE:NODEAGENT @REM The following line contains one zero %~dp0startNode.bat %* endlocal

UNIX: Add the following to the new file startNodeFgl.sh: #!/bin/sh QUEST_JAVA_ENV_OPTS=WEBSPHERE:NODEAGENT export QUEST_JAVA_ENV_OPTS binDir=`dirname $0` $binDir/startNode.sh "$@" 2 Save your startNodeFgl script file.

Use the new startNodeFgl script to start a node from the command line with the Quest monitoring agent enabled. Alternatively, revert to your original startNode script to start a node without Quest monitoring.

Configuring a WebSphere 5.1 Deployment Manager for the Instrumented Agent for Java EE Use the steps in this section to configure a WebSphere 5.1 Deployment Manager for the Instrumented Agent for Java EE.

Configuring Application Servers for the Cartridge for Java EE IBM WebSphere Application Server

61

To configure a WebSphere 5.1 Deployment Manager: 1 Create a new file named startManagerFgl. Add the following content:

Windows: Add the following to the new file startManagerFgl.bat: setlocal set QUEST_JAVA_ENV_OPTS=WEBSPHERE:DMGR @REM The following line contains one zero %~dp0startManager.bat %* endlocal

UNIX: Add the following to the new file startManagerFgl.sh: #!/bin/sh QUEST_JAVA_ENV_OPTS=WEBSPHERE:DMGR export QUEST_JAVA_ENV_OPTS binDir=`dirname $0` $binDir/startManager.sh "$@" 2 Save your startManagerFgl script file.

Use the new startManagerFgl script to start the Deployment Manager from the command line with the Quest monitoring agent enabled. Alternatively, revert to your original startManager script to start the Deployment Manager without Quest monitoring.

Configuring a WebSphere 5.1 Service for the Instrumented Agent for Java EE (Windows only) WebSphere services for single servers, NodeAgents, and Deployment Managers all make use of the startServer.bat script in the \bin directory. Before creating a service which enables the Quest monitoring agent, you must perform the modifications to this file indicated under “Modifying the WebSphere 5.1 startup scripts” on page 58. Once the modifications are in place, proceed with installing the service. Your old Windows Service can be kept, but ensure that no more than one service for your WebSphere server, NodeAgent, or Deployment Manager has a startup type of automatic. All others should be set to manual. For complete details on using the WASService.exe tool, refer to the IBM documentation.

62

Foglight Cartridge for Java EE Installation and Configuration Guide Add the following argument to the -startArgs option: For servers: -Dquest.agent.websphere

For NodeAgents: -Dquest.agent.websphere.nodeagent

For Deployment Managers: -Dquest.agent.websphere.dmgr

Examples Note

A caret (^) character is required at the end of a line (other than the last) to correctly wrap the DOS command on multiple lines. There is a required space before the caret character to ensure proper spacing when copying and pasting the following code blocks.

• To create a Quest-agent-enabled server service, run the command: WASService.exe -add "BASE server1 with Agent" -serverName server1 -startArgs ^ "-Dquest.agent.websphere"

• To create a Quest-agent-enabled NodeAgent service, run the command: WASService.exe -add "ND nodeagent with Agent" -serverName nodeagent -startArgs ^ "-Dquest.agent.websphere.nodeagent"

• To create a Quest-agent-enabled Deployment Manager service, run the command: WASService.exe -add "ND manager with Agent" -serverName dmgr -startArgs ^ "-Dquest.agent.websphere.dmgr"

Starting your WebSphere 5.1 Servers with the Instrumented Agent for Java EE To start your WebSphere 5.1 servers with the Instrumented Agent for Java EE: 1 Configure WebSphere to provide PMI metrics for the Instrumented Agent for

Java EE collection. See “Collecting WebSphere 5.1 Performance Metrics (PMI)” on page 63 for details. 2 If it is not already running, start the Foglight Management Server. 3 If you are integrating the Instrumented Agent for Java EE with the Deployment

Manager:

Configuring Application Servers for the Cartridge for Java EE IBM WebSphere Application Server

63

a Stop the Deployment Manager. b Start the Deployment Manager using the modified startup script or Windows

Service. 4 If you are integrating the Instrumented Agent for Java EE with the NodeAgent: a Stop the NodeAgent. b Start the NodeAgent using the modified startup script or Windows Service.

An Instrumented Java EE Agent is launched for each instrumented server. When the agent connects to the Foglight Management Server, the Management Server console confirms that a WebSphere Application Server Agent has connected by displaying a message such as: INFO Agent licenses assigned; Type: websphere, Host: , CPUs: 1; CPU licenses in use: 1 INFO Accepted connection from Agent "server1 (WebSphere)" (WebSphere 5.1)on host host1.example.com

In addition, the log file for the WebSphere Application Server Agent will contain an INFO message stating that it has connected to the Nexus.

Collecting WebSphere 5.1 Performance Metrics (PMI) The PMI in the WebSphere Administration Console must be enabled to allow the Instrumented Agent for Java EE to collect WebSphere metrics. Deactivating Instrumented Agent for Java EE does not disable PMI. In order to disable PMI, you must make a note of your original PMI settings and restore them manually after you deactivate the Instrumented Agent for Java EE. When PMI is enabled, the Cartridge for Java EE will set the PMI instrumentation level to high by default when you start recording. When you stop recording, the Instrumented Agent for Java EE starts monitoring the PMI level at its pre-recording setting. Caution

It is not recommended that you change the PMI level while you are recording a session. If you do so, the Cartridge for Java EE may be unable to collect the necessary WebSphere metrics. Additionally, the Cartridge for Java EE will not restore the PMI level to its pre-recording setting if it is changed while the session recording is in progress.

You can define the PMI instrumentation level globally and for specific modules by editing the InstrumentationLevels configuration option in /config/ agent/collector/ websphere-5.config. When you start recording, the Cartridge for Java

64

Foglight Cartridge for Java EE Installation and Configuration Guide EE will use the PMI levels that are defined in this file. PMI levels must be one of the following: none, low, medium, high, or max. Example: /^beanModule/: "medium" /^connectionPoolModule/: "max"

Enabling PMI in the WebSphere Administrative Console 1 Open the WebSphere 5 Administrative Console: http://admin_host:admin_port/

admin (the default port is 9090). 2 Expand the Server node in the left pane of the console. Select Application

Servers. In the right pane, click the server that has been instrumented with Instrumented Agent for Java EE. 3 Select Performance Monitoring Service from the Configuration tab. 4 Verify that the Startup checkbox is checked. 5 Click Apply. A Message(s) header appears at the top of the right pane. 6 Click Save. The Save right pane appears. 7 Click Save on this screen to apply changes to the master configuration. Note

Changing the PMI settings affects all tools that query for WebSphere metrics.

Configuring IBM WebSphere Application Server 6.0, 6.0 ND, 6.1, and 6.1 ND This section contains instructions for integrating the Instrumented Agent for Java EE with WebSphere Server versions 6.0, 6.0 ND, 6.1, and 6.1 ND. You either need to create new windows services that start instrumented servers, NodeAgents, and Deployment Managers or modify the startup scripts. Integration with the NodeAgent is necessary for instrumenting the servers that are started by that NodeAgent. Integration with the Deployment Manager is necessary to collect cell-wide configuration information and application server states. Using the Cartridge for Java EE with your WebSphere 6.x servers requires three steps: 1 “Configuring the WebSphere 6.x environment” on page 65 2 “Creating a new WebSphere 6.x service” on page 66

Configuring Application Servers for the Cartridge for Java EE IBM WebSphere Application Server

65

3 “Modifying the WebSphere 6.x startup scripts” on page 68

Other topics include: • “Running WebSphere with security enabled” on page 56 • “Setting the PMI Levels on WebSphere 6.x” on page 69 Caution

Ensure the Disable JIT checkbox is not selected on the Java Virtual Machine page in the WebSphere Administrative Console before integrating WebSphere with the Instrumented Agent for Java EE. Disabling the JIT slows the server's startup and operation.

Caution

There is a problem with WebSphere Application Server 6.0.1 that causes applications to disappear from the list in the Administrative Console when they are targeted to both an application server and a web server. If you are running version 6.0.1, you should upgrade to at least version 6.0.1.2 to fix this problem. For details about this problem, refer to IBM support documentation.

Configuring the WebSphere 6.x environment WebSphere 6.x is configured to use profiles. Therefore, configuration with the Instrumented Agent for Java EE involves two steps. The first is to make modifications to the global setupCmdLine script. These changes only take effect if the environment variable PERFORMASURE_HOME has been set in your user profile setupCmdLine script. All other profiles will ignore the code in the global setupCmdLine script. 1 Make a back-up copy of your original /bin/setupCmdLine

script (.bat or .sh). 2 Open the /bin/setupCmdLine script in a text editor and make

the following modifications: Windows: a Add the following code to the end of the script: if %1==-Dquest.agent.websphere.server set QUEST_JAVA_ENV_OPTS=WEBSPHERE if %1==-Dquest.agent.websphere.nodeagent set QUEST_JAVA_ENV_OPTS=WEBSPHERE:NODEAGENT if %1==-Dquest.agent.websphere.dmgr set QUEST_JAVA_ENV_OPTS=WEBSPHERE:DMGR

66

Foglight Cartridge for Java EE Installation and Configuration Guide b Add the following code before the line “goto :EOF”:

if defined PERFORMASURE_HOME if defined QUEST_JAVA_ENV_OPTS ( call "%PERFORMASURE_HOME%\scripts\quest-java-env.cmd" || ( echo PerformaSure Agent NOT enabled ) )

UNIX: Add the following code to the end of the script: if [ -f "$PERFORMASURE_HOME/scripts/quest-java-env.sh" -a -n "$QUEST_JAVA_ENV_OPTS" ]; then . "$PERFORMASURE_HOME/scripts/quest-java-env.sh" else echo PerformaSure agent NOT enabled fi 3 Save your modified setupCmdLine script file. 4 Locate your profile setupCmdLine script. The default installation places it in

WAS_HOME/profiles//bin. Set PERFORMASURE_HOME at the end of the profile script to enable monitoring for that profile. Windows: rem Enable Quest Agent monitoring for this profile set PERFORMASURE_HOME=***SET THIS to Your PerformaSure Home Directory ***

UNIX: # Enable Quest Agent monitoring for this profile PERFORMASURE_HOME=***SET THIS to Your PerformaSure Home Directory *** export PERFORMASURE_HOME 5 Save the changes to your profile-specific setupCmdLine script.

Creating a new WebSphere 6.x service If starting your servers, NodeAgents, or Deployment Managers as a service, you will need to create a new Windows Service to use the Instrumented Agent for Java EE instrumentation. Refer to IBM documentation for instructions on creating/installing a Windows Service with the WASService.exe tool. Your old Windows Service can be kept, but ensure that no more than one service for your WebSphere server, NodeAgent, or Deployment Manager has a startup type of Automatic. All others should be set to Manual.

Configuring Application Servers for the Cartridge for Java EE IBM WebSphere Application Server

67

When creating a new Windows Service to be integrated with the Instrumented Agent for Java EE, provide an additional argument to the -startArgs option: Note

In the following code, quotes are required, and there is a required space between the first quote and the dash.

• For WebSphere server use: " -Dquest.agent.websphere.server"

• For WebSphere NodeAgent use: " -Dquest.agent.websphere.nodeagent"

• For WebSphere Deployment Manager use: " -Dquest.agent.websphere.dmgr"

Examples Note

A caret (^) character is required at the end of a line (other than the last) to correctly wrap the DOS command on multiple lines. There is a required space before the caret character to ensure proper spacing when copying and pasting the following code blocks.

WebSphere Server WAS_HOME\bin\WASService.exe -add "BASE server1 - with Agent" ^ -servername server1 ^ -profilePath "C:\WebSphere6\profiles\AppSrv01" ^ -startArgs " -Dquest.agent.websphere.server" ^ -startType automatic

WebSphere NodeAgent WAS_HOME\bin\WASService.exe -add "ND nodeagent - with Agent" ^ -servername nodeagent ^ -profilePath "C:\WebSphere6\profiles\AppSrv01" ^ -startArgs " -Dquest.agent.websphere.nodeagent" ^ -startType automatic

68

Foglight Cartridge for Java EE Installation and Configuration Guide WebSphere Deployment Manager

WAS_HOME\bin\WASService.exe -add "ND dmgr - with Agent" ^ -servername dmgr ^ -profilePath "C:\WebSphere6\profiles\Dmgr01" ^ -startArgs " -Dquest.agent.websphere.dmgr" ^ -startType automatic

Modifying the WebSphere 6.x startup scripts Use the steps in this section to modify the WebSphere 6.x startup scripts. Note

Do not follow the procedures in this section if you are starting your servers, NodeAgent, or Deployment Manager using Windows services.

To modify the WebSphere 6.x startup scripts: 1 Locate your profile-specific startServer, startNode, or StartManager script. Save a

backup copy before continuing. 2 Open your profile-specific startServer, startNode, or startManager script. Before

the call to the WebSphere Installation startServer, startNode, or startManager script, add the following environment variable as appropriate: Windows: a In startServer add: set QUEST_JAVA_ENV_OPTS=WEBSPHERE:SERVER b In startNode add: set QUEST_JAVA_ENV_OPTS=WEBSPHERE:NODEAGENT c In startManager add: set QUEST_JAVA_ENV_OPTS=WEBSPHERE:DMGR

UNIX: a In startServer add: QUEST_JAVA_ENV_OPTS=WEBSPHERE:SERVER export QUEST_JAVA_ENV_OPTS b In startNode add: QUEST_JAVA_ENV_OPTS=WEBSPHERE:NODEAGENT export QUEST_JAVA_ENV_OPTS

Configuring Application Servers for the Cartridge for Java EE IBM WebSphere Application Server

69

c In startManager add: QUEST_JAVA_ENV_OPTS=WEBSPHERE:DMGR export QUEST_JAVA_ENV_OPTS

Starting the WebSphere 6.x modified server Use the steps in this section to start the WebSphere 6.x modified server. To start the WebSphere 6.x modified server: 1 Configure WebSphere to provide PMI metrics for Instrumented Agent for Java

EE collection. See “Setting the PMI Levels on WebSphere 6.x” on page 69 for details. 2 If it is not already running, start the Foglight Management Server. 3 If you are using a standalone WebSphere server, stop the server and restart it with

the modified script or the new Windows Service. An Instrumented Agent for Java EE is launched for each instrumented server. When the Instrumented Agent for Java EE connects to the Foglight Management Server, the Management Server console confirms that a WebSphere Application Server Agent has connected by displaying a message such as: INFO Agent licenses assigned; Type: websphere, Host: , CPUs: 1; CPU licenses in use: 1INFO Accepted DCE connection from Agent "server1 (WebSphere)" (WebSphere 6.0)

In addition, the log file for the WebSphere Application Server Agent will contain an INFO message stating that it has connected to the Nexus.

Setting the PMI Levels on WebSphere 6.x To set the PMI levels on WebSphere 6.x: 1 In the WebSphere Administrative Console navigation tree, choose Servers >

Application servers. In the right pane, the Application servers page appears with the Configuration tab open. 2 In the right pane, select the server. 3 Under Performance, click Performance Monitoring Infrastructure (PMI). 4 Select the Enable Performance Monitoring Infrastructure (PMI) checkbox. 5 Optional: select or clear the Use sequential counter update check box to enable

or disable precise statistic update.

70

Foglight Cartridge for Java EE Installation and Configuration Guide 6 Set the Currently monitored statistic set to Extended. This is the minimum PMI

level required for Foglight to populate the WebSphere 6 Agent’s tables with metric-related data. This option enables collection of detailed performance statistics on runtime and application components. Note

If you set the Currently monitored statistic set to None, PMI will be automatically disabled. The higher the setting, the more significant the performance impact of the metric collection process. For more information on PMI settings, see your WebSphere documentation.

7 Click Apply, then OK to return to the server settings. 8 In the Messages pane, click Save to apply your changes.

Restart the WebSphere Application Server in order for the PMI settings to take effect.

Deactivating the Instrumented Agent for Java EE in WebSphere To restore your IBM WebSphere Server to its original state, either undo the code changes made during the integration process, or revert to the original backup script. • If you made a backup copy of the original script, use the original file to start your server or • revert the WebSphere Server to its original state by removing the additions to the Java command line. For example, if you were running WebSphere 6 or 6.1, the procedures to be reversed may include: • “Running WebSphere with security enabled” on page 56, if relevant • “Configuring the WebSphere 6.x environment” on page 65 • “Modifying the WebSphere 6.x startup scripts” on page 68

Configuring Application Servers for the Cartridge for Java EE Oracle® Application Server

71

Oracle® Application Server This section contains instructions for integrating the Instrumented Agent for Java EE with an Oracle application server versions 10g R2 (V10.1.2) and 10g R3 (V10.1.3).

Configuring the Oracle Application Server 10g R2 (V10.1.2) and 10g R3 (V10.1.3) Note

In OracleAS 10g R2 and R3, the cluster name is implicitly set to default whether a server is running in a cluster or in a standalone environment. However, the Instrumented Agent for Java EE will not be able to detect a cluster unless the cluster name is explicitly set to something other than default. You set the cluster name in the file /opmn/conf/opmn.xml by adding the

cluster-name attribute to the ias-instance tag for each server in the cluster and setting this attribute to the desired value. For example:

Note that you must add the cluster-name attribute and set it to the same value for each application server in your cluster.

To configure Oracle Application Server 10g R2 and 10g R3: 1 Run the Instrumented Agent for Java EE preinstrumentor shell script or cmd file

in the scripts directory of your Instrumented Agent for Java EE installation. Tip

If you would like to set options specific to the JVM you are running, set the environment variable JVM_OPTIONS along with the desired VM options. Setting this variable causes the options that you specify to be passed to the Instrumented Agent for Java EE preinstrumentor script. For example, to set the memory limit for the preinstrumentor to 256 MB, you would specify JVM_OPTIONS="-Xms256m" (on Unix platforms) or JVM_OPTIONS=-Xms256m (on Windows).

The preinstrumentor takes one argument: the location of the JDK required by the Oracle application server. Note

You must run the preinstrumentor for each JDK used in your Oracle application server environment (i.e., if you use multiple JDK installation locations for JDK 1.4 and 1.5) or if you use a JDK other than /jdk. To determine the JDKs in use at your environment, enter the following command:

/bin/java -version

72

Foglight Cartridge for Java EE Installation and Configuration Guide Run the preinstrumentor by entering one of the following commands: Unix /scripts/preinstrumentor.sh /jdk

Windows \scripts\preinstrumentor.cmd \jdk

The instructions in this section assume no more than two JDKs (1.4 and 5.0) in use simultaneously. Within a few seconds of successful completion, you should have a new file in the following directory on the machine where you ran the preinstrumentor. Unix /bootstrap Windows \bootstrap The file name matches the location of the JDK supplied to the preinstrumentor. Tip

Make a backup copy of your original /opmn/conf/opmn.xml file before proceeding with the steps below.

2 Open /opmn/conf/opmn.xml in a text editor. a Add the following environment variable definitions at the level. Omit the definition of PERFORMASURE_JDK15_OPTIONS if you are not

Configuring Application Servers for the Cartridge for Java EE Oracle® Application Server

73

using a 5.0 JDK. Omit the definition of PERFORMASURE_JDK14_OPTIONS if you are not using a 1.4 JDK. Tip

Forward and backward slashes (“/”, “\”) in opmn.xml-environment-variable-values are automatically converted to the platform-specific path-separator character, unless preceded by a caret (^). The new environment variables can therefore work on both Windows and Unix platforms without requiring any modifications because of slashes.

b Replace with the path to the directory in which the

Instrumented Agent for Java EE is installed. If there are no spaces in , it does not have to be surrounded by " (although their presence is not detrimental). c If using JDK 1.4, replace with the file name of the bootstrap JAR file created in the / bootstrap directory when you ran the preinstrumentor in step 1 for your

JDK 1.4 installation (for example, C--AppServers-oracle-10gR2_10.1.2jdk.jar). If using JDK 1.5, replace with the file name of the bootstrap JAR file created in the / bootstrap directory when you ran the preinstrumentor in step 1 for your

74

Foglight Cartridge for Java EE Installation and Configuration Guide JDK 1.5 installation (for example, C--AppServers-oracle-10gR3_10.1.3jdk.jar). Caution

If you are integrating the Instrumented Agent for Java EE with OracleAS 10g R2 or 10g R3 in a clustered environment and you have two or more OC4J server instances with the same name, ensure that the id attribute of the process-set tag for each OC4J instance is unique within the cluster.

d Append the following to the value attribute of the java-options tag that is enclosed in the start-parameters tag for each OC4J component that you

want instrumented. Employ the JDK version that was used for that OC4J instance. Note

$PERFORMASURE_JDK14_OPTIONS or $PERFORMASURE_JDK15_OPTIONS must be the last variable in the java-options list.

Modifications When Using JDK 1.4

Modifications When Using JDK 1.5 3 Save opmn.xml. 4 If opmn is running, you must reload the modified opmn.xml file by launching opmnctl reload. If opmn is not running, then start it now. 5 Start and restart each OC4J process that was modified in step 2d. Oracle

application server 10g R2 and R3 have been instrumented and are ready for connection to the Nexus.

Configuring Application Servers for the Cartridge for Java EE Oracle® Application Server

75

Deactivating the Instrumented Agent for Java EE in OracleAS To deactivate Instrumented Agent for Java EE in Oracle Application Server 10g R2 (V10.1.2) and 10g R3 (V10.1.3): Tip

Keep a copy of the opmn.xml file that you modified for the Instrumented Agent for Java EE. Doing so will allow you to start your server with the Instrumented Agent for Java EE without having to re-edit this file.

1 Stop the server. 2 If you made a backup copy of /opmn/conf/opmn.xml, use the

original file to start the server. If you did not make a backup copy, edit /opmn/conf/opmn.xml by making the following changes: a Remove the Instrumented Agent for Java EE code block that you appended to the value attribute of the java-options tag (enclosed in the startparameters tag) for each component that you instrumented. b Save opmn.xml.

76

Foglight Cartridge for Java EE Installation and Configuration Guide

JBoss Application Server This section contains instructions for integrating the Instrumented Agent for Java EE with a JBoss application server versions 4.0.[0-5] and versions 4.2.[0-3].

Before You Begin If you are running the JBoss application server version 4.0 with Jetty, you will have to make the following changes to the agent-type/jboss-400.config file and/or agent-type/ jboss-420.config file before you start recording. Refer to “Configuration Lookup Sequence” on page 30 for information on locating the proper copy of this file. To make changes to the config files: 1 Comment out the following line: "com.sitraka.pas.agent.plugin.instrumentor.method.ServletIns trumentor", 2 Uncomment the following lines: #"com.sitraka.pas.agent.plugin.instrumentor.method.HttpServl etInstrumentor", #"com.sitraka.pas.agent.plugin.instrumentor.ServletRequestIn strumentor", 3 Save the file.

Enabling JTA Metrics for JBoss Application Server Version 4.2 By default, statistics are not enabled for the Transaction Manager Service in JBoss version 4.2. To allow the Instrumented Agent for Java EE to collect these statistics, edit the jbossjta-properties.xml file in your JBoss server//conf directory and add the following line to the element. Restart your JBoss application server.

Configuring Application Servers for the Cartridge for Java EE JBoss Application Server

77

Configuring the JBoss Application Server Versions 4.0 and 4.2 Use the following steps to configure a JBoss application server. For variations, note the exception list presented at the end of the procedure. Note

For the JBoss application server version 4.0, the Management EJB (ejb-management.jar) must be deployed for the JBoss metrics collector to work. The Management EJB is not, however, deployed by default. The Management EJB can be found in the docs/examples/jmx subdirectory of the JBoss application server home directory. To deploy the Management EJB, copy the JAR into the deploy/management subdirectory of your server directory (for example, / server/default/deploy/management).

To configure the JBoss application server: 1 Make a backup copy of your original JBoss server startup script \bin\run.bat (Windows) or /bin/run.sh (Unix). 2 Copy the following block of code to your JBoss server startup script. Insert the

block just before the Java command line that starts the JBoss application server, but before any commands that set or modify the JAVA_HOME and JAVA_OPTS environmental variables.

Code Block for UNIX PERFORMASURE_HOME=***SET THIS*** PerformaSure Home Directory *** if [ -f "$PERFORMASURE_HOME/scripts/quest-java-env.sh" ] then QUEST_JAVA_ENV_OPTS=JBOSS:SERVER:JAVA_OPTS . "$PERFORMASURE_HOME/scripts/quest-java-env.sh" else echo Quest Agent NOT enabled fi

Code Block for Windows set PERFORMASURE_HOME=***SET THIS WITHOUT USING QUOTES*** PerformaSure Home Directory *** set QUEST_JAVA_ENV_OPTS=JBOSS:SERVER:JAVA_OPTS call "%PERFORMASURE_HOME:"=%\scripts\quest-java-env.cmd" if ERRORLEVEL 1 echo Quest Agent NOT enabled 3 Set the PERFORMASURE_HOME variable to the Java_EE installation directory.

In UNIX quote this path if it contains spaces.

78

Foglight Cartridge for Java EE Installation and Configuration Guide 4 Before saving this new startup script, ensure your environment does not meet any

of the exceptions listed at the end of this section, then save the new script. 5 If it is not already running, start the Foglight Management Server, because the

instrumented JBoss application server will attempt to connect to it when launched using the new script. 6 Start the JBoss application server using the new script.

The Foglight Management Server console confirms that a JBoss application server Agent has connected by displaying a message such as: INFO Accepted connection from JBoss Agent on host:

In addition, the log file for the JBoss application server Agent will contain an INFO message stating that it has connected to the Nexus. Note

By default, Agent log files are created in the logs subdirectory of the Foglight home directory on the Agent machine.

Exception List: 1 If you have spaces in the PERFORMASURE_HOME path and your JBoss

application server is on UNIX, the following additional changes apply. If one or both of these conditions are not true, this exception does not apply. Edit the startup script and insert the following code in the Java command line before org.jboss.Main: For JDK 1.4 "${PERFORMASURE_BOOTSTRAP}" ${PERFORMASURE_OPTIONS}

For JDK 5.0 "${PERFORMASURE_BOOTSTRAP}" "${PERFORMASURE_JAVA5}" ${PERFORMASURE_OPTIONS} 2 If using a JRockit JDK, edit the startup script and insert the following code in the

Java command line before org.jboss.Main: UNIX: ${PERFORMASURE_BOOTAGENT}

Windows: %PERFORMASURE_BOOTAGENT%

Configuring Application Servers for the Cartridge for Java EE JBoss Application Server

79

3 If modifying run.sh for the JBoss application server version 4.0.5 or later, and

you applied either exception #1 or exception #2 or both, the following exception applies. For JBoss application server version 4.0.5 and later, the run.sh script provides two different Java command lines. Depending on the options specified when the script is launched, only one of these command lines will be used. The environment variable LAUNCH_JBOSS_IN_BACKGROUND determines which Java command line is used. Ensure that you have modified the correct command for your intended use, or, if unsure, make the prescribed modifications to both Java command lines.

Deactivating the Instrumented Agent for Java EE in JBoss To restore your JBoss application server to its original state, either undo the code changes made during the integration process, or revert to the original backup script. • If you made a backup copy of the original script, use the original file to start your server or • revert the JBoss application server to its original state by removing the additions to the Java command line.

80

Foglight Cartridge for Java EE Installation and Configuration Guide

5 Configuration FAQ and Troubleshooting Application Servers in General This chapter discusses potential issues when configuring application servers for the Foglight Management Server. Foglight Management Server does not detect the correct type for the application server. What might be the problem? Users start their servers in various ways. Some of these ways may be different enough from the standard approaches described in this guide to cause the Foglight Management Server to be unable to determine the correct type for the application server. For example, if you are using a custom class to do some preliminary setup before launching the WebLogic server, and you are passing weblogic.Server as a parameter to this class rather than calling weblogic.Server directly in the Java startup line, the Foglight Management Server gets the wrong name for the application server. If the Foglight Management Server is unable to detect the application server type, it disables the associated Agent and logs a fatal error. Workaround The workaround is to set the application server name, and type explicitly as system properties in the Java command line that starts the application server. Add a -D option to the Java startup line that has this format: -Dquest.agent.appserverinfo=::[[:]]

Example: -Dquest.agent.appserverinfo=petstore1:WebLogic:8.1.0:petCluster

The server name, and type are required parameters. The version and cluster name parameter are optional; if it is not supplied, the Foglight Management Server attempts to

82

Foglight Cartridge for Java EE Installation and Configuration Guide auto-detect the missing information. Valid application server type parameters are Generic, WebLogic, WebLogicNodeManager. The Foglight uses the server type and server version that are set in the command line to configure itself for that specific application server. Caution

Specifying an incorrect application server type or version number results in errors later in the startup sequence. Valid (case-insensitive) application server type parameters are Generic, WebLogic, WebLogicNodeManager Specifying an incorrect application server version number results in errors later in the startup sequence. The format for setting the version parameter differs based on the application server that you are configuring to work with Foglight Management Server. Consult the list below for the correct server- and version-specific format to use to set the version parameter. Numbers and periods must be specified as shown, but x can be replaced with 0 or with any other character or string of characters. For example, you can specify 8.1.5 to set the version parameter for WebLogic 8.1 SP5. Where x is shown after a number (for example, 9.0.2x), you can specify another character or string of characters after this number. Where x is shown after a period (for example, 8.1.x), you must specify another character or string of characters after the period or the version parameter is not set correctly. WebLogic 8.1 — specify 8.1.x WebLogic 9.0 — specify 9.x WebLogic Node Manager — specify x

Why does my application server take so long to start up after integrating it with Foglight Management Server? In addition, when configuring Agents, the user that is running the server(s) must have read/execute permissions on all directories under and including JAVA_EE_HOME. JAVA_EE_HOME identifies the installation directory of the Instrumented Agent for Java EE on the monitored host. If you have manually integrated an application server with Foglight Management Server on AIX5.3 with JVM 1.4, the server is taking a long time to start up due to a problem with JVM 1.4 on AIX5.3. Workaround Add -Djava.net.preferIPv4Stack=true to the Java command line that starts the server.

Configuration FAQ and Troubleshooting Application Servers in General

83

Refer to ibm.com for more information about the problem with JVM 1.4 on AIX. I get the following error when trying to start my application server: [Agent for Java EE main thread] ERROR com.sitraka.pas.agent.Agent - Unable to determine number of CPUs, assuming 1 CPU Why does this error occur? This error results from allocating too much memory in the application server’s startup command, which does not leave enough for the Foglight Managment Server licensing mechanism to determine the number of CPUs on the machine. It also prevents a Foglight System Agent from starting. Try reducing the memory allocated to the application server in the startup command. I have multiple servers with the same name and residing on the same host. When the Instrumented Agents for Java EE connect to the Foglight Management Server, only the first agent connects. What might be the problem? This error occurs because the Foglight Managment Server does not allow duplicate agent names. Agent names are duplicated when multiple servers with the same name on the same host try to connect. If multiple Instrumented Agents for Java EE reside on the same machine with the same server name, only one will be permitted to connect. Workaround The workaround is to uniquely identify the agent name by using the following server startup line: -Dquest.config.agent.agentname=

For example, if you have two administrative servers for two different WebLogic domains running on the same host, the startup lines can be modified to include the following (one per server): -Dquest.config.agent.agentname=test_domain.admin -Dquest.config.agent.agentname=prod_domain.admin

Since the agent names are unique, they will connect to the Foglight Managment Server but not modify the server name.

84

Foglight Cartridge for Java EE Installation and Configuration Guide

Index A Agent-Nexus connection NexusAuthFailureRetryInterval 29 NexusRetryInterval 29 AgentOrderInterval 33 application servers configuring JBoss server 76 configuring OracleAS 71 configuring WebLogic server 47 configuring WebSphere server 56 attempting to restore the Agent-Nexus connection 29 AuthenticationTimeout 30

connection details configuring for Instrumented Agent for Java EE 28 contacting Quest 12 core 9

D deactivating Instrumented Agent in JBoss 79 Instrumented Agent in OracleAS 75 Instrumented Agent in WebLogic 54 Instrumented Agent in WebSphere 70 documentation 9, 10

C

F

cartridge 10 Cartridge for Java EE installing 20 changing the commit timeout setting 34 CommitTimeout 34 configuration lookup sequence 30 configuring Instrumented Agent for Java EE connection details 28 JBoss server 76 logging properties 32 the Nexus 32 WebLogic server 47 WebSphere 5.1 57 WebSphere 6.x 65

Federation configuring the Cartridge for Java EE 41 federation.config 41 feedback 10 firewalls preventing a firewall from closing Nexus connections 35

H how to activate a cartridge 22 install a cartridge 21

86

Foglight Cartridge for Java EE Installation and Configuration Guide

I

S

installing Instrumented Agent for Java EE 23 instrumentation 43 Instrumented Agent for Java EE attempting to connect to the Nexus after an authentication failure 29 configuring connection details 28 logging properties 32 installing 23 logging properties 32 uninstalling 26

server name not recognized 81 service request description 16 setting the authentication timeout 30 silent installation mode 25 specifying the Agent order interval 33 support 12

J JBoss server configuring 76

L logging properties configuring for Instrumented Agent for Java EE 32

N name Foglight Management Server doesn’t detect server name 81 Nexus configuring 32 Nexus connections preventing a firewall from closing Nexus connections 35 NexusAuthFailureRetryInterval 29 NexusRetryInterval 29

O OracleAS configuring 71

T technical support 12 text conventions 10

U uninstalling Instrumented Agent for Java EE 26

W WebLogic server configuring 47 WebSphere server configuring 56 running with security enabled 56