Where to Configure App Agent Properties

You can configure the App Server Agent properties:

in the controller-info.xml file in the <Agent_Installation_Directory>/conf directory

in the system properties (-D options) in the JVM startup script

The system properties override the settings in the controller-info.xml file.

For shared binaries among multiple JVM instances, AppDynamics recommends using a combination of the xml file and the start-up properties to configure the app agent. Configure all the properties common to all the JVMs in the controller-info.xml file. Configure the properties unique to a JVM using the system properties in the start-up script.

For example:

For multiple JVMs belonging to the same application serving different tiers, configure the application name in the controller-info.xml file and the tier name and node name using the system properties.

For multiple JVMs belonging to the same application and the same tier, configure the application name and the tier name in the controller-info.xml file and the node name using the system properties.

After you configure agent properties, confirm that the javaagent argument has been added to the JVM startup script. For more information, see Java Server-Specific Installation Settings.

For some properties, you can use system properties already defined in the start-up script as the App Server Agent property values. For more information, see Configure App Agent for Java to Use Existing System Properties.

Creating and Registering Tiers

You can create a tier in the Controller prior to setting up any agents. Alternatively, an agent can register its tier with the Controller the first time, and only the first time, that it connects with the Controller. If a tier with the name used to connect already exists, the agent is associated with the existing tier.

Example Java App Agent controller-info.xml File

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

	<controller-host>192.168.1.20</controller-host>

	<controller-port>8090</controller-port>

	<controller-ssl-enabled>false</controller-ssl-enabled>

	<application-name>ACMEOnline</application-name>

	<tier-name>InventoryTier</tier-name>

	<node-name>Inventory1</node-name>

	<agent-runtime-dir></agent-runtime-dir>

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

	<account-name></account-name>
	<account-access-key></account-access-key>

	<force-agent-registration>false</force-agent-registration>

</controller-info>

Example Startup-up Using System Properties

The following command uses the system properties to start the agent that monitors the ACME Online sample application's Inventory tier. Note that the system properties are case-sensitive.

java -javaagent:/home/appdynamics/AppServerAgent/javaagent.jar -Dappdynamics.controller.hostName=192.168.1.20 -Dappdynamics.controller.port=8090 -Dappdynamics.agent.applicationName=ACMEOnline -Dappdynamics.agent.tierName=Inventory -Dappdynamics.agent.nodeName=Inventory1 SampleApplication

Java App Server Agent Properties

This section describes the Java App Agent configuration 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. Example values are 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. For an on-premise Controller, use the value for Application Server Host Name that was configured when the Controller was installed. If you are using the AppDynamics SaaS Controller service, see the Welcome email from AppDynamics.

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

SSL Configuration Properties

Controller SSL Enabled Property

Description: When set to true, this property specifies that 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 Password Property

Description: This is an encrypted value of the Controller certificate password. See Password Encryption Utility.

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

System Property: Not applicable

Type: Boolean

Default: None

Required: No

Controller Keystore Filename Property

Description: By default the agent looks for a Java truststore file named cacerts.jks in the configuration directory: <agent install directory>/conf. Use this property to enable full validation of Controller SSL certificates with a different Java truststore file. See Enable SSL for Java.

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

System Property: Not applicable

Type: String

Default: None

Required: No

Force Default SSL Certificate Validation Property

Description: This property allows you 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

Agent Identification Properties

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

Default: None

Required: Yes

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 the JVM / AppServer start-up script already has a system property that references the tier, such as -Dserver.tier, you could use ${server.tier} as the tier name. For more information, see Configure App Agent for Java to Use Existing System Properties.

See Name Business Applications, Tiers, and Nodes.

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

System Property: -Dappdynamics.agent.tierName

Type: String

Default: None

Required: Yes

Node Name Property

Description: This is the name of the JVM node.

Where JVMs are dynamically created, use the system property to set the node name.

If your JVM / AppServer start-up script already has a system property that can be used as a node name, such as -Dserver.name, you could use ${server.name} as the node name. You could also use expressions such as ${server.name}_${host.name}.MyNode to define the node name. See Configure App Agent for Java to Use Existing System Properties for more information.

In general, the node name must be unique within the business application and physical host. If you want to use the same node name for multiple nodes on the same physical machine, create multiple virtual hosts using the Unique Host ID property. See Unique Host ID Property.

See Name Business Applications, Tiers, and Nodes.

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

System Property: -Dappdynamics.agent.nodeName

Type: String

Default: None

Required: Yes

New

Reuse Node Name Property

Description: This system property enables the reuse of node names.

This property is useful in zOS Dynamic Workload Manager based-environments where new JVMs are launched and shutdown based on actual work load. Appdynamics generates a node name with App, Tier and Sequence number. The node names are pooled. For example, the sequence numbers are reused when the nodes are purged (based on the node lifetime).

Use this option in environments where the node name can't be specified in the server startup script, and therefore needs to be auto-generated. Every node creates its own metrics and the names are pooled to make sure the Controller isn't overloaded with too many metric names. The node name is generated by the Controller and sent back to the agent. The Controller recycles node names based on the node retention period property.

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

System Property: -Dappdynamics.agent.reuse.nodeName

Type: Boolean - valid values are "true" or "false"

Default: String.

Required: No

Example: Using the following property specifications, the agent directs the Controller to generate a node name with the prefix "reportGen". Node names will have suffixes --1, --2 etc. depending on how many nodes are running in parallel. Later, the node names are reused by the controller.

-Dappdynamics.agent.reuse.nodeName=true -Dappdynamics.agent.reuse.nodeName.prefix=reportGen

Reuse Node Name Prefix Property

Description: This property directs the Controller to generate node names dynamically with the prefix specified.

System Property: -Dappdynamics.agent.reuse.nodeName.prefix

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

Type: Boolean - valid values are "true" or "false"

Default: false, when set so "true", you do not need to specify a node name.

Required: No

Example: Using the following property specifications, the agent directs the Controller to generate a node name with the prefix "reportGen". Node names will have suffixes --1, --2 etc. depending on how many nodes are running in parallel. Later, the node names are reused by the controller.

-Dappdynamics.agent.reuse.nodeName=true -Dappdynamics.agent.reuse.nodeName.prefix=reportGen

Multi-Tenant Mode Properties

Description: 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 you are using the AppDynamics SaaS Controller, the account name is provided in the Welcome email sent by AppDynamics. You can also find this information in the <controller-install>/initial_account_access_info.txt file.

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

Account Name Property

Description: This is the account name used to authenticate with the Controller.

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

System Properties: -Dappdynamics.agent.accountName

Type: String

Default: None

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

Account Access Key Property

Description: This is the account access key used to authenticate with the Controller.

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

System Properties: -Dappdynamics.agent.accountAccessKey

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

Description: New for 3.8.1 This is 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 Property

Description: New for 3.8.1 This is 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-first-line-containing-password-in-clear-text

Other Properties

Enable Orchestration Property

Description: When set to true, enables auto-detection of the controller host and port when the app server is a compute cloud instance created by an AppDynamics orchestration workflow. See Controller Host Property and Controller Port Property.

In a cloud compute environment, auto-detection is necessary for the Create Machine tasks in the workflow to run correctly.

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

Agent Runtime Directory Property

Description: This property sets the runtime directory for all runtime files (logs, transaction configuration) for nodes that use this agent installation. If this property is specified, all agent logs are written to <Agent-Runtime-Directory>/logs/node-name and transaction configuration is written to the <Agent-Runtime-Directory>/conf/node-name directory.

Element in controller-info.xml: <agent-runtime-dir>

System Property: -Dappdynamics.agent.runtime.dir

Type: String

Default: <Agent_Installation_Directory>/nodes

Required: No

Redirect Logfiles Property

Description: This property sets the destination directory to which to redirect log files for a node.

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.agent.logs.dir

Type: String

Default: <Agent_Installation_Directory>/logs/<Node_Name>

Required: No

Force Agent Registration Property

Description: Set to true only under the following conditions:

The Agent has been moved to a new application and/or tier from the UI
and
You want to override that move by specifying a new application name and/or tier name in the agent configuration.

Element in controller-info.xml: <force-agent-registration>

System Property: Not applicable

Type: Boolean

Default: False

Required: No

Reuse Node Name Property

Description: Set this property if you want the Controller to generate unique node names automatically using a prefix.

You can specify the prefix in the Auto Node Name Prefix Property. If you do not provide a prefix but set the reuse.nodeName property to true, the Controller uses the tier name as a prefix.

This property is useful for dynamic multi-tier clustered applications with many JVMs that have short life spans. It allows AppDynamics to reuse node names and to capture historical data for these short-lived nodes after they become historical or are deleted.

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.agent.reuse.nodeName

Type: Boolean

Default: None

Required: No

Auto Node Name Prefix Property

Description: Set this property if you want the Controller to generate node names automatically using a prefix that you provide.

The Controller generates node names based on the prefix concatenated with a number, which is incremented sequentially. For example, if you assign a value of "mynode" to this property, the Controller generates node names "mynode-1", "mynode-2" and so on.

If one of the nodes is deleted and the Reuse Node Name Property is true, the Controller will re-use the deleted node name.

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.agent.auto.node.prefix=<your_prefix>

Type: String

Default: Serial number maintained by the Controller appended to the tier name

Required: No

Cron/Batch JVM Property

Description: Set this property to true if the JVM is a batch/cron process or if you are instrumenting the main() method. This property can be used to stall the shutdown to allow the agent to send metrics before shutdown.

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.cron.vm

Type: Boolean

Default: False

Required: No

Unique Host ID Property

Description: UniqueHostId logically partitions a single physical host or virtual machine such that it appears to the Controller that the application is running on different machines. Set the value to a string that is unique across the entire managed infrastructure. The string may not contain any spaces. If this property is set on the app agent, it must be set on the machine agent as well.

See Configure Multiple Standalone Machine Agents for One Machine for Java.

System Property: -Dappdynamics.agent.uniqueHostId

Type: String

Default: None

Required: No

Learn More

App Agent for Java Configuration Properties

Where to Configure App Agent Properties

Creating and Registering Tiers

Example Java App Agent controller-info.xml File

Example Startup-up Using System Properties

Java App Server Agent Properties

Agent-Controller Communication Properties

Controller Host Property

Controller Port Property

SSL Configuration Properties

Controller SSL Enabled Property

Controller Keystore Password Property

Controller Keystore Filename Property

Force Default SSL Certificate Validation Property

Agent Identification Properties

Application Name Property

Tier Name Property

Node Name Property

Reuse Node Name Property

Reuse Node Name Prefix Property

Multi-Tenant Mode Properties

Account Name Property

Account Access Key Property

Proxy Properties for the Controller

Proxy Host Property

Proxy Port Property

Proxy User Name Property

Proxy Password Property

Other Properties

Enable Orchestration Property

Agent Runtime Directory Property

Redirect Logfiles Property

Force Agent Registration Property

Reuse Node Name Property

Auto Node Name Prefix Property

Cron/Batch JVM Property

Unique Host ID Property

Learn More