Using the Application Discovery Service API to query discovered configuration items
A configuration item is an IT asset that was discovered in your data center by an agent or by an import. When you use AWS Application Discovery Service (Application Discovery Service), you use the API to specify filters and query specific configuration items for server, application, process, and connection assets. For information about the API, see Application Discovery Service API Reference.
The tables in the following sections list the available input filters and output sorting options for two Application Discovery Service actions:
-
DescribeConfigurations
-
ListConfigurations
The filtering and sorting options are organized by the type of asset to which apply (server, application, process, or connection).
Important
Results returned by DescribeConfigurations
, ListConfigurations
,
and StartExportTask
might not contain recent updates. For more information, see
Eventual consistency in the AWS Application Discovery Service API.
Using the DescribeConfigurations
action
The DescribeConfigurations
action retrieves attributes for a list of
configuration IDs. All the supplied IDs must be for the same asset type (server, application,
process, or connection). Output fields are specific to the asset type selected. For example,
the output for a server configuration item includes a list of attributes about the server,
such as host name, operating system, and number of network cards. For more information about
command syntax, see DescribeConfigurations.
The DescribeConfigurations
action does not support filtering.
Output fields for DescribeConfigurations
The following tables, organized by asset type, list the supported output fields of the
DescribeConfigurations
action. The ones marked as mandatory are always present
in the output.
Server assets
Field | Mandatory |
---|---|
server.agentId |
|
server.applications |
|
server.applications.hasMoreValues |
|
server.configurationId |
x |
server.cpuType |
|
server.hostName |
|
server.hypervisor |
|
server.networkInterfaceInfo |
|
server.networkInterfaceInfo.hasMoreValues |
|
server.osName |
|
server.osVersion |
|
server.tags |
|
server.tags.hasMoreValues |
|
server.timeOfCreation |
x |
server.type |
|
server.performance.avgCpuUsagePct |
|
server.performance.avgDiskReadIOPS |
|
server.performance.avgDiskReadsPerSecondInKB |
|
server.performance.avgDiskWriteIOPS |
|
server.performance.avgDiskWritesPerSecondInKB |
|
server.performance.avgFreeRAMInKB |
|
server.performance.avgNetworkReadsPerSecondInKB |
|
server.performance.avgNetworkWritesPerSecondInKB |
|
server.performance.maxCpuUsagePct |
|
server.performance.maxDiskReadIOPS |
|
server.performance.maxDiskReadsPerSecondInKB |
|
server.performance.maxDiskWriteIOPS |
|
server.performance.maxDiskWritesPerSecondInKB |
|
server.performance.maxNetworkReadsPerSecondInKB |
|
server.performance.maxNetworkWritesPerSecondInKB |
|
server.performance.minFreeRAMInKB |
|
server.performance.numCores |
|
server.performance.numCpus |
|
server.performance.numDisks |
|
server.performance.numNetworkCards |
|
server.performance.totalRAMInKB |
Process assets
Field | Mandatory |
---|---|
process.commandLine |
|
process.configurationId |
x |
process.name |
|
process.path |
|
process.timeOfCreation |
x |
Application assets
Field | Mandatory |
---|---|
application.configurationId |
x |
application.description |
|
application.lastModifiedTime |
x |
application.name |
x |
application.serverCount |
x |
application.timeOfCreation |
x |
Using the ListConfigurations
action
The ListConfigurations
action retrieves a list of configuration items
according to the criteria that you specify in a filter. For more information about command
syntax, see ListConfigurations.
Output fields for
ListConfigurations
The following tables, organized by asset type, list the supported output fields of the
ListConfigurations
action. The ones marked as mandatory are always present in
the output.
Server assets
Field | Mandatory |
---|---|
server.configurationId |
x |
server.agentId |
|
server.hostName |
|
server.osName |
|
server.osVersion |
|
server.timeOfCreation |
x |
server.type |
Process assets
Field | Mandatory |
---|---|
process.commandLine |
|
process.configurationId |
x |
process.name |
|
process.path |
|
process.timeOfCreation |
x |
server.agentId |
|
server.configurationId |
x |
Application assets
Field | Mandatory |
---|---|
application.configurationId |
x |
application.description |
|
application.name |
x |
application.serverCount |
x |
application.timeOfCreation |
x |
application.lastModifiedTime |
x |
Connection assets
Field | Mandatory |
---|---|
connection.destinationIp |
x |
connection.destinationPort |
x |
connection.ipVersion |
x |
connection.latestTimestamp |
x |
connection.occurrence |
x |
connection.sourceIp |
x |
connection.transportProtocol |
|
destinationProcess.configurationId |
|
destinationProcess.name |
|
destinationServer.configurationId |
|
destinationServer.hostName |
|
sourceProcess.configurationId |
|
sourceProcess.name |
|
sourceServer.configurationId |
|
sourceServer.hostName |
Supported filters for
ListConfigurations
The following tables, organized by asset type, list the supported filters for the
ListConfigurations
action. Filters and values are in a key/value relationship
defined by one of the supported logical conditions. You can sort the output of the indicated
filters.
Server assets
Filter |
Supported conditions |
Supported values |
Supported sorting |
---|---|---|---|
server.configurationId |
|
|
None |
server.hostName |
|
|
|
server.osName |
|
|
|
server.osVersion |
|
|
|
server.agentId |
|
|
None |
server.connectorId |
|
|
None |
server.type |
|
String with one of the following values:
|
None |
server.vmWareInfo.morefId |
|
|
None |
server.vmWareInfo.vcenterId |
|
|
None |
server.vmWareInfo.hostId |
|
|
None |
server.networkInterfaceInfo.portGroupId |
|
|
None |
server.networkInterfaceInfo.portGroupName |
|
|
None |
server.networkInterfaceInfo.virtualSwitchName |
|
|
None |
server.networkInterfaceInfo.ipAddress |
|
|
None |
server.networkInterfaceInfo.macAddress |
|
|
None |
server.performance.avgCpuUsagePct |
|
|
None |
server.performance.totalDiskFreeSizeInKB |
|
|
None |
server.performance.avgFreeRAMInKB |
|
|
None |
server.tag.value |
|
|
None |
server.tag.key |
|
|
None |
server.application.name |
|
|
None |
server.application.description |
|
|
None |
server.application.configurationId |
|
|
None |
server.process.configurationId |
|
|
None |
|
|
|
None |
server.process.commandLine |
|
|
None |
Application assets
Filter |
Supported conditions |
Supported values |
Supported sorting |
---|---|---|---|
application.configurationId |
|
|
None |
application.name |
|
|
|
application.description |
|
|
|
application.serverCount |
Filtering not supported. | Filtering not supported. |
|
application.timeOfCreation |
Filtering not supported. | Filtering not supported. |
|
application.lastModifiedTime |
Filtering not supported. | Filtering not supported. |
|
server.configurationId |
|
|
None |
Process assets
Filter |
Supported conditions |
Supported values |
Supported sorting |
---|---|---|---|
process.configurationId |
|
|
|
process.name |
|
|
|
process.commandLine |
|
|
|
server.configurationId |
|
|
|
server.hostName |
|
|
|
server.osName |
|
|
|
server.osVersion |
|
|
|
server.agentId |
|
|
Connection assets
Filter |
Supported conditions |
Supported values |
Supported sorting |
---|---|---|---|
connection.sourceIp |
|
|
|
connection.destinationIp |
|
|
|
connection.destinationPort |
|
|
|
sourceServer.configurationId |
|
|
|
sourceServer.hostName |
|
|
|
destinationServer.osName |
|
|
|
destinationServer.osVersion |
|
|
|
destinationServer.agentId |
|
|
|
sourceProcess.configurationId |
|
|
|
sourceProcess.name |
|
|
|
sourceProcess.commandLine |
|
|
|
destinationProcess.configurationId |
|
|
|
destinationProcess.name |
|
|
|
destinationprocess.commandLine |
|
|
|
Eventual consistency in the AWS Application Discovery Service API
The following update operations are eventually consistent. Updates might not be immediately visible to the read operations StartExportTask, DescribeConfigurations, and ListConfigurations.
Suggestions for managing eventual consistency:
-
When you invoke the read operations StartExportTask, DescribeConfigurations, or ListConfigurations (or their corresponding AWS CLI commands), use an exponential backoff algorithm to allow enough time for any previous update operation to propagate through the system. To do this, run the read operation repeatedly, starting with a two-second wait time, and increasing gradually up to five minutes of wait time.
-
Add wait time between subsequent operations, even if an update operation returns a 200 - OK response. Apply an exponential backoff algorithm starting with a couple of seconds of wait time, and increase gradually up to about five minutes of wait time.