This page describes how to maintain the AppDynamics Java Agent and how to tune its configuration for your requirements. These include, for example, how to upgrade the agent to a new version and how configure SSL for the agent.

Configuration Options and Precedence

You can control many aspects of the operation of the Java Agent through its configuration settings. The agent provides several approaches for specifying these settings, as listed below.

The order of the list matches the priority of the settings. The agent applies the first non-empty value for a configuration property it encounters, given the following order.  

  1. Environment variables. See Use Environment Variables for Java Agent Settings.
  2. System properties passed in the start command for the JVM.
  3. Versioned agent properties: <agent_home>/<version_number>/conf/agent.properties.
  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.

Not all properties are available as environment variables, system properties, or XML elements for the controller-config.xml. Property references include only the available configuration methods.

Choose 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. See Instrument Multiple JVMs on a Single Machine for example configurations.
  • 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.

System Properties Sample Configuration

The following command demonstrates a startup script that includes system properties to start and configure the Java Agent. The 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 MyApplication.jar

System property values are case-sensitive.

Agent Properties Sample Configuration

The Java Agent does not 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 Sample File

The controller-info.xml file resides in <agent_home>/<version_number>/conf. Comments in the file from the agent distribution describe the settings. They have been removed in the following example 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> 

For a complete list of configuration settings, see Java Agent Configuration Properties.