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


On this page:

Related pages:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
56 rates

This topic is a reference for the configuration mechanisms and configuration properties for the AppDynamics Java Agent. 

Configuration Options and Precedence

The Java Agent applies configurations from the following sources in order. The agent applies the first non-empty value for a configuration property. 

  1. Environment variablesSee Use Environment Variables for Java Agent Settings.
  2. System properties passed in the start command for the JVM.
  3. New in 4.1.4, Versioned agent properties: <agent_home>/<version_number>/conf/agent.properties.
  4. New in 4.1.4, Global agent properties: <agent_home>/conf/agent.properties.
  5. Versioned configuration file: <agent_home>/<version_number>/conf/controller-info.xml.

  6. Global configuration file: <agent_home>/conf/controller-info.xml.

Choosing an Effective Configuration Strategy

  • Use versioned agent properties and versioned configuration files before using global agent properties and global configuration files. This minimizes any impact of configuration format changes in future agent releases.
  • The agent only reads versioned agent properties and versioned configuration files from one versioned directory. During upgrades, manually migrate configurations from directories for previous versions. See Upgrade the Java Agent.
  • The Agent Download Wizard automatically configures the agent using a versioned configuration file. The configuration in controller-info.xml statically defines the agent identity.
  • For dynamic or elastic environments that require flexible agent identity, use an approach that provides for the dynamic node identification.
    For example, pass node identify or other agent configuration settings dynamically using environment variables or system properties. 
  • For shared binaries among multiple JVM instances, AppDynamics recommends you use a combination of configuration files and startup properties to configure the app agent. In this case, you configure properties common to all JVMs in the controller-info.xml file. Then specify the properties unique to each JVM using environment variables or system properties.
    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 tier, configure the application name and tier name in the controller-info.xml file and the node name using the system properties.

For some properties, you can use system properties already defined in the startup script as the Java Agent property values. For more information, see Use System Properties for Java Agent Settings.

Sample Configurations

System Properties Configuration

The following command demonstrates a startup script that includes system properties to start and configure the Java Agent. The business application is "ACMEOnline", the tier is "Inventory", and the node is "Inventory1". SampleApplication is the application file. 

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

System property values are case-sensitive.

Agent Properties Configuration

The Java Agent doesn't include an agent.properties file by default. The file is a list of key-value pairs of system properties. For example:

appdynamics.controller.hostName=mycontroller.example.com
appdynamics.controller.port=8090
  • The JVM treats properties from the agent.properties file the same as system properties. Values in agent.properties do not override any properties passed explicitly in the JVM startup script.
  • You can also include system properties not specific to AppDynamics in the agent.properties file. Values from agent.properties do not override values passed in the JVM startup script.
  • Do not include -D switch for keys in the agent.properties file.

controller-info.xml File

The controller-info.xml file resides in the ver<number>/conf subdirectory in the Java Agent home.  The following listing represents a simple example of the configuration file. Comments in the file included with the agent describe the settings, although they have been removed from the following listing for brevity.

<?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>customer1</account-name>
	<account-access-key>341bf72e-7d7a-1234-b33d-9n712nn574</account-access-key>
	<force-agent-registration>false</force-agent-registration>
</controller-info> 

Agent-Controller Communication Properties

Controller Host Property

The host name or the IP address of the AppDynamics Controller. Example values are 192.168.1.22 or myhost or myhost.example.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.

If you are using an environment variable to define the controller host, you must also use an environment variable to define the controller port, otherwise the host value will be overridden by the value specified in the controller-info.xml file.

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

System Property: -Dappdynamics.controller.hostName

Environment Variable: APPDYNAMICS_CONTROLLER_HOST_NAME

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

The HTTP(S) port of the AppDynamics Controller. This is the port used 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.

If you are using an environment variable to define the controller port, you must also use an environment variable to define the controller host, otherwise the port value will be overridden by the value specified in the controller-info.xml file.

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

System Property: -Dappdynamics.controller.port

Environment Variable: APPDYNAMICS_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

If true, 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

Environment Variable: APPDYNAMICS_CONTROLLER_SSL_ENABLED

Type: Boolean

Default: False

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

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

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

AppDynamics Agent SSL Protocol Property

The SSL compatibility table in Agent - Controller Compatibility Matrix lists the default security protocol for the different versions of the Java Agent. If the default security protocol for your version of an agent is incompatible with the Controller or it is incompatible with an intervening proxy, pass the -Dappdynamics.agent.ssl.protocol system property to configure one of the following security protocols:

  • SSL
  • TLS
  • TLSv1.2
  • TLSv1.1

Element in controller-info.xml: Not applicable

System Property: -Dappdynamics.agent.ssl.protocol

Type: String

Default: See Agent - Controller Compatibility Matrix

Required: No

Agent Identification Properties

Automatic Naming Property

If enabled and other agent identification properties are not specified in other settings, the tier and application for the agent are automatically named. The default names are in the format MyApp and MyTier. 

Element in controller-info.xml: <auto-naming>

System Property: Not applicable

Type: Boolean

Default: None

Required: No

Application Name Property

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

Environment Variable: APPDYNAMICS_AGENT_APPLICATION_NAME

Type: String

Default: None

Required: Yes

Tier Name Property

The name of the 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 or application server startup script already has a system property that references a tier, such as -Dserver.tier, you can use ${server.tier} as the tier name. For more information, see Use System Properties for Java Agent Settings.

The agent registers the named tier with the Controller, if the tier does not already exist, the first time it connects with the Controller. If a tier with the name already exists in the Controller model, the agent is associated with the existing tier. 

See Business Application, Tier, and Node Naming.

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

System Property: -Dappdynamics.agent.tierName

Environment Variable: APPDYNAMICS_AGENT_TIER_NAME

Type: String

Default: None

Required: Yes

Node Name Property

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

If your JVM or application server startup 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 Use System Properties for Java Agent Settings 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 Business Application, Tier, and Node Naming.

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

System Property: -Dappdynamics.agent.nodeName

Environment Variable: APPDYNAMICS_AGENT_NODE_NAME

Type: String

Default: None

Required: Yes

Reuse Node Name Property

Set this property to true to reuse node names in AppDynamics. When you set the property to true, you don't need to supply a node name, but you do need to provide a node name prefix using -Dappdynamics.agent.reuse.nodeName.prefix .

This property is useful for monitoring environments where there are many JVMs with short life spans. When true, AppDynamics reuses the node names of historical JVMs for new JVMs. This avoids a proliferation of differently named nodes in AppDynamics over time, particularly when the nodes are essentially identical processes that run over different times. An example of this environment is a z/OS Dynamic Workload Manager based-environment where new JVMs are launched and shut down 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).

The node name is generated by the Controller. The Controller reuses node names based on the node retention period property.

Element in controller-info.xml:  Not applicable

System Property: -Dappdynamics.agent.reuse.nodeName

Type: Boolean

Default: False

Required: No

Example: With the following configuration, the Controller generates a node name with the prefix "reportGen". Node names will have suffixes --1, --2, and so on, depending on the number of nodes are running in parallel. The name of a node that is shut down and qualifies as a historical node may be reused by a new node. 

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

Reuse Node Name Prefix Property

When you configure the agent to reuse node names, use this property to specify the prefix the Controller uses to generate node names dynamically.  

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

Element in controller-info.xml:  Not applicable

Type: String

Default: None

Required: When -Dappdynamics.agent.reuse.nodeName=true

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, and so on, depending on how many nodes are running in parallel.

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

Account 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 key for the 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_home>/initial_account_access_info.txt file.

If the Controller is running in single-tenant mode (the case for most on-premise installations), you only need to configure the account access key. You can find the unique access key for your Controller instance from the License Information page in the UI. 

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

Environment Variable: APPDYNAMICS_AGENT_ACCOUNT_NAME

Type: String

Default: None

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

Account Access Key Property

The account access key used to authenticate with the Controller.

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

System Properties: -Dappdynamics.agent.accountAccessKey

Environment Variable: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY

Type: String

Default: None

Required: Yes

Proxy Properties for the Controller

Use the proxy properties to configure the agent to connect to the Controller through a proxy. 

Proxy authentication cannot be used in conjunction with agent SSL. To connect the agent through a proxy via SSL, the proxy must be open (not require the agent to authenticate).

Proxy Host Property

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

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

Other Properties

Enable Orchestration Property

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

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

Environment Variable: APPDYNAMICS_AGENT_BASE_DIR 

Type: String

Default: <agent_home>/nodes

Required: No

Redirect Logfiles 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_home>/logs/<Node_Name>

Required: No

Force Agent Registration Property

Set to true only under the following conditions:

  • The agent has been moved to a new application or tier from the UI, and
  • You want to override that move by specifying a new application name 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

Auto Node Name Prefix Property

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 a suffix consisting of a number that is incremented sequentially with each new node. For example, if you assign a value of "mynode" to this property, the Controller generates node names "mynode-1", "mynode-2" and so on.

This property provides a similar function to the Reuse Node Name Prefix Property property. However, this property is not meant to be used in combination with reusing node names; use Reuse Node Name Prefix Property for those cases instead. 

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

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

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.

System Property: -Dappdynamics.agent.uniqueHostId

Environment Variable: APPDYNAMICS_AGENT_UNIQUE_HOST_ID

Type: String

Default: None

Required: No

Agent Meta Info Property

Allows you to associate arbitrary information with a node, which can then be used as a basis for applying health rules or policies by node. For example, you can exclude a health rule from applying to agents tagged as test agents based on a meta-info property. Pass the property in key:value format (for example, "key1;value1;key2:value2"). 

For information on using the properties in health rules or policies (along with built-in meta-info properties), see Configure Health Rules or Configure Policies

System Property: -Dappdynamics.agent.node.metainfo 

Type: String

Default: None

Required: No

Hot Spot Learning on Controller

Enables or disables hotspot learning on the Controller. Setting this option to false disables everything related to the hot spot feature. For more information on hot spots, see Transaction Snapshots.

System Property: -Dappdynamics.hotspot.learn.enabled

Type: String

Default: True

Required: No