Install the Apache Agent

Related pages:

To monitor the performance of your Apache HTTP Server, IBM HTTP Server (IHS) or Oracle HTTP Server, install the AppDynamics Apache Agent on the servers where you run Apache, IHS or OHS. The agent instruments the Apache server and sends performance data to a Java proxy, which in turn sends data to the AppDynamics Controller.

If you are using the Apache Monitoring Extension with the Machine Agent, you can continue to use it. You may need to restart the Machine Agent after installing the Apache Agent.

Before Starting

Ensure that the web server version and operating system are supported. See Supported Apache Web Servers.

Also verify the following requirements on the machine on which you are installing the agent:

Perform the installation under the same user and group that Apache is using when spawning worker processes and threads.
Ensure that the machine on which the agent runs has random or urandom set appropriately. This is because certain functions in the Apache Agent are dependent on random number generation.
Else, it can lead to abrupt behavior such as log files or directories may not be created, nothing is reported from the agent to the Controller, and so on.
Ensure that the ulimit setting for open file descriptors is set such that neither the Apache worker process or the Proxy task does not exceed it to avoid resource contention. **
Check the open file descriptor limit of the userid that the proxy and/or Apache worker process must have:
For the MPM_Worker mode, the number of file descriptors must be set using the following calculation: 1024 + ServerLimit + (2 * ServerLimit * ThreadsPerChild).
For all other modes, you must set the number of file descriptors using the calculation: (Total number of concurrently active Apache workers * 2) + 1024.
The open file descriptor setting can be found in /etc/security/limits.conf, but the setting requires a host reboot to become effective, or set through the "ulimit -n" command for the current userid's session only.
Check for modules with dependencies on libstdc++.so.5. See Special Considerations for Apache Web Servers with libstdc++.so.5 Modules. This is most common with IHS and OHS.
Ensure that the machine on which the agent runs has a locale environment set properly. As some functions in the Apache Agent have a dependency on the locale it could lead to a crash otherwise.
Based on the agent's requirement, you can select one of the following and set the environment variable as:

export LANG=en_US.UTF-8
export LANGUAGE=$LANG
export LC_ALL=$LANG

CODE

Or

export LANG=en_US.UTF-8

CODE

Or

export LC_ALL=C

CODE

Download and Install the Apache Agent

To guarantee performance and stability, you should install one agent for each Apache instance. Do not exceed two Apache instances per agent.

Download the Apache Agent from the Getting Started wizard or https://accounts.appdynamics.com/downloads.
Extract the agent to /opt.
```
tar -xzvf ./appdynamics-sdk-native.<version>.tar.gz -C /opt
```
CODE
The agent installs to /opt/appdynamics-sdk-native. This is the <agent_install_directory>. If you are installing multiple agents, you must create separate install directories for each agent.
Grant the Apache, IHS, or OHS owner read and write permissions to the logs directory: <agent_install_directory>/logs.
Run install.sh. This script installs the agent proxy.
```
<agent_install_directory>/install.sh 
```
CODE
For an agent to monitor your Apache instance, you must launch the proxy. If you are monitoring multiple Apache instances, we recommend that you manually launch each proxy, and set AppDynamicsLaunchProxy to NO for every Apache instance.
The next step is to create the agent configuration file and configure the agent.

For cURL installation, see Download AppDynamics Software.

Configure the Apache Agent

Create a configuration file for the AppDynamics Apache Web Server agent, such as appdynamics_agent.conf, in the Apache, IHS, or OHS configuration directory. For example:
```
touch /etc/<path_to_webserver_dir>/conf/appdynamics_agent.conf
```
In the appdynamics_agent.conf file, configure the following settings. If you have multiple agents installed, you must edit the appdynamics_agent.conf file for each agent, specifying which directory the agent load modules are located. Ensure that each Apache instance references a different appdynamics_agent.conf file, and that each file specifies a different agent install directory.

For multiple Apache web server instances that share the same Apache Agent, ensure that Comm dirs, set using AppdynamicsProxyCommDir directive, for each proxy process is different. Also ensure that the node names in each server configuration file, appdynamics_agent.conf, are also different.

- LoadFile: Loads the AppDynamics Agent SDK shared library. Assuming the agent is installed in /opt, the setting would be
  /opt/appdynamics-sdk-native/sdk_lib/lib/libappdynamics_native_sdk.so. Required.
  For example:
```
LoadFile /opt/appdynamics-sdk-native/sdk_lib/lib/libzmq.so.3
LoadFile /opt/appdynamics-sdk-native/sdk_lib/lib/libuuid.so.1
LoadFile /opt/appdynamics-sdk-native/sdk_lib/lib/libappdynamics_native_sdk.so
```
  CODE
  libappdynamics_native_sdk.so has a runtime dependency on libzmq and libuuid. These libraries can be found in the same directory as ibappdynamics_native_sdk.so.
- LoadModule: Loads the AppDynamics Apache Agent shared library. The correct module is libmod_appdynamics.so for Apache 2.4 and libmod_appdynamics22.so for Apache 2.2. Required.
  
  OHS and IHS 7.x - 8.x require the Apache 2.2 module. IHS 9.x uses the Apache 2.4 module.
  
  Apache 2.4 example:
```
LoadModule appdynamics_module /opt/appdynamics-sdk-native/WebServerAgent/Apache/libmod_appdynamics.so
```
  CODE
  Apache 2.2 example:
```
LoadModule appdynamics_module /opt/appdynamics-sdk-native/WebServerAgent/Apache/libmod_appdynamics22.so
```
  CODE
- AppDynamicsEnabled: Must be included and set to ON for web server monitoring to be enabled. Otherwise, monitoring is disabled by default. For example:
```
AppDynamicsEnabled ON
```
  CODE
  To disable monitoring, set to OFF or remove the AppDynamics module include statement (see Configure the Apache Server for AppDynamics) from the Apache configuration file.
- AppDynamicsControllerHost: Hostname or IP address of the AppDynamics controller to connect to. Required.
  For example
```
AppDynamicsControllerHost mycontroller.saas.appdynamics.com
```
  CODE
- AppDynamicsControllerPort: Controller HTTP(S) port. For SaaS, use 443 for HTTPS or 80 for HTTP. For on-premises, HTTP defaults to 8090 and HTTPS defaults to 8181. Optional. Configure if you do not want to use these defaults. If you are using HTTPS, the SSL setting (AppDynamicsControllerSSL) must also be set.
  For example:
```
AppDynamicsControllerPort 80
```
  CODE
- AppDynamicsControllerSSL: Set to connect to the Controller over SSL. Default is OFF. Set to ON to enable SSL connection and also set the AppDynamicsControllerPort to an HTTPS port.
  Example:
```
AppDynamicsControllerSSL OFF
```
  CODE
- AppDynamicsAccountName: AppDynamics account name. For on-premises controllers, find your credentials under > License in the Controller. For SaaS Controllers, AppDynamics provides your credentials in your Welcome email. Required.
  Example:
```
AppDynamicsAccountName MyCompany
```
  CODE
- AppDynamicsAccessKey: AppDynamics account access key. For on-premises Controllers, find your credentials under > License in the Controller. For SaaS Controllers, AppDynamics provides your credentials in your Welcome email. Required.
  Example:
```
AppDynamicsAccessKey zd8yjh5yuy5k
```
  CODE
- AppDynamicsProxyHost: Proxy server hostname or IP address. Optional. Use if the agent connects to the Controller through a HTTP proxy server.
- AppDynamicsProxyport: Proxy server port. Optional. Use if the agent connects to the Controller through a HTTP proxy server
- AppDynamicsApplication: AppDynamics application name. See Overview of Application Monitoring. Required.
  For example:
```
AppDynamicsApplication MyWS2App
```
  CODE
- AppDynamicsTier: AppDynamics tier name. See Overview of Application Monitoring. Required.
  For example:
```
AppDynamicsTier MyWS2
```
  CODE
- AppDynamicsNode: AppDynamics node name. See Overview of Application Monitoring. The node name is required and each node name must be unique.
  For example:
```
AppDynamicsNode WS2_1
```
  CODE

Sample appdynamics_agent.conf

#Load the AppDynamics SDK.
LoadFile /opt/appdynamics-sdk-native/sdk_lib/lib/libzmq.so.3
LoadFile /opt/appdynamics-sdk-native/sdk_lib/lib/libuuid.so.1
LoadFile /opt/appdynamics-sdk-native/sdk_lib/lib/libappdynamics_native_sdk.so
 
#Load the Apache Agent. In this example for Apache 2.4
LoadModule appdynamics_module /opt/appdynamics-sdk-native/WebServerAgent/Apache/libmod_appdynamics.so

AppDynamicsEnabled On

#AppDynamics Controller connection.
AppDynamicsControllerHost mycontroller.saas.appdynamics.com
AppDynamicsControllerPort 80
AppDynamicsControllerSSL OFF

#Account credentials
AppDynamicsAccountName MyCompany
AppDynamicsAccessKey zd8yjh5yuy5k

#Configure Controller connection through an HTTP proxy server.
#AppDynamicsProxyHost <proxy host>
#AppDynamicsProxyPort <proxy port>

#Business application, tier, node
AppDynamicsApplication MyApache2App
AppDynamicsTier Apache2
AppDynamicsNode Apache2_1

CODE

Launch the Proxy

To launch the proxy manually, run runSDKProxy.sh using the user ID of the Apache worker threads.

nohup <agent_install_directory>/runSDKProxy.sh >>/dev/null 2><agent_install_dir>/logs/proxy.out &

It is recommended that you create a Unix System Service that automatically starts the proxy at system startup.

The Proxy expects the appropriate (64- vs. 32-bit) libstdc+6 library location. If you are installing the Apache Agent on a 64-bit OS that supports running a 32-bit Apache HTTP Server, make sure that the downloaded Apache Agent matches (i.e., is 32-bit), and that the libstdc+6 library is 32-bit as well. If you have both 64-bit and 32-bit versions of that library, make sure you are pointing to the correct version using the command export LD_PRELOAD=<path to 32bit library> before starting runSDKProxy.

Additional Directives

You may need to set the following optional directives unless instructed by AppDynamics support:

AppDynamicsBackendNameSegments- The number of URL segments that are displayed in the backend naming. This is only applicable for requests routing through the mod_proxy, when Apache is acting as a reverse proxy server, also-known-as a gateway server. Specify the rule configuration for backend naming in the appdynamics_agent.conf file. The default value is 0 and only the IP address of the request URL is displayed. If you set a value of 2, then the first two segments along-with the IP address are displayed. Therefore for a request proxying to http://1.1.1.1/services/admin/abc, the backend isnamed as http://1.1.1.1/services/admin.
For example:

AppDynamicsBackendNameSegments 2

CODE

AppDynamicsResolveBackends- Controls the way Apache module backends appear in the Controller UI. If ON, metrics for Apache modules are shown as part of downstream tiers or backends. Module backends do not appear on flow maps.
If OFF, Apache module backends appear in the flow maps with their own metrics. See Apache Modules.
Defaults to ON. Optional.
For example:
```
AppDynamicsResolveBackends OFF
```
CODE
AppDynamicsTraceAsError- If ON, tracepoints are written as errors to the Apache logs, by default error_log. Default is OFF. Optional.
For example:
```
AppDynamicsTraceAsError OFF
```
CODE
AppDynamicsReportAllInstrumentedModules- If OFF, the agent reports only modules that occur during the HANDLER stage of Apache request processing. If ON, the agent reports modules during all stages of Apache request processing. The default is OFF.
For example:
```
AppDynamicsReportAllInstrumentedModules OFF
```
CODE
AppDynamicsLaunchProxy- If ON, the agent launches the proxy automatically when on startup. If OFF, you need to manually launch the proxy. If your system uses any command to do a graceful restart of Apache, such as log rotate, or if your system encounters heavy loads, you should set this property to OFF. The default is OFF.
For example:
```
AppDynamicsLaunchProxy OFF
```
CODE
For information about how to examine and resolve proxy issues that may prevent an application agent from connecting to the Controller, see Dynamic Language Agent Proxy.
You may want to launch the proxy manually for debugging. For example, to set a different proxy root directory or runtime directory or to output additional debugging information.
AppDynamicsRequestCacheCleanupInterval- Timeout in milliseconds after which the request cache is cleaned up by Java proxy. Proxy consists of a queue that takes all the requests from the agents and stores these requests for processing. Sometimes, this message queue can have an enormous cache within an interval of a minute under high load scenarios. Therefore as a preventive measure, a cleanup timer with a default value of 60 secs is available. To monitor long transactions, increase the cleanup interval, but you must be vigilant of the high cache or memory usage.
For example:
```
AppDynamicsRequestCacheCleanupInterval 120000
```
CODE
If you are running the proxy manually, then while running the launch proxy command add the following flag:
--req-cache-cleanup-interval=120000

CODE
AppDynamicsProxyCommDir- Path to the directory containing the domain control socket, which the agent uses to start an AppDynamics node. Defaults to <agent_install_directory>/logs/appd-sdk. If you modify this setting, make sure that the directory path does not exceed 107 characters, which is the Linux limit to the socket file name size. If the directory path is too long, you will get an error message when the agent attempts to start.
```
AppDynamicsProxyCommDir <agent_install_directory>/proxy/altcommdir
```
CODE
For Filtering sensitive-data and privileged information, see Filter Sensitive Data.

Configure the Apache Server for AppDynamics

Add an include for the AppDynamics Apache Agent configuration to the server configuration. Ensure that the AppDynamics module is loaded after any modules you want to be instrumented. Any modules loaded after the AppDynamics agent are excluded from instrumentation and monitoring. For example, add the following as the last line in the httpd.conf file—on Ubuntu and Debian, this file is called apache2.conf:
```
#Include AppDynamics Apache Agent Configuration
Include conf/appdynamics_agent.conf
```
CODE
If you are running multiple instances of the web server, modify the .conf Include path to match the configuration file name for that instance. For example:
```
#Include AppDynamics Apache Agent Configuration.
Include conf/appdynamics_agent1.conf
```
CODE
Restart the web server. For example, for Apache on CentOS:
```
apachectl restart
```
CODE
Apply load to your web server to activate instrumentation.

The AppDynamics Apache Agent automatically detects the incoming HTTP calls as business transactions. It detects loaded modules as backends. Log in to the AppDynamics Controller to begin monitoring.

Map Virtual Hosts to AppDynamics Tiers

By configuring virtual hosts, Apache Web Server administrators can have a single Apache Web Server instance act as the entry point for what appears to be different websites from the end user's perspective.

In the AppDynamics application model, it will usually make sense to represent each virtual host configured in an Apache Web Server as its own tier. This tends to better represent the logical model of the environment and reduces the likelihood of quickly exhausting tier business transaction limits for an Apache Web Server that proxies a large application environment.

To associate different virtual hosts with different tiers, add the AppDynamicsApplicationContext directive to the virtual host configuration, supplying the application, tier and node name as arguments, as follows:

AppDynamicsApplicationContext <application> <tier> <node>

For example:

Listen 80
<VirtualHost *:80>
    DocumentRoot "/www/example1"
    ServerName site1.example.com
    ...
    AppDynamicsApplicationContext MyApp site1.example.com:80 node01
</VirtualHost>

<VirtualHost *:80>
    DocumentRoot "/www/example2"
    ServerName site2.example.org
    ...
    AppDynamicsApplicationContext MyApp site2.example.org:80 node01
</VirtualHost>

In the example above, the tier name is a combination of the virtual machine ServerName and port number. You are not required to include the ServerName and port number in the tier name, but they can be useful for identifying which virtual machines are creating business transactions. We recommend using a tier name that best represents the purpose of the virtual machine.

The Apache Web Server Agent associates incoming requests to the AppDynamics context based upon the virtual host server and port in the request.

Note that instead of using virtual hosts to multi-host from Apache, an administrator may run multiple instances of the Apache Web Server with a distinct httpd.conf file—on Ubuntu and Debian, this file is called apache2.conf—for each instance. In this case, you would instrument the Apache Web Server by creating an AppDynamics agent configuration file for each instance, and include each configuration file in the httpd.conf file of the corresponding instance. See Configure the Apache Agent.

Set Unique Host ID for App Agents

To set a unique host ID for the App agents, add the following command to the runProxy file:

set -- "$@" -Dappdynamics.agent.uniqueHostId="<your-unique-host-id>"

For example, you can add the following to the <agent_install_directory>/proxy/runProxy file.

 set -- "$@" -Dappdynamics.agent.logs.dir=${logsDir}
 set -- "$@" -Dcomm=${proxyCommunicationDir}
 set -- "$@" -DagentType=${agentType}
 set -- "$@" -Dappdynamics.agent.uniqueHostId="<your-unique-host-id>"
 set -- "$@" -Dappdynamics.agent.runtime.dir=${proxyRuntimeDir}
 set -- "$@" -Dlog4j.ignoreTCL=true
 set -- "$@" -XX:MaxPermSize=${maxPermSize}

CODE

You must set the unique host ID again after an agent upgrade.