This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


Beta Disclaimer

This documentation mentions features that are currently beta. AppDynamics reserves the right to change the features at any time before making them generally available as well as never making them generally available. Any buying decisions should be made based on features that are currently generally available.

On this page:

Related pages:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
55 rates

General Notes

You can configure Standalone Machine Agent properties:

  • as elements in the controller-info.xml file located in the <machine_agent_home>/conf directory
  • in the agent system configuration properties (-D<system_property>) section of the Standalone Machine Agent start-up script or on the command line

The JVM system properties and Linux options override the settings in the controller-info.xml file. 

Some properties can be configured only in the controller-info.xml file, some only as arguments to the startup command line or in agent configuration files, and others can be configured as both controller-info.xml elements and system properties.

System Property Configuration Property Format Requirements

  • System properties are case-sensitive.
  • Property values that contain spaces must be surrounded with double quotes.
  • For Windows only: Any agent configuration property with '=' in it must be surrounded with double quotes.

Where to Specify Agent System Configuration Properties

You configure agent system properties in different ways depending on your operating system and the installation package you used as follows:

 Linux using the RPM Package

New in 4.1 When starting the agent service with the service launcher specify the agent system properties by editing the JAVA_OPTS environment variable. Use the format JAVA_OPTS="-D<sys-property1>=<value1> -D<sys-property2>=<value2>. The config file is located as follows:

  • SysV:  <machine_agent_home>/etc/sysconfig/appdynamics-machine-agent
  • systemD: <machine_agent_home>/etc/systemd/system/appdynamics-machine-agent.service

When starting the agent application on the command line using the machine-agent command, specify the agent system properties on the command line, such as:

  • Run agent in background: % nohup <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1> -D<system_property2>=<value2> ...  &
  • Run agent in foreground: % <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1> -D<system_property2>=<value2> ... 
 Linux using the JRE Bundled Archive

New in 4.1 When starting the agent application on the command line using the machine-agent command, specify the agent system properties on the command line, such as:

  • Run agent in background: % nohup <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1> -D<system_property2>=<value2> ...  &
  • Run agent in foreground: % <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1> -D<system_property2>=<value2> ... 
 Linux using the Non-JRE Bundled, Non-OS Specific Zip File

When starting the agent application on the command line using the machine-agent script, specify the agent system properties on the command line, such as:

  • Run agent in background: % nohup <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1> -D<system_property2>=<value2> ... &
  • Run agent in foreground: % <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1> -D<system_property2>=<value2> ... 
 Solaris using the JRE Bundled Archive or the non-JRE Bundled, Non-OS Specific Zip File

When starting the agent application on the command line using the machine-agent script, specify the agent system properties on the command line, such as:

  • Run agent in background: % nohup <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1-D<system_property2>=<value2> ...  &
  • Run agent in foreground: % <machine_agent_home>/bin/machine-agent -D<system_property1>=<value1-D<system_property2>=<value2> ... 
 Windows using the JRE Bundled Archive

New in 4.1  When starting the agent using the agent service installer and launcher, InstallService.cmd, specify the agent system properties on the command line, such as:

> <machine_agent_home>\InstallService.cmd "-D<system_property1>=<value1>" "-D<system_property2>=<value2>" ... 

After the service is installed, you will see a new file. <machine_agent_home>\bin\MachineAgentService.vmoptions. Each line in this file is passed as a property to the Standalone Machine Agent. You can edit this file to change the parameters with which the Standalone Machine Agent will start. Then you can use the MachineAgentService command to start the agent with the new properties

New in 4.1  When starting the agent as an application from the command line, using the machine-agent.cmd script, specify the agent system properties on the command line, such as:

<machine_agent_home>\bin\machine-agent.cmd /agentProps "-D<system_property1>=<value1>"  "-D<system_property2>=<value2>" ... 

 Windows using the non-JRE Bundled, Non-OS Specific Archive

New in 4.1 When starting the agent application on the command line using the machine-agent script, specify the agent system properties on the command line, such as:

> <machine_agent_home>\bin\machine-agent.cmd "-D<system_property1>=<value1>" "-D<system_property2>=<value2>" ...

 Mac OS X using the JRE Bundled Archive

New in 4.1 When starting the agent service using the <machine_agent_home>/osx-install.sh script, specify the agent system properties on the command line, such as:

> sh <machine_agent_home>/osx-install.sh -D<system_property1>=<value1> -D<system_property2>=<value2> ... 

When you run the <machine_agent_home>/osx-install.sh script, the <machine_agent_home>/com.appdynamics.machineagent.plist.template is updated with the installation directory and the java properties set for the machine agent.

When starting the agent as an application from the command line, using the launchctl utility, first specify the Standalone Machine Agent system properties in the <machine_agent_home>/com.appdynamics.machineagent.plist.template, ProgramArguments array, Non_STD_JAVA_PROPS string and save the template as <machine_agent_home>/com.appdynamics.machineagent.plist and then load this plist file with the launchctl utility.

 Mac OS X using the non-JRE Bundled, Non-OS Specific Archive

New in 4.1 When starting the agent application on the command line using the machine-agent script, specify the agent system properties on the command line, such as:

> <machine_agent_home>/bin/machine-agent.cmd -D<system_property1>=<value1> -D<system_property2>=<value2> ...

Example Standalone Machine Agent controller-info.xml File

<?xml version="1.0" encoding="UTF-8"?>
<controller-info>

	<controller-host>192.10.10.10</controller-host>

	<controller-port>8090</controller-port>
    
    <account-access-key>165e65645-95c1-40e3-9576-6a1424de9625<account-access-key>
 
	<controller-ssl-enabled>false</controller-ssl-enabled>

	<enable-orchestration>false</enable-orchestration>

    <!-- The following account-related parameters are necessary only for SaaS installations-->
	<!--account-name></account-name-->
	
	<force-agent-registration>false</force-agent-registration>
 
	<!-- The following options are optional and only required when force-agent-registration is true-->
	<!--application-name></application-name-->
	<!--tier-name></tier-name-->
	<!--node-name></node-name-->

</controller-info>

A bash example. 

<machine_agent_home>/bin/machine-agent -Dappdynamics.controller.hostName=192.168.1.20 -Dappdynamics.controller.port=8090 -Dappdynamics.agent.accountAccessKey=165e65645-95c1-40e3-9576-6a1424de9625 -Dappdynamics.agent.applicationName=ACMEOnline -Dappdynamics.agent.tierName=Inventory -Dappdynamics.agent.nodeName=inventory1 org.tomcat.TomcatServer

Standalone Machine Agent Configuration Property Reference

This section describes the Standalone Machine Agentconfiguration properties, including their controller-info-xml elements and their system property options.

Agent-Controller Communication Properties

Controller Host Property

Description: This is the host name or the IP address of the AppDynamics Controller, e.g. 192.168.1.22 or myhost or myhost.abc.com. This is the same host that you use to access the AppDynamics browser-based user interface.

Element in controller-info.xml:  <controller-host>

System Property: -Dappdynamics.controller.hostName

Type: String

Default: None

Required: Yes If the Enable Orchestration property is false.
If Enable Orchestration is true, and if the agent is deployed in a compute cloud instance created by an AppDynamics workflow, do not set the Controller host unless you want to override the auto-detected value. See Enable Orchestration Property.

Controller Port Property

Description: This is the HTTP(S) port of the AppDynamics Controller. This is the same port that you use to access the AppDynamics browser-based user interface. If the Controller SSL Enabled property is set to true, specify the HTTPS port of the Controller; otherwise specify the HTTP port. See Controller SSL Enabled Property.

Element in controller-info.xml:  <controller-port>

System Property: -Dappdynamics.controller.port

Type: Positive Integer

Default: For On-premise installations, port 8090 for HTTP and port 8181 for HTTPS are the defaults.
For the SaaS Controller Service, port 80 for HTTP and port 443 for HTTPS are the defaults.

Required: Yes, if the Enable Orchestration property is false.
If Enable Orchestration is true, and if the agent is deployed in a compute cloud instance created by an AppDynamics workflow, do not set the Controller port unless you want to override the auto-detected value. See Enable Orchestration Property.

Account Access Key Property

Description: This is the account access key used to authenticate with the Controller. This key is generated at installation time and can be found on the AppDynamics Administration Console. After logging in, click Accounts, select the account, and then click Show Access Key.

Element in controller-info.xml:  <account-access-key>

System Property: -Dappdynamics.agent.accountAccessKey

Type: String

Default: None

Required: New in 4.1 Yes. Prior to version 4.1, this property was required only for SaaS and multi-tenant Controllers. The account access key property is now required to authenticate all agent to Controller communications.

Example: -Dappdynamics.agent.accountAccessKey=165e65645-95c1-40e3-9576-6a1424de9625

Standalone Machine Agent Identification Properties

If the Standalone Machine Agent is installed on a machine that does not have an App Server agent, configure the application name, tier name and the node name. Otherwise these configurations are not required for the Standalone Machine Agent.

Application Name Property

Description:  This is the name of the logical business application that this JVM node belongs to. Note that this is not the deployment name(ear/war/jar) on the application server.

If a business application of the configured name does not exist, it is created automatically.

Element in controller-info.xml:  <application-name>

System Property: -Dappdynamics.agent.applicationName

Type: String

Defaults: None

Required: If a registered app server agent is already installed on the same host as this machine agent, this configuration is not required.

Tier Name Property

Description:  This is the name of the logical tier that this JVM node belongs to. Note that this is not the deployment name (ear/war/jar) on the application server.

If a tier of the configured name does not exist, it is created automatically.

Element in controller-info.xml: <tier-name>

System Property: -Dappdynamics.agent.tierName

Type: String

Defaults: None

Required: If a registered app server agent is already installed on the same host as this machine agent, this configuration is not required.

Node Name Property

Description:  This is the name of the JVM node.

Element in controller-info.xml: <node-name>

System Property: -Dappdynamics.agent.nodeName

Type: String

Defaults: None

Required: If a registered app server agent is already installed on the same host as this Standalone Machine Agent, this configuration is not required.

Enable Server Monitoring Property

Enable Server Monitoring Pro Property

Description:  New in 4.1 Enables the new features of Server Monitoring Beta 4.1.

Element in controller-info.xml:  n/a

System Property: -Dappdynamics.sim.enabled

Type: Boolean

Default: false

Required: Required to enable beta features of Server Monitoring.

Multi-Tenant Mode Properties

If the AppDynamics Controller is running in multi-tenant mode or if you are using the AppDynamics SaaS Controller, specify the account name and account access key for this agent to authenticate with the Controller.

If the Controller is running in single-tenant mode (the default) there is no need to configure these values.

When the agent is registered with an AppDynamics SaaS Controller, features used to run Remediation Scripts are disabled If you later reconfigure the agent controller-info.xml to register with a non-SaaS or on-premise Controller, the agent can run local scripts as usual.

Account Name Property

Description:  This is the account name used to authenticate with the Controller.
If you are using the AppDynamics SaaS Controller, the Account Name is provided in the Welcome email sent by AppDynamics.

Element in controller-info.xml:  <account-name>

System Property: -Dappdynamics.agent.accountName

Type: String

Default: None

Required: Yes for AppDynamics SaaS Controller and other multi-tenant users; no for single-tenant users.

Proxy Properties for the Controller

These properties route data to the Controller through a proxy.

Proxy authentication cannot be used in conjunction with SSL. 

Proxy Host Property

Description:  This is the proxy host name or IP address.

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.http.proxyHost

Type: String

Default: None

Required No

Proxy Port Property

Description:  This is the proxy HTTP(S) port.

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.http.proxyPort

Type: Positive Integer

Default: None

Required: No

Proxy User Name Property

The name of the user that is authenticated by the proxy host.

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.http.proxyUser

Type: String

Default: None

Required: No

Proxy Password File Property

The absolute path to the file containing the password of the user that is authenticated by the proxy host. The password must be the first line of the file and must be in clear (unencrypted) text. 

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.http.proxyPasswordFile

Type: String

Default: None

Required: No

Example: -Dappdynamics.http.proxyPasswordFile=/path/to/file-with-password

SSL Properties

Controller SSL Enabled Property

Description:  This property specifies whether the agent should use SSL (HTTPS) to connect to the Controller. If SSL Enabled is true, set the Controller Port property to the HTTPS port of the Controller. See Controller Port Property.

Element in controller-info.xml:  <controller-ssl-enabled>

System Property: -Dappdynamics.controller.ssl.enabled

Type: Boolean

Default: False

Required: No

Controller Keystore Filename Property

By default, the agent looks for a Java truststore file named cacerts.jks in the conf directory in the agent home. Use this property to enable full validation of Controller SSL certificates with a different Java truststore file. See Enable SSL for the Standalone Machine Agent.

Element in controller-info.xml:  <controller-keystore-filename>

System Property: Not applicable

Type: String

Default: None

Required: No

Controller Keystore Password Property

The plain text value of the Controller certificate password. 

Element in controller-info.xml: <controller-keystore-password>

System Property: Not applicable

Type: String

Default: None

Required: No

Force Default SSL Certificate Validation Property

Used to override the default behavior for SSL validation. The property can have three states:

  • true:  Forces the agent to perform full validation of the certificate sent by the controller, enabling the agent to enforce the SSL trust chain.  Use this setting when a public certificate authority(CA) signs your Controller SSL certificate. See Enable SSL On-Premise with a Trusted CA Signed Certificate.
  • false: Forces the agent to perform minimal validation of the certificate. This property disables full validation of the Controller's SSL certificate. Use this setting when full validation of a SaaS certificate fails.
  • unspecified:  The validation performed by the agent depends on the context:
    • If the agent is connecting to a SaaS controller, full validation is performed.
    • If the agent is connecting to an on-premise controller, and the cacerts.jks file is present, then full validation is performed using the cacerts.jks file.
    • If the agent is connecting to an on-premise controller, and there is no cacerts.jks file, then minimal validation is performed 

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.force.default.ssl.certificate.validation

Type: Boolean

Default: None

Required: No

HTTP Listener Properties

Enable HTTP Listener

Description:  When set to true, this property enables the Standalone Machine Agent HTTP listener.
You can send metrics to the Standalone Machine Agent using its HTTP listener. You can report metrics through the Standalone Machine Agent by making HTTP calls to the agent instead of piping to the agent through sysout.

Element in controller-info.xml: Not applicable

System Property: -Dmetric.http.listener

Type: Boolean

Default: False

Required: No

HTTP Listener Port

Description:  In order to enable the Standalone Machine Agent HTTP listener, you must also specify the HTTP listener port

Element in controller-info.xml: Not applicable

System Property: -Dmetric.http.listener.port

Type: Numeric

Default: 8293

Required: No

Other Properties

Enable Orchestration Property

Description:  When set to true, this property enables Standalone Machine Agent workflow task execution.
It also enables auto-detection of the controller host and port when the app server is a compute cloud instance created by an AppDynamics orchestration workflow. In a cloud compute environment, auto-detection is necessary for the Create Machine tasks in the workflow to run correctly.

See Controller Host Property and Controller Port Property.

The machine agent polls for task executions only when orchestration is enabled.

If the host machine on which this agent resides is not created through AppDynamics workflow orchestration, this property should be set
to false.

Element in controller-info.xml:  <enable-orchestration>

System Property: Not applicable

Type: Boolean

Default: False

Required: No

Unique Host ID Property

Description:  New in 4.1 This property logically partitions a single physical host or virtual machine. You can use the unique host ID when you want to use the same node name for multiple nodes on the same physical machine.  

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.agent.uniqueHostId

Type: ASCII string without spaces, must be unique across the entire managed infrastructure. 

Default: The host name that is currently used. If the last part of the machine hierarchy is empty, the unique host ID is used as the machine name. For example, if machine hierarchy is "Data Center 1|Rack 2|" and host ID is "Host ID 3", then the machine hierarchy will become "Data Center 1|Rack 2|Host ID 3".

Required: No. Only required if you have more than one app agent running on the host. Then to see machine agent metrics for that app agent, you need to run a separate Standalone Machine Agent instance for each app agent and specify a unique host id for each machine agent. The corresponding app agent must specify the same unique host ID as the machine agent.

Machine Hierarchy Property

Description: New in 4.1 Allows you to group your servers together into arbitrary hierarchies by specifying a hierarchical path to the server. The server hierarchy displays in the Metric Browser and on the Server Monitoring Pro Dashboard. The server hierarchy is also used to select subgroups of machines to apply health rules to. The last element of the path indicates the server name, a name of your choice. If the path contains spaces it must be enclosed in double-quotes. 

Element in controller-info.xml: machine-path

System Property: -Dappdynamics.machine.agent.hierarchyPath

Environment VariableAPPDYNAMICS_MACHINE_HIERARCHY_PATH

Type: ASCII string with path elements that are separated by a "|" (bar). 

Default: The value specified by Unique Host ID Property. If the last part of the machine hierarchy is empty, the Unique Host ID is the machine name. For example, if machine hierarchy is "Data Center 1|Rack 2|" and Unique host ID is "Host ID 3", then the machine hierarchy will become "Data Center 1|Rack 2|Host ID 3".

Required: No

Examples

  • System Properties: -Dappdynamics.machine.agent.hierarchyPath= "Data Center 1|Rack 2|Machine3"
  • controller-info.xml: 

    <machine-path>
         "Data Center 1|Rack 2|Machine3"
    </machine-path>
  • Environment VariableAPPDYNAMICS_MACHINE_HIERARCHY_PATH="Data Center 1|Rack 2|Machine3"

     

 

  • No labels