Database Visibility API

This page describes the Database Visibility API methods you can use to get, create, update, and delete Database Visibility Collectors.

Include the following headers for all Database Visibility API requests:

Accept: application/json; Content-type: application/json

CODE

JSON is currently the only supported format.

Database Visibility uses infrastructure-based licensing, where there is no direct correlation between the database collector and license usage. Therefore for Controller version >=21.2, the licensesUsed parameter always returns -1.

Get All Collectors

GET /controller/rest/databases/collectors

CODE

Get a Specific Collector

GET /controller/rest/databases/collectors/{configurationId}

CODE

Create a Collector

POST /controller/rest/databases/collectors/create

CODE

The JSON you send must contain the relevant Collector information. The required fields describing the Collector vary based on the type of database. See UI Collector versus JSON Collector Configuration Field Names

Example JSON Request

{
    "type":"MYSQL",
    "name":"localdocker_dbagent-MySQLCollector",
    "hostname":"mysql",
    "port":"3306",
    "username":"root",
    "password":"appdynamics_redacted_password",
    "enabled":true,
    "excludedSchemas":null,
    "databaseName":null,
    "failoverPartner":null,
    "connectAsSysdba":false,
    "useServiceName":false,
    "sid":null,
    "customConnectionString":null,
    "enterpriseDB":false,
    "useSSL":false,
    "enableOSMonitor":false,
    "hostOS":null,
    "useLocalWMI":false,
    "hostDomain":null,
    "hostUsername":null,
    "hostPassword":"",
    "dbInstanceIdentifier":null,
    "region":null,
    "certificateAuth":false,
    "removeLiterals":true,
    "sshPort":0,
    "agentName":"localdocker_dbagent",
    "dbCyberArkEnabled":false,
    "dbCyberArkApplication":null,
    "dbCyberArkSafe":null,
    "dbCyberArkFolder":null,
    "dbCyberArkObject":null,
    "hwCyberArkEnabled":false,
    "hwCyberArkApplication":null,
    "hwCyberArkSafe":null,
    "hwCyberArkFolder":null,
    "hwCyberArkObject":null,
    "orapkiSslEnabled":false,
    "orasslClientAuthEnabled":false,
    "orasslTruststoreLoc":null,
    "orasslTruststoreType":null,
    "orasslTruststorePassword":"",
    "orasslKeystoreLoc":null,
    "orasslKeystoreType":null,
    "orasslKeystorePassword":"",
    "ldapEnabled":false,
    "customMetrics":null,
    "subConfigs":[
        {
            "type":"MYSQL",
            "name":"localdocker_dbagent-MySQLCollector sub-collector",
            "hostname":"mysql-remote",
            "port":"3388",
            "username":"root",
            "password":"different-password",
            "enabled":true,
            "excludedSchemas":null,
            "databaseName":null,
            "failoverPartner":null,
            "connectAsSysdba":false,
            "useServiceName":false,
            "sid":null,
            "customConnectionString":null,
            "enterpriseDB":false,
            "useSSL":false,
            "enableOSMonitor":false,
            "hostOS":null,
            "useLocalWMI":false,
            "hostDomain":null,
            "hostUsername":null,
            "hostPassword":"",
            "dbInstanceIdentifier":null,
            "region":null,
            "certificateAuth":false,
            "removeLiterals":true,
            "sshPort":0,
            "agentName":"localdocker_dbagent",
            "dbCyberArkEnabled":false,
            "dbCyberArkApplication":null,
            "dbCyberArkSafe":null,
            "dbCyberArkFolder":null,
            "dbCyberArkObject":null,
            "hwCyberArkEnabled":false,
            "hwCyberArkApplication":null,
            "hwCyberArkSafe":null,
            "hwCyberArkFolder":null,
            "hwCyberArkObject":null,
            "orapkiSslEnabled":false,
            "orasslClientAuthEnabled":false,
            "orasslTruststoreLoc":null,
            "orasslTruststoreType":null,
            "orasslTruststorePassword":"",
            "orasslKeystoreLoc":null,
            "orasslKeystoreType":null,
            "orasslKeystorePassword":"",
            "ldapEnabled":false,
            "customMetrics":null
        }
    ]
}

JSON

extraProperties: To configure the frequency for sampling queries from the database (except Cassandra), you can use the extraProperties parameter in the JSON request payload. The following JSON sample can be used in the request payload to configure the sampling interval:

{
    "type":"POSTGRESQL",
    "agentName":"UpgradeTest204",
    "name":"SamplingInterval",
    "hostname":"ec2-54-202-140-213.us-west-2.compute.amazonaws.com",
    "port":"5432",
    "username":"postgres",
    "password":"Appd123",
    "removeLiterals":"true",
    "enableOSMonitor":"true",
    "hostOS":"LINUX",
    "sshPort":"22",
    "hostUsername":"ec2-user",
    "hostPassword":"",
    "certificateAuth":true,
    "enabled":"true",
    "enterpriseDB":"false",
    "extraProperties":[
        {
            "key":"dbagent.sampling.interval",
            "value":"10",
            "sensitive":false
        }
    ]
}

JSON

The following JSON key-value pair is used in extraProperties for configuring the interval:

key: dbagent.sampling.interval

value: positive integer

The value can be 1, 2, 5, 10, 20, or 30.

You can configure this property through the agent. See Configure the Agent Settings for Monitoring Database.

Update a Collector

Make a GET request for the collector that you want to update.
Copy the JSON response body that is returned by the GET request to a text editor, and modify the fields that you want to update.

Make a POST request for the collector that you want to update, and include the updated JSON.

POST /controller/rest/databases/collectors/update

CODE

Example JSON Request

{
    "id":1,
    "type":"MYSQL",
    "name":"localdocker_dbagent-MySQLCollector",
    "hostname":"mysql",
    "port":"3306",
    "username":"root",
    "password":"appdynamics_redacted_password",
    "enabled":true,
    "excludedSchemas":null,
    "databaseName":null,
    "failoverPartner":null,
    "connectAsSysdba":false,
    "useServiceName":false,
    "sid":null,
    "customConnectionString":null,
    "enterpriseDB":false,
    "useSSL":false,
    "enableOSMonitor":false,
    "hostOS":null,
    "useLocalWMI":false,
    "hostDomain":null,
    "hostUsername":null,
    "hostPassword":"",
    "dbInstanceIdentifier":null,
    "region":null,
    "certificateAuth":false,
    "removeLiterals":true,
    "sshPort":0,
    "agentName":"localdocker_dbagent",
    "dbCyberArkEnabled":false,
    "dbCyberArkApplication":null,
    "dbCyberArkSafe":null,
    "dbCyberArkFolder":null,
    "dbCyberArkObject":null,
    "hwCyberArkEnabled":false,
    "hwCyberArkApplication":null,
    "hwCyberArkSafe":null,
    "hwCyberArkFolder":null,
    "hwCyberArkObject":null,
    "orapkiSslEnabled":false,
    "orasslClientAuthEnabled":false,
    "orasslTruststoreLoc":null,
    "orasslTruststoreType":null,
    "orasslTruststorePassword":"",
    "orasslKeystoreLoc":null,
    "orasslKeystoreType":null,
    "orasslKeystorePassword":"",
    "ldapEnabled":false,
    "customMetrics":null,
    "subConfigs":[
        {
            "id":2,
            "type":"MYSQL",
            "name":"localdocker_dbagent-MySQLCollector sub-collector",
            "hostname":"mysql",
            "port":"3388",
            "username":"root",
            "password":"appdynamics-redacted-password",
            "enabled":true,
            "excludedSchemas":null,
            "databaseName":null,
            "failoverPartner":null,
            "connectAsSysdba":false,
            "useServiceName":false,
            "sid":null,
            "customConnectionString":null,
            "enterpriseDB":false,
            "useSSL":false,
            "enableOSMonitor":false,
            "hostOS":null,
            "useLocalWMI":false,
            "hostDomain":null,
            "hostUsername":null,
            "hostPassword":"",
            "dbInstanceIdentifier":null,
            "region":null,
            "certificateAuth":false,
            "removeLiterals":true,
            "sshPort":0,
            "agentName":"localdocker_dbagent",
            "dbCyberArkEnabled":false,
            "dbCyberArkApplication":null,
            "dbCyberArkSafe":null,
            "dbCyberArkFolder":null,
            "dbCyberArkObject":null,
            "hwCyberArkEnabled":false,
            "hwCyberArkApplication":null,
            "hwCyberArkSafe":null,
            "hwCyberArkFolder":null,
            "hwCyberArkObject":null,
            "orapkiSslEnabled":false,
            "orasslClientAuthEnabled":false,
            "orasslTruststoreLoc":null,
            "orasslTruststoreType":null,
            "orasslTruststorePassword":"",
            "orasslKeystoreLoc":null,
            "orasslKeystoreType":null,
            "orasslKeystorePassword":"",
            "ldapEnabled":false,
            "customMetrics":null
        }
    ]
}

JSON

The JSON you send must contain all the details of the existing collector with only the fields that you want to modify changed. To ensure you have all the fields, use the Get a Specific Collector call.

To add a new sub-collector to an existing collector, provide the sub-collector details without the id field.

To configure the interval for sampling queries, refer to the extraProperties parameter in the JSON request payload as mentioned in extraProperties under Create a Collector.

Delete a Specific Collector

DELETE /controller/rest/databases/collectors/{configurationId}

CODE

Example Delete Request

DELETE /controller/rest/databases/collectors/{1}

CODE

Batch Delete Multiple Collectors

POST /controller/rest/databases/collectors/batchDelete

CODE

Send an array of the configuration Ids of the Collectors.

Below is an example of a batch delete command.

curl --user {username}@{account_name}:{password} -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '[1,2,3]' {Controller_URL}/controller/rest/databases/collectors/batchDelete

CODE

Get All Monitored Database Servers

GET /controller/rest/databases/servers

CODE

Example

curl --user {username}@{account_name}:{password} {Controller_URL}/controller/rest/databases/servers

CODE

The output is a list of database servers and their details.

Get Database Server Details

GET /controller/rest/databases/servers/{dbserver_id}

CODE

Example

curl --user {username}@{account_name}:{password} {Controller_URL}/controller/rest/databases/servers/{dbserver_id}

CODE

The output contains a list of the database's details, including name, node ID, and database type.

Get all Database Agent Events

GET /controller/rest/applications/_dbmon/events

CODE

For a list of query string parameters, see Retrieve Event Data.

Example

curl --user {username}@{account_name}:{password} {Controller_URL}/controller/rest/applications/_dbmon/events?time-range-type=BEFORE_NOW&duration-in-mins=30&event-types=%20AGENT_EVENT,DB_SERVER_PARAMTER_CHANGE&severities=INFO,WARN,ERROR

CODE

The output gives you a list of events. For each event element, you can determine the node that the event is mapped to by looking for the entity-definition element.

Get all Database Monitoring Application Nodes

GET /controller/rest/applications/_dbmon/nodes

CODE

Example

curl --user {username}@{account_name}:{password} {Controller_URL}/controller/rest/applications/_dbmon/nodes

CODE

UI Collector versus JSON Collector Configuration Field Names

Use the table below to ensure you use the correct field names for your API calls. The Collector configuration field names are described in Configure the Database Agent to Monitor Server Hardware and Add Database Collectors.

Section	UI Collector Configuration Field Name	JSON Collector Configuration Field Name
		id (AppDynamics assigns this ID to the Collector when you configure the Collector. You need this ID when doing a batch delete.)
	Database Type	`type`
	Database Agent	`agentName`
	Database	`name`
Connection Details	Hostname/IP Address	`hostname`
	EnterpriseDB	`enterpriseDB`
	Failover Partner	`failoverPartner`
	Listener Port	`port`
	Custom JDBC Connection String	`customConnectionString`
	Use Service Name	`useServiceName`
	SID or SERVICE_NAME	`sid`
	Connect as a sysdba	`connectAsSysdba`
	Username	`username`
	Password	`password`
	Logging Enabled
Hardware Monitoring	Monitor Operating System	`enableOSMonitor`
	Operating System	`hostOS`
	Use Local WMI	`useLocalWMI`
	Domain	`hostDomain`
	SSH Port	`sshPort`
	Use certificate	`certificateAuth`
	Username	`hostUsername`
	Password	`hostPassword`

SSL field

In addition to JSON Configuration Fields, there is the SSL field. SSL is a configurable property for the Database Agent. If the Database Agent has been configured to use SSL, then you must also provide the SSL field and its value in your Database Visibility API calls.

Get Health Rule Violations for a Collector

GET /controller/rest/databases/servers/healthrule-violations/<server-id>

CODE

Input parameters

Parameter Name	Parameter Type	Value	Mandatory
`server_id`	URI	Provide the databse server name or ID.	Yes
`time-range-type`	Query	Possible values are: `BEFORE_NOW` To use the "`BEFORE_NOW"` option, you must also specify the "`duration-in-mins"` parameter. `BEFORE_TIME` To use the "`BEFORE_TIME"` option, you must also specify the "`duration-in-mins"` and "`end-time"` parameters. `AFTER_TIME` To use the "`AFTER_TIME"` option, you must also specify the "`duration-in-mins"` and "`start-time"` parameters. `BETWEEN_TIMES` To use this option, you must also specify the "`start-time`" and "`end-time`" parameters. The "`BETWEEN_TIMES"` range includes the start-time and excludes the end-time.	Yes
`duration-in-mins`	Query	Duration (in minutes) to return the metric data.	If time-range-type is `BEFORE_NOW, BEFORE_TIME,` or `AFTER_TIME`
`start-time`	Query	Start time (in milliseconds) from which the metric data is returned.	If time-range-type is `AFTER_TIME` or `BETWEEN_TIMES`
`end-time`	Query	End time (in milliseconds) until which the metric data is returned.	If time-range-type is `BEFORE_TIME` or `BETWEEN_TIMES`
`output`	Query	HTTP Request parameter included as part of the URL to change the output format. Valid values are `XML` (default) or `JSON`.	No

Example

curl --user {username}@{account_name}:{password} {Controller_URL}/controller/rest/databases/servers/healthrule-violations/<server-id>?time-range-type=BEFORE_NOW&duration-in-mins=<required_duration>

CODE