Foglight Application Performance Monitoring SaaS Edition
2015 Dell 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 Dell Inc. The information in this document is provided in connection with Dell 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 Dell products. EXCEPT AS SET FORTH IN THE TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, DELL 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 DELL 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 DELL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Dell 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. Dell does not make any commitment to update the information contained in this document. If you have any questions regarding your potential use of this material, contact: Dell Inc. Attn: LEGAL Dept 5 Polaris Way Aliso Viejo, CA 92656 Refer to our web site (software.dell.com) for regional and international office information. Patents Foglight is protected by U.S. Patents # 7,979,245; 8,175,862; and 8,892,415. Additional Patents Pending. For more information, go to http://software.dell.com/legal/patents.aspx. Trademarks Dell, the Dell logo, Foglight, IntelliProfile, NetVault, PerformaSure, PowerEdge, and Tag and Follow are trademarks of Dell Inc. "Apache HTTP Server", Apache, "Apache Tomcat" and "Tomcat" are trademarks of the Apache Software Foundation. Google is a registered trademark of Google Inc. Chrome, Android, and Nexus are trademarks of Google Inc. Red Hat, JBoss, the JBoss logo, and Red Hat Enterprise Linux are registered trademarks of Red Hat, Inc. in the U.S. and other countries. CentOS is a trademark of Red Hat, Inc. in the U.S. and other countries. Microsoft,.NET, Active Directory, Internet Explorer, Hyper-V, SharePoint, SQL Server, Windows, Windows Vista and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. AIX, IBM, PowerVM and WebSphere are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Sun, Oracle, Java, Oracle Solaris, and WebLogic are trademarks or registered trademarks of Oracle and/or its affiliates in the United States and other countries. SPARC is a registered trademark of SPARC International, Inc. in the United States and other countries. Products bearing the SPARC trademarks are based on an architecture developed by Oracle Corporation. OpenLDAP is a registered trademark of the OpenLDAP Foundation. HP is a registered trademark that belongs to Hewlett-Packard Development Company, L.P. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. Novell and edirectory are registered trademarks of Novell, Inc., in the United States and other countries. VMware, ESX, ESXi, vsphere, vcenter, vmotion, and vcloud Director are registered trademarks or trademarks of VMware, Inc. in the United States and/or other jurisdictions. Sybase is a registered trademark of Sybase, Inc. The X Window System and UNIX are registered trademarks of The Open Group. Mozilla and Firefox are registered trademarks of the Mozilla Foundation. "Eclipse", "Eclipse Foundation Member", "EclipseCon", "Eclipse Summit", "Built on Eclipse", "Eclipse Ready" "Eclipse Incubation", and Eclipse Proposals" are trademarks of Eclipse Foundation, Inc. IOS is a registered trademark or trademark of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. Apple, ipad, iphone, Mac OS, Safari, Swift, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Ubuntu is a registered trademark of Canonical Ltd. Symantec and Veritas are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S. and other countries. YAST is a registered trademark of SUSE LLC in the United States and other countries. Citrix, AppFlow, NetScaler, XenApp, and XenDesktop are trademarks of Citrix Systems, Inc. and/or one or more of its subsidiaries, and may be registered in the United States Patent and Trademark Office and in other countries. AlertSite and DéjàClick are either trademarks or registered trademarks of Boca Internet Technologies, Inc. Samsung, Galaxy S, and Galaxy Note are registered trademarks of Samsung Electronics America, Inc. and/or its related entities. MOTOROLA is a registered trademarks of Motorola Trademark Holdings, LLC. The Trademark BlackBerry Bold is owned by Research In Motion Limited and is registered in the United States and may be pending or registered in other countries. Dell is not endorsed, sponsored, affiliated with or otherwise authorized by Research In Motion Limited. Ixia and the Ixia four-petal logo are registered trademarks or trademarks of Ixia. Opera, Opera Mini, and the O logo are trademarks of Opera Software ASA. Tevron, the Tevron logo, and CitraTest are registered trademarks of Tevron, LLC. PostgreSQL is a registered trademark of the PostgreSQL Global Development Group. MariaDB is a trademark or registered trademark of MariaDB Corporation Ab in the European Union and United States of America and/or other countries. Other trademarks and trade names may be used in this document to refer to either the entities claiming the marks and names or their products. Dell disclaims any proprietary interest in the marks and names of others.
Legend CAUTION: A CAUTION icon indicates potential damage to hardware or loss of data if instructions are not followed. WARNING: A WARNING icon indicates a potential for property damage, personal injury, or death. IMPORTANT NOTE, NOTE, TIP, MOBILE, or VIDEO: An information icon indicates supporting information. Foglight APM SaaS Edition Updated - July 2015
Contents Introducing Foglight APM SaaS....................................... 6 Quick Start.................................................. 6 Getting Started with Foglight APM SaaS.................................. 6 Observe.................................................... 7 Ad-hoc Analysis: the Investigate Activity................................. 9 Setting Up Foglight APM SaaS Monitoring............................... 12 Validated web browsers............................................12 License Keys.................................................13 Instrument Mobile Devices..........................................13 Generate a support bundle..........................................14 Installing the APM Java Agent...................................... 15 System requirements for Java application servers...........................15 Supported operating systems......................................15 Supported JVMs...............................................16 Validated platforms...............................................16 Oracle WebLogic..............................................17 IBM WebSphere...............................................17 Red Hat JBoss................................................17 Apache Tomcat...............................................17 GlassFish...................................................18 Eclipse Jetty.................................................18 Apache Geronimo.............................................18 Install the APM Java agent..........................................18 Integrate with an application server....................................20 Known issues with APM Java Agent integration.............................21 Upgrade the APM Java agent and re-integrate your application server.............22 Automatically integrate with an app server............................22 Uninstall the APM Java agent and undo the application server integration...........23 Update the proxy server settings......................................23 Modify your Java App Server Startup................................. 24 Modify JBoss startup scripts.........................................24 domain.bat on Windows - Java 1.6..................................24 domain.bat on Windows - Java 1.5..................................25 Integrate with WebSphere..........................................25 WebSphere on Windows.........................................25 WebSphere on UNIX............................................26 Installing the APM PHP Agent....................................... 27 Key features of the PHP agent.....................................27 Supported Platforms...........................................27 Install the APM PHP agent...........................................28 4
Interactive Configuration........................................29 Instrumenting your PHP application.................................29 Integrate with a second PHP app on the same host.......................30 Silent Installation.............................................30 Uninstallation................................................32 Update the proxy server settings...................................32 Installing the APM.NET Agent...................................... 33 Key features of the.net agent....................................33 Supported platforms and versions...................................33 Install the APM.NET agent..........................................34 Interactive Configuration........................................34 Command-line installation........................................35 Instrumenting your.net application.................................35 Silent Installation.............................................35 Uninstallation................................................35 About Dell.................................................... 36 Contacting Dell..................................................36 Technical support resources.........................................36 5
Introducing Foglight APM SaaS 1 enables fast analysis of performance problems and errors in large and dynamic web-scale applications. Foglight APM SaaS uses a groundbreaking technique we call Differential Analytics. It is a simple system that tests thousands of hypotheses in real time to determine which factors are the most relevant to performance problems and errors. This system allows you to manage hundreds of application servers with the same simplicity as managing a single server. Setting Up Foglight APM SaaS Monitoring Installing the APM Java Agent Installing the APM PHP Agent Installing the APM.NET Agent Instrument Mobile Devices Getting Started with Foglight APM SaaS Observe Ad-hoc Analysis: the Investigate Activity Quick Start Get up and running quickly: 1 Run the installer to create your agent. See Setting Up Foglight APM SaaS Monitoring for details. 2 Generate transactions for the system to monitor. 3 Log in to Foglight APM SaaS and select your application. 4 Use the Monitor activity page to monitor your application. Getting Started with Foglight APM SaaS Installing the Foglight APM agent is a 5-minute process. The installer sets up your Host monitoring and creates an APM Tracing agent to collect method-level traces and other detailed transaction data. After you have created the first APM agent, you can script the installation for multiple servers. Any servers that use the same scripted installation automatically connect and feed data to the Foglight APM SaaS analytics engine. Foglight APM SaaS analyzes data from transactions that flow through your application. TIP: If you are running the APM agent as a trial, be sure to run realistic and varied traffic through the application to see the power of the dimensional analysis. Foglight APM SaaS categorizes transactions into four response statuses. Each hit is also color-coded in the UI according to its response time. The default response time status thresholds are defined as: Good (blue) response time under two seconds Fair (light purple) response time between two and five seconds 6
Poor (dark purple) response time over five seconds Error (berry red) transaction ended with an error code or uncaught exception The response time thresholds for each status are customizable. You can adjust them through the Administer UI based on the specific needs of your monitored environment. Figure 1. The Monitor Activity page in Foglight APM SaaS Monitor Activity page The Monitor activity contains three tabbed views: Observe Review your application health from the top level. Explore Look through all of the dimensions that Foglight APM SaaS analyzes. Diagnose Find the problems and their causes with Foglight s powerful ability to remove noise. Observe The Observe > Overview tab introduces the primary information required to understand the transactional performance of your application. This view also introduces Foglight APM SaaS s groundbreaking Differential Analytics through the Top Correlations. This tab contains four views: Transaction Volume view Health Score view Differential Response Time Breakdown view Top Correlations view 7
Transaction Volume view First, consider the Transaction Volume. The graph displays the transaction volume over time, color-coded by response status. This section also includes a breakdown of the Good, Poor/Fair, and Error transactions, and the overall application health score. Figure 2. The Transaction Volume and Health Score views Health Score view The Health Score is a numerical summary of the response time status for any group of transactions. This concept applies to the whole application here, but is also applicable to any subset of transactions displayed in Foglight APM SaaS. The default health score is derived from the distribution of response time status across all transactions. That is, it is a rolled-up score that averages the number of good, fair, poor, and error hits over all hits received. Each hit is assigned a specific numeric value for the health score: Good = 100 Fair = 50 Poor = 25 Error = 0 For example, if an application had 100 requests, with 1 error, 81 Good, 14 Fair, and 4 Poor, the health score would be 89. The health score appears as a numerical value and an icon and color (for example, a green check mark or red x). This concept is used to represent the health of objects from the application level to the individual dimension level, and the color may apply to any group of hits represented anywhere in Foglight APM SaaS. Differential Response Time Breakdown view Next, the Differential Response Time Breakdown shows the time spent on each tier of the application. The breakdown includes multiple app server tiers, databases, and end user and network time (if enabled). The differentiating feature here is that Foglight APM SaaS separates transactions with Good response time from those transactions with bad (Poor/Fair) response times. This separation means that if you have 100 app servers, but only 1 is performing poorly, the Poor/Fair response time bar for the tier containing that app server is much larger than the Good bar. You can see that the time for the bad transactions was spent in that tier instead of losing the problem in averaged data. Figure 3. The Response Time Breakdown view 8
Top Correlations view Finally, the Top Correlations view is where you can see the results of the powerful analytics engine. Thousands of dimensional values from your transactional data are tested against each other. The analytics engine finds the factors that are most relevant to performance problems or errors and displays them in this list. A factor is considered relevant when its percentage of errors or performance violators is significantly higher than its percentage of hits. Figure 4. The Top Correlations view Consider the following examples: 20 percent of transactions came from New York City, but 50 percent of the performance problems came from there. This factor is relevant (+30 percent). 80 percent of the errors came from a specific browser, but 90 percent of your customers use that browser. This factor is not relevant (-10 percent). App Server 14 served 8 percent of the transactions at some point, but those hits accounted for 35 percent of the performance problems. This factor is relevant (+27 percent). Foglight APM SaaS does this analysis automatically for many dimensions, including: location client properties (browser, client application type and OS) server properties (including which servers participated in a transaction and which code or SQL statements took the most time) TIP: To view a complete list of dimensions, select the Explore tab. The main advantage of this analysis is that removes the complexity of large and dynamic environments. Deployed heterogeneous code, loosely connected API-based elastic applications, dynamic URL names, or complex interdependencies between systems do not interfere with Foglight s analytics. With this approach, you do not need to catch the problem at the moment it occurs. Issues do not have to move the needle in terms of overall averages to rise to the top. Foglight APM SaaS provides a new, simpler view into relevant correlated factors affecting your application performance. Ad-hoc Analysis: the Investigate Activity Use the Investigate activity to: 9
Look for patterns in your data with the help of advanced data analysis and visualization tools. Find individual traces so that you can view their method call traces, session timeline, SQL statements, and exception traces. Investigate begins with a filtering query that limits the initial data set that you see to a specific subset of all transactions. TIP: If you drilled down to this view from the Monitor Activity page, this query may be pre-populated. Figure 5. The Investigate view, beginning with a default filtering query. You can graph the query results in a series of widgets, including: scatter plots, heat maps, histograms, pivot tables, or a world map. You can customize the widgets to show any of the fields that Foglight APM SaaS captures for individual transactions. The widgets form a visual filter chain: every widget acts as a filter for the widget that follows it. For example, you can draw a box around a group of hits in the scatter plot, or around a set of cities on the map. You could also select three rows in the pivot table. In each case, the widgets are redrawn with only the selected data. Figure 6. The hits selected in each widget filter the view in the next widget. 10
Foglight APM SaaS provides several pre-set configurations that are designed to help you find bottlenecks or resource consumption in a query result set. Figure 7. Select a preset Visual Filter, or use the Custom option to create your own. The widget chains are also fully customizable. You can create and save your own widget chains and use them for analysis again and again. And when you want to dig deeper, you can click Traces (in the Results column on the far right) to view the full details for selected individual traces. Figure 8. Investigate the detail of selected traces in the Lineup view. Put the power of Foglight APM SaaS to work for you: If you re not already logged in, head to http://www.foglight.com/ now. 11
Setting Up Foglight APM SaaS Monitoring 2 This topic provides a high-level overview of the installation process. For detailed information on a particular step, follow the appropriate Tell me more about link. Get Started: 1 Open the Foglight APM SaaS website (http://www.foglight.com/) in your web browser. 2 Create an account and agree to the Terms of Use. 3 On the Monitor a New Application page: a b c Select the Application Platform type. Select your your OS platform. Download and run the Agent Installer. 4 Follow the instructions provided by the installer for the type of agent you are installing. See Table 1 for links to procedures for each agent type. 5 Monitor your application performance. See the Foglight Application Performance Monitoring SaaS Edition User Guide for an overview, as well as tasks and workflows. If you need more information about a step or option, see the matching topic in the Tell me more table. Table 1. Where to find additional information about steps and options. Tell me more about... Which web browsers I can use to access Foglight APM SaaS Edition APM Java agent APM PHP agent APM.NET agent Mobile Device Instrumentation Troubleshooting my installation Getting help from Support Answer See Validated web browsers See Installing the APM Java Agent See Installing the APM PHP Agent See Installing the APM.NET Agent See Instrument Mobile Devices See Troubleshooting installation See Generate a support bundle Validated web browsers The following web browsers have been tested and validated for use with Foglight APM SaaS. Customers are expected to keep their browsers up to date with the latest security patches or updates. NOTE: Unless otherwise stated, all versions later than the ones listed below are supported. If your browser is not in the list, it has not been tested or validated for use with Foglight APM SaaS. Validated browsers Internet Explorer 9, 10, and 11 for desktop environments Patched according to Microsoft Security Bulletin September 2014 12
On Microsoft Windows 7 or Windows 8.1 OS platforms Internet Explorer 11 for touch environments On Microsoft Windows 8.1 Firefox 32.0.1 Firefox 31.1.0esr Safari versions: 6.1.6 on Mac OS X Lion or Mountain Lion 7.0.6 on Mac OS X Mavericks ios 8 on ipad Google Chrome 37.0.2062.120 Mobile (phone) browsers: iphone: Safari ios 8 Android: Chrome 32.0.1700.99 The following browsers are not supported: Internet Explorer: 6, 7, and 8 License Keys A license key is generated automatically when you download the APM installer. This key is bound to your APM agent. Foglight APM SaaS verifies the license key during the installation process. Instrument Mobile Devices When you want to monitor the performance of mobile applications (hereafter called apps) that implement a platform-specific user interface, you use a Dell Foglight Application Performance Monitoring SaaS Edition SDK that extends the platform s software development kit (SDK). The Foglight APM SaaS SDK enables you to capture the details and timing data required to generate performance data for your app. Performance data provides insight into how an end user interacts with your app and the performance of the app from the user s perspective. Foglight APM SaaS analyzes this data and correlates it with other known performance data, such as how long it took an application server to respond to HTTP requests from the app, to help you identify, quantify, and resolve performance issues. To configure mobile device instrumentation: 1 On the Administer page, Agent Management tab, select Installers. 2 On the Installers page, select Mobile Device Instrumentation. 3 Optional To learn more about the mobile SDKs, click the link to the guide for the platform you are interested in. The online documentation opens in a new window. 4 Click the download button for the platform you want to instrument. 5 For full instrumentation instructions, see the Mobile App Developer Guide for your platform: For Android TM platforms For IOS platforms 13
Generate a support bundle If you are asked to generate a support bundle to help the support team diagnose an issue, you can do so from the Administer activity page, or from the commmand-line. To generate a support bundle from the UI: 1 On the Agent Management > Agent Status & Troubleshooting tab of the Administer page, click Support Bundle for the application that is experiencing issues. 2 Optional To explore the contents of the support bundle before you submit it, click What s in my support bundle?. a b Click Yes to download the support bundle contents. When prompted, open the downloaded file or save it to your hard drive. 3 Type a description of the problem in the text box in the dialog box that opens. When finished, click Upload. NOTE: It takes several minutes to generate and upload the support bundle. To generate a support bundle for the APM Java agent from the command-line: 1 Open a command window. 2 Change the directory to the APM agent directory. By default this directory is: C:\Program Files\Common Files\Dell\APM Agent. 3 Run the CreateMasterSupportBundle.cmd sh script. 4 When the script is finished, follow the instructions from the Foglight APM SaaS team to upload the bundle. To generate a support bundle for the APM PHP agent from the command-line: 1 SSH to the PHP application server. 2 Execute the following command: <install_path>/bin/support-bundle.sh This command creates a file in the following location: <install_path>/state/default/support 3 When the script is finished, follow the instructions from the Foglight APM SaaS team to upload the bundle. 14
Installing the APM Java Agent 3 The Foglight APM SaaS Java Agent monitors the availability and performance of your Java TM applications and application servers, in the context of your entire application. Review the following information before beginning your installation. System requirements for Java application servers Supported operating systems Supported JVMs Validated platforms Oracle WebLogic IBM WebSphere Red Hat JBoss Apache Tomcat GlassFish Eclipse Jetty Apache Geronimo Install the APM Java agent Integrate with an application server Known issues with APM Java Agent integration Upgrade the APM Java agent and re-integrate your application server Automatically integrate with an app server Uninstall the APM Java agent and undo the application server integration Update the proxy server settings System requirements for Java application servers The following sections and topics provide information about supported application servers, JVMs, and OS platforms. Supported operating systems Supported JVMs Supported operating systems The following operating systems are supported for Foglight APM SaaS: 15
Table 1. Supported platforms Operating System Version OS Architecture Microsoft Windows Vista (SP1 or above) 7 (Professional or above) 8 (Pro, Enterprise) 8.1 IA-32 x86-64 Novell SUSE Linux Enterprise 10 Server 11 Oracle Linux 4.x 5.x 6.x Server 2003 Server 2008 Server 2008 R2 Server 2012 Server 2012 R2 Red Hat Enterprise Linux AP/Server 5.x 6.x 7.x IA-32 x86-64 x86-64 IA-32 x86-64 IA-32 x86-64 IA-32 x86-64 Supported JVMs JVM s of version 1.5 through 1.8 are supported, regardless of the application server the JVM is running on. NOTE: For Java 1.8 support, the Java version must be 1.8.0_31 or later. For Java 1.7 support, the Java version must be 1.7.0_75 or later. The following specific JVMs have been tested and validated for the APM agent: Oracle Java TM SE version 1.5 to 1.8 OpenJDK 1.6 and 1.7 JRockit 1.5 and 1.6 Azul Systems Zing JVM 1.6 and 1.7 Validated platforms Foglight APM SaaS is expected to successfully monitor any application server running any of the JVM versions listed in Supported JVMs. The following is a list of specific application server platforms against which Foglight APM SaaS has been tested and validated: Oracle WebLogic IBM WebSphere Red Hat JBoss 16
Apache Tomcat GlassFish Eclipse Jetty Apache Geronimo Oracle WebLogic WebLogic Server 12c (12.1.[1-2]) WebLogic Server 11g R1 (10.3.[1-6]) WebLogic Server and Express 10.3 WebLogic Server and Express 10.0 WebLogic Server and Express 9.2 IBM WebSphere WebSphere 8.5.5 WebSphere 8.5 WebSphere 8.0 WebSphere 7.0 Red Hat JBoss JBoss WildFly 8.[0-2] NOTE: In this release, support for WildFly does not include JavaScript instrumentation injection for end user monitoring or HTTP POST parameter collection. JBoss AS 7.1.[0-1] JBoss AS 6.1.0 JBoss EAP 6.2 JBoss EAP 6.1.[0-1] JBoss EAP 6.0.[0-1] JBoss EAT 5.2 JBoss EAP 5.1.[0-2] Apache Tomcat Apache Tomcat 7.0.[6-52] Apache Tomcat 6.0.[0-37] 17
GlassFish Supported with workarounds, as described in Known issues with APM Java Agent integration. GlassFish 4.1 Eclipse Jetty Jetty 9.2.5 Jetty 8.1.16 Apache Geronimo Supported with workarounds, as described in Known issues with APM Java Agent integration. 3.0.1 2.2.1 2.1.8 If you encounter any issues while monitoring an application server not listed here, please contact the Foglight APM SaaS Support team to assist you with diagnosing the issue and expanding the validated platforms list. Install the APM Java agent The Foglight APM SaaS Java Agent installer is distributed as a JAR file. The Monitor a New Application page provides the command that must be run from the command-line to perform the installation. The installer extracts the agent and configures host monitoring. NOTE: If a fglam.exe service is already installed on the host, you must uninstall this service before attempting to run the Foglight APM SaaS installer. To install the APM Agent: 1 On the Monitor a New Application page, type a name for your application in the Application Name box. 2 To monitor a Java application server, ensure that the App Server Agent tab is selected. 3 Select the Application Platform Type: Java. 4 Select your Install OS type: Microsoft Windows 32-bit or 64-bit, or Linux 32-bit or 64-bit. 5 Click Download Installer Agent. 6 Open a command window and change directories to the location where the file was downloaded. 7 Run the command that was generated for you in the gray box with one or more of the following options, as required by your environment. For example, for a Windows 64-bit installation, the command to use the default setting is: java -jar setupapmsaasjava-<version>-windows-x86_64-myapplication.jar -f Table 2. Installer options. Option short name Option long name Description -f --use-defaults Performs an installation with default options. -h --help Displays the help. This is the default behavior when no options are provided. 18
Table 2. Installer options. Option short name Option long name Description -i --no-install Performs a trial installation. Use this option to validate installation parameters without actually completing the installation. -l --no-comm-check Disables communication with Foglight servers during installation. -o --logdir <dir> Sets the directory for the installation log file. The default is: <working directory>/logs. -t --tempdir <dir> Sets the working directory for installation tasks. The default is: <setup jar location>/jarname -u --update If the selected installation directory (--installdir from Table 2) already contains an agent, the installation is updated. Table 3. Optional Installation settings. Option short name Option long name Description -d --installdir <dir> Sets the installation directory for the APM agents. -s --no-service Disables the installation of the Foglight Agent Manager (FglAM) Windows Service. -T --tier <name> Sets the tier name for the application. -x --proxy <host>:<port> Enables the APM agent to use a proxy at the specified host and port address. -xd --proxy-domain <domain> Sets the proxy user domain. -xp --proxy-pass <password> Sets the proxy password. -xu --proxy-user <user> Sets the proxy username. -xx --proxy-preserve When updating an existing installation (- u), this command tells the agent to ignore any proxy options that are specified on the command-line, including empty options. This effectively removes existing proxy settings during the update. This option also disables the communication check. Table 4. Advanced installation options. Option short name Option long name Description -D <systemproperty> -n --host-display-name <name> Optional system property to pass to the embedded installer. Provides an alternate display name for the monitoring agents. TIP: If the options you specify are incomplete or incorrect, the installer prompts you to provide the proper information. Follow the on-screen instructions. 19
For example: To run the installer, specifying an installation directory and setting the directory for the log file, the command would be: java -jar setupapmsaasjava-<version>-windows-x86_64-myapplication.jar -d C:\MyInstall\Here\ -o C:\MyInstall\Here\logs IMPORTANT: Do not close the command window after the installation completes successfully. The Java options required for integration appear on the command-line. Copy and paste these two lines into a text file for reference. For more information, see Integrate with an application server. Troubleshooting installation What are the default installation directories? By default (that is, if you run the installer with the -f option), the installer uses the following directories: Install directory <location of downloaded JAR file>\foglightapm Temp directory <location of downloaded JAR file>\setup Log directory <location of downloaded JAR file>\setup\logs What do I do if the installation fails? In most cases, the installer prints the error message and any related solution in the command window. If this information is insufficient, or if you encounter an unspecified error, open and review the log files for the installer. The installation creates a set of pre-installation log files and a set of post-installation log files. Pre-installation log files are written to the log directory specified when the installer was launched. For example: C:\setup\logs. Post-installation log files are written to the state directory of your installation. If you need assistance with troubleshooting your installation, contact Support. Integrate with an application server To complete the integration of the APM agent with your application server, copy the Java options from the installer command window and add them to the Java startup commands for your application. To complete the integration: 1 In the installer command window, after the message Installation was SUCCESSFUL, read the required steps for integration. 2 Make note of which option you require. For Java version 6 or later JVMs, only the -javaagent option is necessary. This is the preferred method of integration for all application servers. For Java version 5 and some cases of Java version 6 JVMs, both the -javaagent and -Xbootclasspath options are required. For all JVM versions: -Ddell.appname= YourAppName 3 Copy one or more of the options to a text file, as needed. 4 Open the file containing the Java startup commands for your application and add the Java option(s) provided by the installer. For example: For Tomcat, with Java 1.6 or later, open catalina.bat and add the line to the JAVA_OPTS variable: 20
1: set JAVA_OPTS=%JAVA_OPTS% -javaagent:"<install_path>\agents\javaee\lib\foglightapm-agent.jar" For Tomcat, with Java 1.5, open catalina.bat and add the following to the JAVA_OPTS variable: 1: set JAVA_OPTS=%JAVA_OPTS% ^ 2: -Xbootclasspath/p:<install_path>\agents\JavaEE\<version>\lib\performasurebootstrap.jar ^ 3: -javaagent:<install_path>\agents\javaee\<version>\lib\performasure-agent.jar IMPORTANT: The file you need to edit, and the location of the Java options varies depending on the application server you want to integrate with. For more examples, see Modify your Java App Server Startup. 5 Update any exsiting Java 6 Save and close the file. 7 Restart your application server. 8 Allow the application to run and generate traffic to it. 9 View the application in Foglight APM SaaS, on the Monitor page. For more information about the Monitor activity, see Getting Started with Foglight APM SaaS. Troubleshooting instrumentation I am having trouble instrumenting Apache Geronimo. Check to ensure that you are using any known workarounds that may be required. Workaround for Apache Geronimo 2.1.8 I am having trouble instrumenting GlassFish. Check to ensure that you are using any known workarounds that may be required. Workaround for GlassFish 4.1 I am trying to run Tomcat with the APM Java agent, but the agent does not start and no log files are created. Check to ensure that you are using any known workarounds that may be required. Workaround for Tomcat with java.endorsed.dirs=<tomcat_home>\bin system property Known issues with APM Java Agent integration The following is a list of tested platform and version combination that Foglight APM SaaS does not support: Oracle WebLogic 12.1.3 IBM WebSphere Application Server (WAS) Liberty Profile Workaround for Apache Geronimo 2.1.8 Apache Geronimo version 2.1.8 requires a workaround in order to allow temporary file creation in the default location during startup. Add the following statement to the geronimo.bat file, directly before the line that starts the app server: 21
set GERONIMO_TMPDIR=%GERONIMO_HOME%/%GERONIMO_TMPDIR% Workaround for GlassFish 4.1 In most cases, the APM Java agent no longer requires that you specify -Xbootclasspath/p: <install_path>\agents\javaee\<version>\lib\performasureagent.jar on the command-line. However, GlassFish 4.1 still requires this option and generates errors if it is not provided. Workaround for Tomcat with java.endorsed.dirs=<tomcat_home>\bin system property If the java.endorsed.dirs system property is set to <tomcat_home>\bin, you must insert com.quest.pas.agent.bootstrap.agentbootstrap immediately before org.apache.catalina.startup.bootstrap in the Java command-line used to start Tomcat. Upgrade the APM Java agent and reintegrate your application server The Foglight APM SaaS installer can run the same version multiple times, to upgrade an integration with the same application server, or to integrate with other application servers. To upgrade the APM Java agent and re-integrate your application server: 1 Upgrade the APM Java agent. a b c d Run the PrepareForLocalUpgrade.cmd/sh script. Download an updated installer from http://www.foglight.com/apm/setupapm, using the same configuration you provided initially. Launch the Foglight APM SaaS installer, and point to the installation location of the existing APM agent. Ignore the warning that the chosen installation directory is not empty. Complete the installation. 2 Restart the application server(s). The new application server integration takes effect after the application server restart. Automatically integrate with an app server Use this procedure to integrate with an application server on a host machine where you have already installed the APM Java agent. For example, if you want to integrate with a JBoss app server, follow the steps below. You can repeat this procedure for additional installations of the same or different app server types. To automatically integrate with an app server: 1 Locate the script named IntegrateAgain.cmd sh in the APM agent installation directory (for example, C:\<install_path>\FoglightAPM\IntegrateAgain.cmd sh). 2 Double-click the script. An interactive installer launches, enabling you to integrate another app server. 3 Follow the steps of the installer and provide the necessary integration details. 22
4 After the integration completes, restart the application server. The new application server integration takes effect after the application server restart. Uninstall the APM Java agent and undo the application server integration This procedure assumes that you have already run the Foglight APM SaaS installer and integrated with a Java application server. To uninstall the APM agent and undo the application server integration: 1 Stop all application servers integrated with the Foglight APM SaaS installation. 2 Locate the uninstall script in the APM agent installation directory (for example, C:\Program Files\Common Files\Dell\APM Agent\). 3 Run the uninstallation script: On Windows platforms: run the Uninstall.cmd script. On UNIX /Linux platforms: run the Uninstall.sh script. 4 Restart the application servers, as necessary. Update the proxy server settings After you have installed the APM Java agent, and updated it with additional integrations, you may need to update the proxy settings for the agent. To update the proxy server settings: 1 Locate the script named ConfigureProxy.cmd sh in the APM agent installation directory (for example, C:\<install_path>\FoglightAPM\ConfigureProxy.cmd sh). 2 Double-click the script. An interactive installer launches, enabling you to re-configure the proxy server settings. 3 Follow the steps of the installer and provide the necessary integration details. 4 After the integration completes, restart the application server. 23
Modify your Java App Server Startup 4 To complete the integration of the APM agent with your application server, copy the Java options from the installer command window and add them to the Java startup commands for your application. The file you need to edit, and the location of the Java options varies depending on the application server you want to integrate with. NOTE: The list of examples is not exhaustive and does not cover every application server that you can integrate with the APM agent. This list may be expanded at any time. Modify JBoss startup scripts domain.bat on Windows - Java 1.6 domain.bat on Windows - Java 1.5 Integrate with WebSphere WebSphere on Windows WebSphere on UNIX Modify JBoss startup scripts The options you provide to the JBoss startup scripts depend on which Java version you are running. domain.bat on Windows - Java 1.6 domain.bat on Windows - Java 1.5 domain.bat on Windows - Java 1.6 You have two options: 1 Add the option exactly as provided by the installer. See lines 5 in the example. Example: 1: :RESTART 2: "%JAVA%" %PROCESS_CONTROLLER_JAVA_OPTS% ^ 3: "-Dorg.jboss.boot.log.file=%JBOSS_LOG_DIR%\process-controller.log" ^ 4: "-Dlogging.configuration=file:%JBOSS_CONFIG_DIR%/logging.properties" ^ 5: -javaagent:"<install_path>\agents\javaee\lib\foglightapm-agent.jar" ^ 6: -jar "%JBOSS_HOME%\jboss-modules.jar" ^ The carets (^) at the end of each line are only required if you want to match the syntax of your existing script. OR 2 Paste the options provided into a new environment variable and add the variable to the Java command. See line 1 in the example. NOTE: Ensure that the variable name you use is not already used elsewhere in the script. 24
Example: 1: set DELL_APM_OPTS= -javaagent:"<install_path>\agents\javaee\lib\foglightapmagent.jar" 2: :RESTART 3: "%JAVA%" %PROCESS_CONTROLLER_JAVA_OPTS% %DELL_APM_OPTS% ^ 4: "-Dorg.jboss.boot.log.file=%JBOSS_LOG_DIR%\process-controller.log" ^ domain.bat on Windows - Java 1.5 You have two options: 1 Add the options exactly as provided by the installer. See lines 5 and 6 in the example. Example: 1: :RESTART 2: "%JAVA%" %PROCESS_CONTROLLER_JAVA_OPTS% ^ 3: "-Dorg.jboss.boot.log.file=%JBOSS_LOG_DIR%\process-controller.log" ^ 4: "-Dlogging.configuration=file:%JBOSS_CONFIG_DIR%/logging.properties" ^ 5: -Xbootclasspath/p:"<install_path>\agents\JavaEE\<version>\lib\performasureagent.jar" ^ 6: -javaagent:"<install_path>\agents\javaee\<version>\lib\performasure-agent.jar" ^ 7: -jar "%JBOSS_HOME%\jboss-modules.jar" ^ The carets (^) at the end of each line are only required if you want to match the syntax of your existing script. OR 2 Paste the options provided into a new environment variable and add the variable to the Java command. See line 1 in the example. NOTE: Ensure that the variable name you use is not already used elsewhere in the script. Example: 1: set DELL_APM_OPTS=-Xbootclasspath/p:"<install_path>\agents\JavaEE\<version>\lib\perform asure-agent.jar" -javaagent:"<install_path>\agents\javaee\<version>\lib\performasure-agent.jar" 2: :RESTART 3: "%JAVA%" %PROCESS_CONTROLLER_JAVA_OPTS% %DELL_APM_OPTS% ^ 4: "-Dorg.jboss.boot.log.file=%JBOSS_LOG_DIR%\process-controller.log" ^ Integrate with WebSphere WebSphere on Windows You have three options: 1 Use the IntegrateAgain.cmd script to integrate a single WebSphere Windows Service. See Integrate with an application server for details. OR 2 Use the IntegrateAgain.cmd script to integrate a single WebSphere profile. See Integrate with an application server for details. 25
OR 3 Manually insert the integration options into the startup scripts to integrate all profiles and all services connected to a WebSphere installation: 1 Install the Foglight APM agent. You can include spaces in the installation path, but parentheses () are not allowed. 2 Locate <WAS_HOME>\bin\setupCmdLine.bat and open the file in a text editor. 3 Locate the line containing the text :NO_SET_USER_INSTALL_ROOT 4 Below that line, add the integration options for Java 1.6+ provided by the installer to the USER_INSTALL_PROP environment variable: Example: 1: set FOGLIGHT_JAR=C:\FoglightAPM\lib\foglightapm-agent.jar 2: if exist "%FOGLIGHT_JAR%" ( 3: set USER_INSTALL_PROP=%USER_INSTALL_PROP% -javaagent:"%foglight_jar%" 4: ) NOTE: Do not use quotes in line 1, even if the path contains spaces. WebSphere on UNIX You have two options: 1 Use the IntegrateAgain.sh script to integrate a single WebSphere profile. See Integrate with an application server for details. NOTE: IntegrateAgain.sh handles spaces in the installation path automatically OR 2 Manually insert the integration options into the startup scripts to integrate all profiles and all services connected to a WebSphere installation. 1 Install the Foglight APM agent. IMPORTANT: Do not use spaces in the installation path. 2 Locate <WAS_HOME>/bin/setupCmdLine.sh and open the file in a text editor. 3 At the very end of the file, add the integration options for Java 1.6+ provided by the installer to the USER_INSTALL_PROP environment variable: Example: 1: FOGLIGHT_JAR=/opt/FoglightAPM/lib/foglightapm-agent.jar 2: if [-f "$FOGLIGHT_JAR" ]; then 3: USER_INSTALL_PROP="${USER_INSTALL_PROP} -javaagent:${foglight_jar}" 4: fi 26
5 Installing the APM PHP Agent The Foglight APM SaaS PHP trace agent is a deployable agent for PHP application servers that collects headers and metrics about each HTTP/HTTPS request made to a PHP app. The PHP agent also performs detailed tracing of the function calls that occur within the PHP script. All of this information is forwarded to Foglight APM SaaS for correlation and display. Key features of the PHP agent Collects back-end response time for each PHP transaction. Generates SQL call trees for MySQL that include the database name, host, port, SQL statement, and function call that triggered the SQL access. These details are all broken down by execution times and/or count. Generates pivots by browser type, Client OS, geolocation, or any of the other dimensions (pivots) available in Foglight APM SaaS. Browser instrumentation is auto-injected to collect front-end navigation times to get a true end-to-end picture of the user s response. Collects Top Methods or Top SQL statements by either execution time or frequency. Capture PHP exceptions or errors, and enables you to see the line of code where they were triggered. A license key is generated automatically when you download the APM installer. This key is bound to your APM Agent. Foglight APM SaaS verifies the license key during the installation process. Supported Platforms The section lists the PHP Versions, OS Platforms, and Web Servers that are supported by the APM PHP agent. PHP Versions The following PHP versions are supported: 5.2 5.3 5.4 5.5 5.6 OS Platforms The following OS platforms are supported 27
Table 1. Supported OS platforms OS 64-bit support 32-bit support Cent OS 5 & 6 Y Y Cent OS 7 Y N Debian 6, 7 Y Y Fedora 20, 21 Y Y opensuse 12, 13 Y Y Red Hat Enterprise Linux (RHEL) 5, 6 Y Y Red Hat Enterprise Linux (RHEL) 7 Y N SuSe SLES 10, 11 SP3 Y Y Ubuntu 12, 14 Y Y Web Servers The following web servers are supported: Apache HTTP Server versions 2.4.x and 2.2.x Any server using PHP-FPM Install the APM PHP agent The Foglight APM SaaS agent installer is distributed as a tarball file (tgz). You must unpack the file and run the included install script which will walk you through the installation process. To install the APM PHP agent: 1 On the Monitor a New Application page, type a name for your application in the Application Name box. 2 To monitor PHP, ensure that the App Server Agent tab is selected. 3 Select the Application Platform Type: PHP. 4 Select your Install OS, and the OS Distribution. See Supported Platforms for details about supported OS platforms. 5 Click Download Installer Agent. 6 Copy the installation package to the application server. 7 Unpack the installer using tar. For example: tar -zxf setupapmsaasphp--<version>-<os Type>_<bits>-<YourAppName>.tgz 8 From the command-line, run the install.sh script using sudo to start the interactive installer. The install script requires elevated privileges to ensure the background services are auto-started correctly. For example: sudo./install.sh 9 Follow the steps of the installation wizard. See Interactive Configuration for details. 10 After the installation completes, restart your PHP application server. 11 Monitor your application performance. See the Foglight Application Performance Monitoring SaaS Edition User Guide for an overview, as well as tasks and workflows. 28
Interactive Configuration The interactive installer guides you through the configuration of the APM PHP agent. To configure the APM PHP agent: 1 On the first page of the interactive installer, specify the installation directory for the APM PHP agent. 2 Optional Provide proxy server details for connecting to Foglight APM SaaS through a proxy. 3 Select the PHP runtime configurations to instrument. The installer discovers php.ini files and automatically adds them to the initial list. The installer also attempts to auto-detect the PHP version and threading. If these values are not set, they must be configured for each PHP runtime configuration before continuing. PHP version and threading can be set manually from a list or you can select a PHP binary file. The installer determines the PHP version and threading to use based on the selected PHP binary file. NOTE: Auto discovery only searches /opt, /usr/local, /etc and the user s home directory. 4 Select each Apache and/or PHP-FPM server instance that you want to monitor. The installer discovers all actively running Apache or FPM instances and adds them to the initial list. Non-running Apache or FPM configurations can be found under the Discover Apache and Discover PHP-FPM options respectively. NOTE: Auto discovery only searches /opt, /usr/local, /etc, and user s home directory. 5 By default, the Foglight services are registered to automatically start on boot. If you disable automatic startup, a script is created that you can use to later enable autostart on boot. This script requires root privileges, and is installed at <install_path>/enable_auostart.sh. 6 Use the Configure User for Background services option to control which user the Foglight background services run under. By default, this is either the daemon user (if available), or the current user (if you are running the installer as a non-root user). 7 Review the installation options you have selected. No changes are made until you confirm the options and the installation begins. During the installation process, changes may be made to the selected PHP runtime configuration, Apache configuration, and PHP-FPM configuration files. Backup copies of the all files are created before any changes are made. Details of the changes are written to the installation log. Instrumenting your PHP application To monitor your PHP application, the APM PHP agent must be configured to load the Foglight APM PHP extension. This is done by adding an entry to the php.ini file for your PHP application. This change is made as part of the installation process described in Interactive Configuration. The installer searches the /opt, /etc, and /usr/local directories (and associated subdirectories) for any php.ini files, and prompts you to select the file to update. Manual instrumentation If for some reason the php.ini file is not updated automatically, you can manually update your file by adding an entry that looks like: extension=<install_path>/traceagents/php/foglightapm_php_<version>.so Extensions for all supported versions of PHP can be found in the options directory: <install_path>/traceagents/php NOTE: Any changes to the php.ini file take effect after you restart the web server. 29
Default Installation Locations By default, the Foglight APM PHP Agent files are placed in the following locations: /opt/foglight/apm/traceagents To change this directory, specify an optional command-line argument when installing: --installdir <install_path> Example: sudo./install.sh --silent --installdir /opt/myinstall Integrate with a second PHP app on the same host Use this procedure to integrate with a PHP app of a different type on a host machine where you have already integrated one PHP app. To integrate with a different PHP app on the same machine: 1 Locate the PHP app runtime configuration (php.ini). 2 Locate the PHP binary for that runtime configuration (php). 3 Run the following script using the information from step 1 and step 2: <install_path>/traceagents/php/add_php_app.sh --php-ini /path/to/php.ini --phpbinary /path/to/php 4 Restart your PHP app server. Example: /opt/foglight/traceagents/php/add_php_app.sh --php-ini /opt/wordpress/php/etc/php.ini --php-binary /opt/wordpres/php/bin/php Silent Installation You can install the APM PHP agent without using the interactive installer by specifying the silent option. The basic command is sh install.sh --silent. There are additional options for specifying paths to binaries and proxy settings. NOTE: The install script requires elevated privileges (sudo) to ensure the background services are autostarted correctly. Table 2. Silent installation options for the APM PHP agent. Option long name --silent --installdir <dir> --host-display-name <name> --proxy <host>:<port> --proxy-user <user> --proxy-pass <password> --autostart <enabled disabled> Description Skips the interactive prompts and uses the commandline options only. Sets the installation directory for the APM agents. Provides an alternate display name for the monitoring agents. Enables the APM agent to use a proxy at the specified host and port address. Sets the proxy username. Sets the proxy password. Start on boot Trace Upload daemon : (enabled disabled) [default=enabled] 30
Table 2. Silent installation options for the APM PHP agent. Option long name --run-user The user name under which background daemons run. --disable-containers <enabled disabled> Disables container monitoring (Apache or FPM). By default this option is enabled. --php-ini <path_to_php_ini> Sets the path to the PHP app runtime configuration (php.ini). --php-binary <path_to_php> Full path to the php binary used to determine the PHP version and threading for the Trace module (php). --php-version <5.2 5.3 5.4 5.5 5.6> Explicitly sets the PHP version for the Trace module (5.2 5.3 5.4 5.5 5.6). --php-threading <enabled disabled> Explicitly sets PHP threading for the Trace module (enabled disabled). --apache-conf <httpd.conf> Optional Sets the path of httpd.conf or apache2.conf file. --apache-ports <apache ports> Optional Sets the apache listening port. Ports should be comma-separated ( "," ). --fpm-conf <php-fpm.conf> Optional Sets the path of php-fpm.conf file. --fpm-prefix <php prefix> Optional Sets the php installation prefix. --proxy-domain <domain> Sets the proxy user domain. --proxy-preserve When updating an existing installation (-u), this command tells the agent to ignore any proxy options that are specified on the command-line, including empty options. This effectively removes existing proxy settings during the update. This option also disables the communication check. To instrument all PHP instances on the server in silent mode: 1 From the command-line, run the installer with the silent option. Example: sudo./install.sh --silent 2 Restart your PHP application servers. To instrument a single PHP instance on the server in silent mode: 1 From the command-line, run the installer with the --php-ini. For all PHP instances, you must specify the PHP version and threading in one of two ways: Use --php-binary to select a PHP binary that can be used to determine PHP version and threading. or Use both --php-version and --php-threading combo to explicitly set the PHP Version and Threading. These version and threading options affect all subsequent --php-ini flags. 2 In all cases, restart your PHP application server after running the install.sh script. Examples: Description sudo./install.sh --silent --php-binary <path_to_php_binary> --php-ini <path_to_php_ini_1> --php-ini <path_to_php_ini_2> sudo./install.sh --silent --php-version <5.3 5.4 5.5 5.6> --php-threading <enabled disabled> --php-ini <path_to_php_ini_1> --php-ini <path_to_php_ini_2> 31
sudo./install.sh --silent --php-version 5.3 --php-threading enabled --php-ini <path_to_php_ini_5.3> --php-version 5.5 --php-ini <path_to_php_ini_5.5> Uninstallation To remove the PHP agent installation: 1 Run the uninstall.sh script. Example: /<install_path>/uninstall.sh The default location is /opt/foglight/apm/uninstall.sh. 2 Follow the instructions on the command-line to complete the uninstallation. Update the proxy server settings After you have installed the APM PHP agent you may need to update the proxy settings for the agent. To update the proxy server settings: 1 Edit the file located at: <install_path>/traceagents/config/uploadmgr/config.ini 2 Change the following settings, as necessary, to configure a proxy: ProxyAuthType ProxyType ProxyIP ProxyPort ProxyUser ProxyPassword 3 Save the changes to the file. 4 Restart the uploadmgr using the following command: rcuploadmgr restart The new proxy settings are now in effect. 32
Installing the APM.NET Agent 6 The Foglight APM SaaS.NET agent collects transaction data and performance metric of your Microsoft.NET applications running in IIS. The collected data is forwarded to Foglight APM SaaS for correlation and display. Key features of the.net agent Collects back-end response time and count for.net transactions running in Microsoft IIS Collects call tree transaction data, including: Method execution time and count Exception data SQL calls made to the database (data source, SQL statement and optionally SQL parameters) Collect performance counter metrics for.net components such as application pools Optional injection of browser instrumentation to collect front-end navigation times A license key is generated automatically when you download the APM installer. This key is bound to your APM Agent. Foglight APM SaaS verifies the license key during the installation process. IMPORTANT: If you intend to install the APM.NET agent on the same host where a previous version of the Foglight for Microsoft.NET agent is alreay installed, you must first uninstall the older version before installing the APM.NET agent. Supported platforms and versions The APM.NET agent monitors applications on the following platforms and of the stated versions: Table 1. Supported platforms and versions.net Framework Version Windows Server 2008 (IA32, x86-64) Windows Server 2008 R2 (IA32, x86-64) Windows Server 2012 (x86-64) IIS 7.0 IIS 7.5 IIS 8.0 IIS 8.5 2.0, SP1, SP2 Y Y Y Y 3.0, SP1, SP2 Y Y Y Y 3.5, SP1 Y Y Y Y 4.0 Y Y Y Y 4.5, 4.5.1, 4.5.2 Y Y Y Y Windows Server 2012 R2 (x86-64) 33
Install the APM.NET agent IMPORTANT: If you intend to install the APM.NET agent on the same host where a previous version of the Foglight for Microsoft.NET agent is alreay installed, you must first uninstall the older version before installing the APM.NET agent. The Foglight APM SaaS agent installer is distributed as a zip file. Unzip the file and run the included installer (.exe file), which will walk you through the installation process. To install the APM PHP agent: 1 On the Monitor a New Application page, type a name for your application in the Application Name box. 2 To monitor.net, ensure that the App Server Agent tab is selected. 3 Select the Application Platform Type:.NET. 4 Select your Install OS. See Supported platforms and versions for details about supported OS platforms. 5 Click Download Installer Agent. 6 Unzip the downloaded file to a temporary directory. 7 Double-click the.exe install file to start the installation. 8 Follow the steps of the installation wizard. See Interactive Configuration for details. 9 After the installation completes, restart your.net application server by performing an iisreset. 10 Monitor your application performance. See the Foglight Application Performance Monitoring SaaS Edition User Guide for an overview, as well as tasks and workflows. Interactive Configuration The interactive installer guides you through the configuration of the APM.NET agent. To configure the APM.NET agent: 1 Read the introduction and accept the license agreement. 2 On the choose Install Location page, specify the installation directory for the APM.NET agent. 3 Optional Provide proxy server details for connecting to Foglight APM SaaS through a proxy. 4 Type the tier name for the application. 5 By default, the.net agent is configured to install as a Windows service. This enables the agent to start automatically whenever the Windows OS starts. To disable this option, clear the check box labelled Yes, installapm Agent as a Windows service. 6 Optional By default, if you enable the.net agent to run as a Windows service, the agent Windows service is configured to start automatically at the end of the installation. To disable this option, clear the check box labelled Start APM Agent Windows Service at the end of the installation. 7 Optional By default, local system monitoring is enabled. This option configures the APM agent to monitor your local system environment to track and analyze any performance issues. To disable this option, clear the check box labelled Enable local system monitoring. 8 On the Summary page, review your selections and click Finish. 9 After the installation finishes, perform an iisreset from the command-line. 34
Command-line installation You can also install the APM.NET agent from the command-line by running the installer executable with the --headless option. Follow the prompts on the command-line to specify options and required information. After the installation finishes, perform an iisreset to ensure the settings take effect. Instrumenting your.net application The installation process automatically integrates the.net agent with your Microsoft IIS. After the installation finishes, perform an iisreset to ensure the settings take effect. Silent Installation You can install the APM.NET agent without using the interactive installer by starting the installation from the command-line and specifying the silent option. The basic command is: APMSaaSDotNET-<version>-windows-<OS-bits>.exe --silent --installdir <dir> Table 2. Silent installation options for the APM.NET agent. Option long name --installdir <dir> --host-display-name <name> --silent --proxy <host>:<port> --poxy-user <user> --proxy-pass <password> --proxy-domain <domain> --no-service --no-start-on-exit --tier <name> Description Sets the installation directory for the APM agents. Provides an alternate display name for the monitoring agents. Installs the agent in silent (non-interactive) mode. Default values are used unless explicitly overridden on the command-line. Enables the APM agent to use a proxy at the specified host URL and port address. Sets the user name for the proxy connection. Sets the password for the proxy connection. Sets the Windows domain for the proxy connection. Disables the installation of the Foglight Agent Manager (FglAM) Windows Service. Prevents the Foglight Agent Manager process from starting automatically after the installation completes. Specifies the tier name for the application. For example: -DTierNAme=MyWebTier Uninstallation To remove the.net agent installation: 1 In the agent installation folder, locate and run Uninstall.cmd. 2 Perform an iisreset. 35
About Dell Dell listens to customers and delivers worldwide innovative technology, business solutions and services they trust and value. For more information, visit www.software.dell.com. Contacting Dell Technical support: Online support Product questions and sales: (800) 306-9329 Email: info@software.dell.com Technical support resources Technical support is available to customers who have purchased Dell software with a valid maintenance contract and to customers who have trial versions. To access the Support Portal, go to http://software.dell.com/support/. The Support Portal provides self-help tools you can use to solve problems quickly and independently, 24 hours a day, 365 days a year. In addition, the portal provides direct access to product support engineers through an online Service Request system. The site enables you to: Create, update, and manage Service Requests (cases) View Knowledge Base articles Obtain product notifications Download software. For trial software, go to Trial Downloads. View how-to videos Engage in community discussions Chat with a support engineer 36