This page describes how configure a Database Agent.

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

   Use the following command if you are using Java >15:

  java -XX:+HeapDumpOnOutOfMemoryError -XX:OnOutOfMemoryError=“kill -9 %p” -jar db-agent.jar --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.security=ALL-UNNAMED

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

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

Example Database 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>
	<!-- The following attribute enables or disables SSL communications between the agent and the Controller.-->
	<controller-ssl-enabled>false</controller-ssl-enabled>
 
	<!-- The following account-related parameters are necessary only for SaaS installations-->
	<!--account-name></account-name-->

</controller-info>

Example Startup Configuration Using System Properties

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

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

Database Agent Properties

This section describes the  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_home> 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 

Value:  

• 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 Controller, for example, 192.168.1.22 or myhost or myhost.abc.com. This is the same host that you use to access the Controller UI.

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

System Property: -Dappdynamics.controller.hostName

Environment Variable: APPDYNAMICS_CONTROLLER_HOST_NAME

Type: String

Default: None

Required: Yes

Controller Port Property

Description: This is the HTTP(S) port of the Controller. This is the same port that you use to access the 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

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

Environment Variable: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY

Type: String

Default: None

Required: Yes. Earlier than 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: -Ddbagent.name=<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.

 Example: -Ddbagent.name="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

Environment Variable:  APPDYNAMICS_AGENT_UNIQUE_HOST_ID

Multi-Tenant Mode Properties

If the Controller is running in multi-tenant mode or if you are using the 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 SaaS Controller, the Account Name is in the Welcome email sent to you.

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

System Property: -Dappdynamics.agent.accountName

Environment Variable: APPDYNAMICS_AGENT_ACCOUNT_NAME

Type: String

Default: None

Required: 

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

Environment Variable: APPDYNAMICS_CONTROLLER_SSL_ENABLED

Type: Boolean

Default: False

Required: No