AppDynamics Application Intelligence Platform

3.9.x Documentation


Learn by Watching

Doc Maps

Skip to end of metadata
Go to start of metadata


This topic covers the Machine Agent. It does not cover the embedded .NET Machine Agent included with the App Agent for .NET. 

The Machine Agent uses a built-in hardware monitor to report metrics and hardware usage data. The hardware monitor is a script that writes data to STDOUT of a process. Once installed, the Machine Agent runs and reports to the Controller once a minute.

Use the Machine Agent to:

Machine Agent Architecture

Metrics Collected by the Machine Agent

The agent automatically collects the following performance data:

  1. CPU
    1. Busy, Free
  2. Memory
    1. Used, Free, Total
  3. Disk
    1. Network mounted disks (Free, Used, IO Writes/Reads in KB/s and packets)
    2. Local disks (Free, Used, IO Writes/Reads in KB/s and packets)
      You can configure the agent to monitor virtual disks
  4. Network interfaces
    1. No Loopback
    2. No disabled or unconnected
    3. Incoming KB, KB/s, packets, packets/s
    4. Outgoing KB, KB/s, packets, packets/s


There are many more metrics collected which you can view in the Metric Browser -> Application Infrastructure Performance ->Hardware Resources or add them to your Custom Dashboard. To add CPU metrics to your Custom Dashboard, add the metrics for only one node per server because the metrics collected for a node are for the entire server hosting that node.

Limiting Disk Metrics Collection

By default, the Machine Agent uses the Java Hardware Monitor (Sigar API-based), which may collect more metrics than you need.  

For example, you may not want to see backup metrics such as the following, where out of a total 3315 metrics reported by the Machine Agent, 2584 are due to back up disk metrics :

Instead of using the default Java Hardware Monitor the Machine Agent can use the Hardware Monitor which uses an OS specific script file ( in this case) to capture stats, which will not track backup porcesses.

To stop tracking backup process and limit future disk metrics switch from the Java Hardware Monitor to the Hardware Monitor.

To switch from the Java Hardware Monitor to the Hardware Monitor

  1. Stop the Machine Agent by stopping its process.  See below for info on identifying the agent process.
  2. Switch from the Java Hardware Monitor to Hardware Monitor as follows:
    1. Open for edit monitor.xml from <Agent install directory>/monitors/HardwareMonitor/monitor.xmll
    2. Change <enabled>false</enabled> to <enabled>true</enabled> and then save the file.
    3. Open for edit  <Agent install directory>/monitors/JavaHardwareMonitor/monitor.xml.
    4. Change <enabled>true</enabled> to <enabled>false</enabled> and then save the file.
  3. Restart the Machine Agent.

From the command line, enter java -jar <Agent install directory>/machineagent.jar.

This limits the future disks metrics but will not delete the existing metrics.

Which process is the machine agent process?

For Linux
Use the following command to identify which process is running the Machine Agent.

ps -ef | grep machine

For Windows

Process Explorer is a free application from Microsoft that can help you identify the Standalone 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

Machine Agent and the Flow Maps

The Machine Agent monitors a particular machine and not a particular application server. The agent can therefore refer to multiple nodes running on the same machine. A flow map, on the other hand, displays the communication between different nodes during application execution, or the business transaction flow from tier to tier. A Machine Agent cannot be a part of the flow and therefore is not shown in the flow map.

Machine Agent and the Server Health Indicator

Metrics monitored by the agent are included in the infrastructure health indicator in the dashboards.

The health indicator is driven by health rule violations in the given time period and health rule violations are configured on hardware metrics collected by the Machine Agent. Health rules for all possible metrics are not configured out-of-the-box, so you might want to configure additional health rule according to your requirements. For details see Configure Health Rules.

Using the Machine Agent

To access the Machine Agents window

  • In  the upper right menu bar of the controller UI, click Settings -> AppDynamics Agents.

AppDynamics lists all agents for all business applications.

Resetting a Machine Agent

The reset operation purges all existing metrics for an agent and starts gathering them again. It stops the agent and starts it again.

To reset (stop/restart) a Machine Agent

1. In the Machine Agents window of the Controller UI, select an agent.

2. Click Reset Selected Machine Agent.

Associate a Machine Agent with an Application

If no configuration details are provided during installation, or if the node has been moved to another application, then the Machine Agent appears in the System -> Agents tab as "not associated with any applications". To have the Machine Agent start sending metrics or executing workflow tasks, manually associate it with an application.

The following message in the agent log (<machine_agent_home>/logs/machine-agent.log) indicates that there is no application associated with the agent:

Received Metric Registration request for a machine id:<NNNNN> that is NOT registered to any nodes yet, sending back null response!

To associate a Machine Agent with a business application

1. In the AppDynamics Agents window, select an agent.

2. Click Associate with an Application.

To associate multiple agents with multiple business applications

If the machine is hosting servers that belong to multiple business applications, you may need multiple agents.

If there are nodes belonging to multiple business applications, you can run multiple agents each configured to report metrics for a different node, tier, and application.

You cannot "assign" a single Machine Agent to multiple business application per se. A Machine Agent on a specific machine is automatically associated with all nodes running on that machine. A node is associated with a single business application. Therefore an application is associated with the agents of its nodes. By default a Machine Agent inherits the application/tier/node names of the App Agent installed on the same hardware.

To associate one Machine Agent agent with multiple JVMs, each running on separate VMs on the same machine

If you have an application where a tier has three nodes running on the same machine and you want the Machine Agent to report the metrics for their host machine to each node do the following


  1. Stop the agents for all app agent nodes and the machine agent node associated with the application. If this is is fresh application association ignore this step.
  2. Start the appserver agent node for each VM (using the app, tier and node details provided in <AppAgent install directory>/conf/controller-info.xml) with the -D JVM arg, in addition to the -javaagent argument as below . 

    -Dappdynamics.agent.uniqueHostId=myTierAHostName1 -javaagent
  3. Start the Machine Agent with same uniquehostid used for agent nodes associated above.

    java -Dappdynamics.agent.uniqueHostId=myTierAHostName1 -jar machineagent.jar

    Ensure sure you have not provided application-name, tier-name, and node-name details in <machineagent install directory>/conf/controller-info.xml file.

Resolving Problems

Switch from the Java Hardware Monitor to the Hardware Monitor if you see messages similar to the following in the logs:


[Worker-7] 12 Sep 2014 07:27:49,449 WARN MonitorOutputHandler - Metric Reporter type mismatch for metric [Hardware Resources|Network|Incoming packets/sec] Aggregator of OBSERVATION already exists for metric Metric Identifier[Hardware Resources|Network|Incoming packets/sec] ID[0]



Learn More

  • No labels