The Standalone Machine Agent

The AppDynamics Machine Agent, also called the Machine Agent, is a standalone Java program that collects performance statistics about your environment. It can be deployed on any machine that hosts application servers, database servers, messaging servers, Web servers, etc. It has an extensible architecture.

The Machine Agent supports hardware monitoring on most platforms. You can also write custom plugins for monitoring particular hardware metrics.

The following illustration shows the architecture for the Machine Agent. A Machine Agent collects hardware metrics using the default and custom plugins and sends task execution data to the Controller.

Prerequisites for Installing the Standalone Machine Agent

The Machine Agent requires Java 1.5 or later to be installed on the machine. You can download Java 1.6 from the Oracle website.

A machine can have only one active Machine Agent installation at a time. Make sure you do not have any previous running installation processes before you install.

To install the Standalone Machine Agent

1. Download the Machine Agent.

Download the agent from AppDynamics Download Center.

You can also download from the Linux command line.

The Standalone Machine Agent is packaged as a zip file.

2. Extract the zip file to the destination directory.

Do not use spaces in the destination directory path.

For Windows environments, unblock the zip file before you extract it. To unblock the zip file, right-click on the zip file and select the Properties tab. On the Properties tab, choose unblock to unblock the file.

3. Configure how the agent connects to the Controller.

Configure properties for the Controller host name and port number using either the <Machine_Agent_Installation_Directory>/conf/controller-info.xml file or by adding system properties to the JVM startup script file.

Configure using controller-info.xml	Configure using System Properties	Required	Default
<controller-host>	-Dappdynamics.controller.hostName	Yes	None
<controller-port>	-Dappdynamics.controller.port	Yes	For On-premise Controller installations: By default, port 8090 for HTTP and 8181 for HTTPS communication. For SaaS Controller service: By default, port 80 for HTTP and port 443 for HTTPS communication.

If you start a Standalone Machine Agent on a machine that already has an App Agent for Java or the App Agent for PHP installed, the Machine Agent will automatically associate itself with the app agent's application, tier, and node settings. If you install an App Agent for PHP on the same machine as the Machine Agent, install the App Agent before the Machine Agent, and do not specify the tier and node in the machine agent configuration.

To configure agent to use SSL see Enable SSL for Communicating with the Controller.

To configure the agent to use proxy settings see Proxy Settings for the Controller.

4. (For Multi-tenant mode or SaaS installations only.) Configure the agent account information.

This step is required only when the AppDynamics Controller is configured in Controller Tenant Mode or when you Use a SaaS Controller. Skip this step if you are using single-tenant mode.

Specify the properties for Account Name and Account Key. This information is in the welcome email sent by AppDynamics Support Team.

Configure using controller-info.xml	Configure using System Properties	Required	Default
<account-name>	-Dappdynamics.agent.accountName	Required only if your Controller is configured for multi-tenant mode or if your Controller is hosted.	None.
<account-access-key>	-Dappdynamics.agent.accountAccessKey	Required only if your Controller is configured for multi-tenant mode or if your Controller is hosted.	None.

5. Configure the business application, tier, and node.

If there is an App Agent already installed on the machine, AppDynamics automatically makes the association.

If there is no App Agent installed on the same machine, specify the application, tier, and node names.

Edit the agent <Agent_Install_Directory>/conf/controller-info.xml file and specify the following elements:

Configure using controller-info.xml	Configure using System Properties
<application-name>	-Dappdynamics.agent.applicationName
<tier-name>	-Dappdynamics.agent.tierName
<node-name>	-Dappdynamics.agent.nodeName

If you do not provide configuration details the Machine Agent will not be associated with a business application. You can manually associate the agent in the UI at a later time. See Administer Standalone Machine Agents.

6. (Optional) Configure the agent to run automatically when the machine starts.

See Machine Agent Install and Admin FAQ.

7. Start the agent.

In a command line console, execute the following command to start the Machine Agent:

java -Xmx32m -jar machineagent.jar

Alternatively, in a Linux environment, you can execute the following command in the background:

nohup java -Xmx32m -jar machineagent.jar &

If your application uses a large number of AppDynamics extensions with the machine agent, you may need to increase the size of the memory allocation as follows:

java -Xms64m -Xmx64m -jar machineagent.jar &

8. Verify the agent installation.

Open the <Agent_Install_Directory>/logs/machine-agent.log file. After successful installation, this file should contain the following message:

Started AppDynamics Machine Agent Successfully

This message is also printed on the STDOUT of the process.

9. Verify that the agent is reporting to the Controller.

In the left navigation panel, click Servers -> App Servers -> <Tier> -> <Node>.
AppDynamics displays the Tier Dashboard for the selected tier.

When Machine Agentis reporting to the Controller, the Machine Agent Status column shows a green up arrow icon.

You should see an "up" arrow symbol listed for the agent.

Resolve Standalone Machine Agent Installation Issues

To verify that the agent is running

Use the following command to verify that the agent script is running:

Linux:

ps -ef | grep machine

Windows:
1. Open a command line console.
2. Start the Task Manager and click the Processes tab.
3. The agent process should be running. If the script is not running, terminate the Machine Agent Java process and restart it.

To resolve agent connectivity problems

If when you start the Machine Agent, it cannot register with the controller or associate with the same node in the controller, looking at the stack trace may reveal the reason why.

For example, the following message in the stack trace may indicate that the application, tier, and node information was not provided during the Machine Agent startup or in the controller-info.xml file.

<execution-output>System agent 239590 not associated with application, metric registration request refused.</execution-output>

Make sure that the application, tier, and node information is either provided during the Machine Agent startup or in the controller-info.xml file. For information on configuring the Machine Agent, see Machine Agent Configuration Properties.

After providing the above information, restart the Machine Agent and check the agent behavior. Machine Agent log files may also provide some insight into problems.

Which process is the machine agent process?

Process Explorer is a free application from Microsoft that can help you identify the Machine Agent process. When there are multiple java processes running, hover over a Java process in Process Explorer to identify the process that was started using the machineagent.jar file.

For example, in Process Explorer, hover over a process to see information about how the process was started as you can see in the following window:

You can download Process Explorer at http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx.

Learn More

Install the Standalone Machine Agent