Foglight Application Performance Monitoring SaaS...

Foglight™ Application Performance Monitoring SaaS EditionGetting Started Guide

Copyright© 2016 Dell Inc. All rights reserved.

This product is protected by U.S. and international copyright and intellectual property laws. Dell™, the Dell logo, Foglight, IntelliProfile, NetVault, OpenManage, PerformaSure, PowerEdge, Tag and Follow, and Toad are trademarks of Dell Inc. in the United States and/or other jurisdictions. "Apache HTTP Server", Apache, "Apache Tomcat" and "Tomcat" are trademarks of the Apache Software Foundation. Google is a registered trademark of Google Inc. Android, Chrome, Google Play, 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. Fedora and the Infinity design logo are trademarks of Red Hat, Inc. Microsoft, .NET, Active Directory, Internet Explorer, Hyper-V, SharePoint, Silverlight, SQL Server, Visual Basic, 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. OpenSUSE, SUSE, and YAST are registered trademarks of SUSE LCC 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. Vormetric is a registered trademark of Vormetric, Inc. Intel, Itanium, Pentium, and Xeon are trademarks of Intel Corporation in the U.S. and/or other countries. Debian is a registered trademark of Software in the Public Interest, Inc. OpenStack is a trademark of the OpenStack Foundation. All other marks and names mentioned herein may be trademarks of their respective companies.

Foglight APM SaaS Edition Getting Started Guide Updated - January 2016

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.

Contents

Foglight Application Performance Monitoring SaaS Edition Getting Started Guide

3

Introducing Foglight APM SaaS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Getting Started with Foglight APM SaaS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Observe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Ad-hoc Analysis: the Investigate Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Setting Up Foglight APM SaaS Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Validated web browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Instrument Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Generate a support bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Installing the APM Java Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Validated platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

Install the APM Java agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Integrate with an application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Known issues with APM Java Agent integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Upgrade the APM Java agent and re-integrate your application server . . . . . . . . . . . . .20

Uninstall the APM Java agent and undo the application server integration . . . . . . . . . . .21

Update the proxy server settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Modify your Java App Server Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Modify JBoss startup scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Integrate with WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Installing the APM PHP Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Install the APM PHP agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27Instrumenting your PHP application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Silent Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Update the proxy server settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Installing the APM .NET Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Install the APM .NET agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33Instrumenting your .NET application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Silent Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

About Dell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

1

Introducing Foglight APM SaaS

Foglight Application Performance Monitoring SaaS Edition 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 StartGet 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 SaaSInstalling 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.

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

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.


4

• 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 pageThe 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.

ObserveThe 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


5

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


6

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)

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 ActivityUse the Investigate activity to:

TIP: To view a complete list of dimensions, select the Explore tab.


7

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

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.

TIP: If you drilled down to this view from the Monitor Activity page, this query may be pre-populated.


8

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.


9

http://www.foglight.com/

2

Setting Up Foglight APM SaaS Monitoring

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 Select the Application Platform type.

b Select your your OS platform.

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

Validated web browsersThe 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.

Validated browsers

• Internet Explorer 9, 10, and 11 for desktop environments

• Patched according to Microsoft® Security Bulletin September 2014

Table 1. Where to find additional information about steps and options.

Tell me more about... Answer

Which web browsers I can use to access Foglight APM SaaS Edition

See Validated web browsers

APM Java agent See Installing the APM Java Agent

APM PHP agent See Installing the APM PHP Agent

APM .NET agent See Installing the APM .NET Agent

Mobile Device Instrumentation See Instrument Mobile Devices

Troubleshooting my installation See Troubleshooting installation

Getting help from Support See Generate a support bundle

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.


10

http://documents.software.dell.com/DOC198304

http://www.foglight.com/

• 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 KeysA 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 DevicesWhen 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 AndroidTM platforms

• For IOS® platforms


11

http://documents.software.dell.com/Foglight%20Application%20Performance%20Monitoring%20SaaS%20Edition/Current/Mobile%20App%20Developer%20Guide%20for%20Android%E2%84%A2%20Platforms/

http://documents.software.dell.com/Foglight%20Application%20Performance%20Monitoring%20SaaS%20Edition/Current/Mobile%20App%20Developer%20Guide%20for%20iOS%C2%AE%20Platforms/

Generate a support bundleIf 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 Click Yes to download the support bundle contents.

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

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.

NOTE: It takes several minutes to generate and upload the support bundle.


12

3

Installing the APM Java Agent

The Foglight APM SaaS Java Agent monitors the availability and performance of your JavaTM 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 serversThe following sections and topics provide information about supported application servers, JVMs, and OS platforms.

• Supported operating systems

• Supported JVMs

Supported operating systemsThe following operating systems are supported for Foglight APM SaaS:


13

Supported JVMsJVM s of version 1.5 through 1.8 are supported, regardless of the application server the JVM is running on.

The following specific JVMs have been tested and validated for the APM agent:

• Oracle® JavaTM 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 platformsFoglight 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

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

Server 2003

Server 2008

IA-32

x86-64

Server 2008 R2

Server 2012

Server 2012 R2

x86-64

Novell® SUSE Linux® Enterprise Server

10

11

IA-32

x86-64

Oracle® Linux® 4.x

5.x

6.x

IA-32

x86-64

Red Hat® Enterprise Linux® AP/Server 5.x

6.x

7.x

IA-32

x86-64

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.


14

• 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



IBM WebSphere• WebSphere® 8.5.5

• WebSphere® 8.5

• WebSphere® 8.0

• WebSphere® 7.0

Red Hat JBoss• JBoss® WildFly 8.[0-2]

• 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]

NOTE: In this release, support for WildFly does not include JavaScript instrumentation injection for end user monitoring or HTTP POST parameter collection.


15

GlassFishSupported 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 GeronimoSupported 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.

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

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.

Table 3. 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.


16

-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 4. Optional Installation settings.


-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 5. Advanced installation options.


-D <system-property>

Optional system property to pass to the embedded installer.

-n --host-display-name <name>

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.

Table 3. Installer options.



17

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

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.

Why is my APM Java agent installation failing on Ubuntu?

In Ubuntu 14.10 (64-bit), the APM Saas Java agent installation sometimes fails with the error: “Unable to find valid certification path to the requested target” (endpoint is https://api/foglight.com). This happens because of a known Ubuntu issue where the Java does not recognize the top level CA certificate as valid, so the /etc/ssl/certs/java/cacerts directory is not created.

To complete the installation, use one of these workarounds.

Workarounds

• Run the following command to create the /etc/ssl/certs/java/cacerts directory:

sudo /var/lib/dpkg/info/ca-certificates-java.postinst configure

For more information about this command and the Ubuntu known issue, see https://bugs.launchpad.net/ubuntu/+source/ca-certificates-java/+bug/1396760

• If you cannot fix your JDK certificate right now, bypass the installation check with the Foglight Management Server by running the APM Java agent installation with the optional --no-comm-check command:

java -jar setupAPMSaaSJava-<version>-linux-x86_64-MyApplication.jar -l

If you need assistance with troubleshooting your installation, contact Support.

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.


18

Integrate with an application serverTo 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:

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\performasure-bootstrap.jar ^3: -javaagent:<install_path>\agents\JavaEE\<version>\lib\performasure-agent.jar

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.


• Workaround for GlassFish 4.1

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.


19

I am trying to run Tomcat with the APM Java agent, but the agent does not start and no log files are created.


• Workaround for Tomcat with java.endorsed.dirs=<tomcat_home>\bin system property

Known issues with APM Java Agent integrationThe 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.8Apache 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:

set GERONIMO_TMPDIR=%GERONIMO_HOME%/%GERONIMO_TMPDIR%

Workaround for GlassFish 4.1In most cases, the APM Java agent no longer requires that you specify -Xbootclasspath/p:”<install_path>\agents\JavaEE\<version>\lib\performasure-agent.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 propertyIf 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 re-integrate your application serverThe 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 Run the PrepareForLocalUpgrade.cmd/sh script.


20

Automatically integrate with an app serverUse 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.

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 integrationThis 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 Edit the Java startup commands for your application and remove the Java options that you added during the agent installation. The options that you added depend on the JVM version that your appserver uses.

For example:

Java 1.6 or later:

-javaagent:"<install_path>\agents\JavaEE\lib\foglightapm-agent.jar"

Java 1.5 and some Java 1.6:

-Xbootclasspath/p:<install_path>\agents\JavaEE\<version>\lib\performasure-bootstrap.jar

-javaagent:<install_path>\agents\JavaEE\<version>\lib\performasure-agent.jar

2 Stop all application servers integrated with the Foglight APM SaaS installation.

3 Locate the uninstall script in the APM agent installation directory (for example, C:\Program Files\Common Files\Dell\APM Agent\).

4 Run the uninstallation script and follow the prompts.

• On Windows® platforms: run the Uninstall.cmd script.

• On UNIX®/Linux® platforms: run the Uninstall.sh script.

5 Restart the application servers, as necessary.

Update the proxy server settingsAfter you have installed the APM Java agent, and updated it with additional integrations, you may need to update the proxy settings for the agent.


21

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.


22

4

Modify your Java App Server Startup

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.

• Modify JBoss startup scripts

• domain.bat on Windows - Java 1.6


• Integrate with WebSphere

• WebSphere on Windows

• WebSphere on UNIX

Modify JBoss startup scriptsThe options you provide to the JBoss startup scripts depend on which Java version you are running.



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: :RESTART2: "%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: 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.

NOTE: Ensure that the variable name you use is not already used elsewhere in the script.


23

Example:

1: set DELL_APM_OPTS= -javaagent:"<install_path>\agents\JavaEE\lib\foglightapm-agent.jar"2: :RESTART3: "%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


1 Add the options exactly as provided by the installer. See lines 5 and 6 in the example.

Example:

1: :RESTART2: "%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\performasure-agent.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.

Example:

1: set DELL_APM_OPTS=-Xbootclasspath/p:"<install_path>\agents\JavaEE\<version>\lib\performasure-agent.jar" -javaagent:"<install_path>\agents\JavaEE\<version>\lib\performasure-agent.jar"2: :RESTART3: "%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.

NOTE: Ensure that the variable name you use is not already used elsewhere in the script.


24

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.jar2: if exist "%FOGLIGHT_JAR%" (3: set USER_INSTALL_PROP=%USER_INSTALL_PROP% -javaagent:"%FOGLIGHT_JAR%"4: )

WebSphere on UNIX


1 Use the IntegrateAgain.sh script to integrate a single WebSphere profile. See Integrate with an application server for details.

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.

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.jar2: if [-f "$FOGLIGHT_JAR" ]; then3: USER_INSTALL_PROP="${USER_INSTALL_PROP} -javaagent:${FOGLIGHT_JAR}"4: fi

NOTE: Do not use quotes in line 1, even if the path contains spaces.

NOTE: IntegrateAgain.sh handles spaces in the installation path automatically

IMPORTANT: Do not use spaces in the installation path.


25

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 PlatformsThe 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


26

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 agentThe 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:


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.


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.


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


27


Interactive ConfigurationThe 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.

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.

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 applicationTo 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: Auto discovery only searches /opt, /usr/local, /etc and the user’s home directory.

NOTE: Auto discovery only searches /opt, /usr/local, /etc, and user’s home directory.

NOTE: Any changes to the php.ini file take effect after you restart the web server.


28

Default Installation LocationsBy 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 hostUse 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 --php-binary /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 InstallationYou 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 auto-started correctly.

Table 7. Silent installation options for the APM PHP agent.

Option long name Description

--silent Skips the interactive prompts and uses the command-line options only.

--installdir <dir> Sets the installation directory for the APM agents.

--host-display-name <name> Provides an alternate display name for the monitoring agents.

--proxy <host>:<port> Enables the APM agent to use a proxy at the specified host and port address.

--proxy-user <user> Sets the proxy username.

--proxy-pass <password> Sets the proxy password.

--autostart <enabled|disabled> Start on boot Trace Upload daemon : (enabled|disabled) [default=enabled]


29

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:

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>

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

Table 7. Silent installation options for the APM PHP agent.



30

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.

3 Remove any manually added entries in the php.ini that reference the FoglightAPM_php_<version>.so file.

4 After uninstalling the PHP agent, restart your PHP application.

Update the proxy server settingsAfter 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.


31

6

Installing the APM .NET Agent

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.

Supported platforms and versions The APM .NET agent monitors applications on the following platforms and of the stated versions:

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.

Table 8. 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)

Windows Server 2012 R2 (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


32

Install 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:


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.


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.


Interactive ConfigurationThe 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.

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.


33


Command-line installationYou 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 InstallationYou 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>

Uninstallation

To remove the .NET agent installation:

1 In the agent installation folder, locate and run Uninstall.cmd.

2 Perform an iisreset.

Table 9. Silent installation options for the APM .NET agent.


--installdir <dir> Sets the installation directory for the APM agents.

--host-display-name <name> Provides an alternate display name for the monitoring agents.

--silent Installs the agent in silent (non-interactive) mode. Default values are used unless explicitly overridden on the command-line.

--proxy <host>:<port> Enables the APM agent to use a proxy at the specified host URL and port address.

--poxy-user <user> Sets the user name for the proxy connection.

--proxy-pass <password> Sets the password for the proxy connection.

--proxy-domain <domain> Sets the Windows® domain for the proxy connection.

--no-service Disables the installation of the Foglight Agent Manager

(FglAM) Windows® Service.

--no-start-on-exit Prevents the Foglight Agent Manager process from starting automatically after the installation completes.

--tier <name> Specifies the tier name for the application. For example: -DTierNAme=MyWebTier


34

About Dell

Dell listens to customers and delivers worldwide innovative technology, business solutions, and services they trust and value. For more information, visit http://www.software.dell.com.

Contacting DellFor sales or other inquiries, visit http://software.dell.com/company/contact-us.aspx or call 1-949-754-8000.

Technical support resourcesechnical 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 https://support.software.dell.com.

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 Support Portal provides direct access to product support engineers through an online Service Request system.

The Support Portal enables you to:

• Create, update, and manage Service Requests (cases).

• View Knowledge Base articles.

• Obtain product notifications.

• Download software. For trial software, go to http://software.dell.com/trials.

• View how-to videos.

• Engage in community discussions.

• Chat with a support engineer.


35

http://software.dell.com/company/contact-us.aspx

https://support.software.dell.com/

http://software.dell.com/trials/

http://software.dell.com/

Foglight Application Performance Monitoring SaaS...

Documents

Transcript of Foglight Application Performance Monitoring SaaS...