AppDynamics switched from Semantic Versioning to Calendar Versioning starting in February 2020 for some agents and March 2020 for the entire product suite.

    Skip to end of metadata
    Go to start of metadata

    This page includes the details for configuring a Database Agent.

    Related pages:

    Your Rating:
    1 Star2 Star3 Star4 Star5 Star
    33 rates

    Where to Configure Database Agent Properties

    You can configure agent properties in the following locations:

    • The controller-info.xml file located in the <db_agent_home>/conf directory
    • The system properties (-D options) section in the JVM start-up command. The system properties override the settings in the controller-info.xml file. System properties are case-sensitive.  

      java -XX:+HeapDumpOnOutOfMemoryError -XX:OnOutOfMemoryError=“kill -9 %p” -jar db-agent.jar

      Alternatively, you can use a script to start the agent.

      Windowsstart-dbagent.bat -Xms<min_heap_size> -Xmx<max_heap_size>

      ./start-dbagent -Xms<min_heap_size> -Xmx<max_heap_size> &

    Example Database Agent controller-info.xml File

    	<?xml version="1.0" encoding="UTF-8"?>
    	<!-- The following attribute enables or disables SSL communications between the agent and the Controller.-->
    	<!-- The following account-related parameters are necessary only for SaaS installations-->

    Example Startup Configuration Using System Properties

    A bash example. Note that the system properties are case-sensitive.

    -Dappdynamics.controller.hostName= -Dappdynamics.controller.port=8090 

    Database Agent Properties

    This section describes the Database Agent configuration properties, including their controller-info-xml elements and their system property options.

    Required System Properties

    Path to the Agent jar File 

    Description: Provides the absolute path to the jar file.

    System Property: -jar

    Value: <db_agent_home>db-agent-jar

    Type: ASCII string, including spaces. If <db_agent_name> contains spaces, you must enclose the entire name in double quotes (" ").

    Required: Yes 

    Example: -jar="D:\AppDynamics\Database Agent\db-agent.jar"

    Path to the Java Library 

    Description: Provides the absolute path to  sqlijdbc_auth.dll.  

    System Property: -Djava.library.path 


    • For 64-bit systems: <db_agent_home>\auth\x64
    • For 32-bit systems: <db_agent_home>\auth\x32 

    Type: ASCII string, including spaces. If <db_agent_home> contains spaces, you must enclose the entire name in double quotes (" ").

    Required: Recommended. Required for SQL Server Windows Authentication on Windows 64-bit systems. 

    Example: -Djava.library.path="D:\AppDynamics\Database Agent\auth\x64"

    Optional System Properties

    Disable Retry on Auth Failure

    Description: Stops retrying to establish JDBC connection when JDBC authentication fails. 

    System Property: -Dretry.on.auth.failure=false 

    Default: The system property is set to true.

    Type: String

    Supported Locales for Parsing Numbers

    Description: Specifies which locale to use for parsing numbers. See Java 7 Supported Locales or Java 8 Supported Locales for valid values. Use the values for the Java version that you are running in your environment.

    System Property: -Ddbagent.language

    Default: The system property is set to en-US or en_US.

    Type: String

    Agent-Controller Communication Properties

    Controller Host Property

    Description: This is the host name or the IP address of the AppDynamics Controller, e.g. or myhost or This is the same host that you use to access the AppDynamics Controller UI.

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

    System Property: -Dappdynamics.controller.hostName


    Type: String

    Default: None

    Required: Yes

    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 premises installations, port 8090 for HTTP and port 8181 for HTTPS are the default ports the Controller listens to.
    For the SaaS Controller Service, port 80 for HTTP and port 443 for HTTPS are the default ports the Controller listens to.

    Required: Yes

    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 Property: -Dappdynamics.agent.accountAccessKey


    Type: String

    Default: None

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

    Multiple Agent Environment Properties

    The following properties are useful when you are configuring your system to include more than one Database Agent.

    Database Agent Name Property

    Description: This property uniquely identifies the Database Agent to the Controller. 

    System Property:<db_agent_name>

    Type: ASCII string, including spaces. If <agent_name> contains spaces, you must enclose the entire name in double quotes (" ").

    Default:  Default Database Agent 

    Required:  Required when you have more than one Database Agent reporting to the Controller.

     You may want to run multiple Database Agents under the following conditions:

    • When you have databases spread across multiple networks, and one machine cannot access all the databases on all the networks. In this case, you can have a uniquely named Database Agent in each network that monitors the databases only visible on that network. 
    • If you have multiple SQL Server instances that each require different credentials, and you want to connect to them via Windows Authentication. When using Windows Authentication, the Database Agent will use the credentials of the currently logged in user. 
    • When you want one or more agents to back up a primary agent. The database agent names for your backup agents must match the database agent name of your primary agent. The last agent you launch will be the primary agent."Scarborough Network Database Agent"

    Unique Host ID

    Description: The Unique Host ID 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 must not contain any spaces. If you have a machine agent that is running on the same host as that of the database agent, then this property value must be different than that of the machine agent. If you are running multiple database agents from the same host with the same name, then this property value must be different for those agents.

    System Property: -Dappdynamics.agent.uniqueHostId

    Type: String

    Default:  None


    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.

    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 in the Welcome email AppDynamics sent to you.

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

    System Property: -Dappdynamics.agent.accountName


    Type: String

    Default: None


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

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

    Description:  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.

    If Use Encrypted Credentials is false, enter the password in plain text. If Use Encrypted Credentials is true, encrypt the password. See Encrypt Agent Credentials.

    Element in controller-info.xml: Not applicable

    System Property: -Dappdynamics.http.proxyPasswordFile

    Type: String

    Default: None

    Required: No

    Other 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