AppDynamics Application Intelligence Platform

3.9.x Documentation

PDFs

Learn by Watching

Doc Maps

Introduction

You use the REST API to retrieve information from AppDynamics programmatically.

The AppDynamics REST API is implemented using Representational State Transfer (REST) Services. The data can be returned in either the JavaScript Object Notation (JSON) or the eXtensible Markup Language (XML) format. The default output format is XML.

The URIs in the Monitor APIs are a set of REST services that open access to Monitor data collected by AppDynamics. Each URI can be found by accessing:

http://<Controller_Host>:<Controller_Port>/controller/rest/<REST_URI>

You can find more general information about REST on Wikipedia.

You may find the REST Python Client Extension to be a useful tool.

For information about importing and exporting transaction detection configurations using REST, see Import and Export Transaction Detection Configuration for Java.

Authentication

To invoke the REST APIs, provide basic HTTP authentication credentials as well as your account information. These are:

  • Account: the AppDynamics tenant account name
  • Username: a user in that account
  • Password: the password for that account

If you have installed an on-premise Controller on a single-tenant platform or if you are using the AppDynamics SaaS Controller, your default account is "customer1". In this case the username to log in with would be:

<your_username>@customer1

If you are using a multi-tenant Controller, you need to log in with a username in your multi-tenant account:

<your_username>@<your_accountname>

Invalid Characters for Usernames

Usernames that contain the following characters are not authenticated for REST API calls:

\ / " [ ] : | < > + = ; , ? * @, ' tab space

If you have already created usernames that contain any of the disallowed characters, such as "user:customer66", create a new username without the disallowed chartacter for the purpose of accessing the REST APIs.

 

Retrieve all business applications

URI: /controller/rest/applications

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

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 - Retrieve list of all business applications.

URI

Sample object output

/controller/rest/applications

XML

/controller/rest/applications?output=JSON

JSON

Retrieve all Business Transactions in a particular business application

URI: /applications/<application-name | application-id>/business-transactions

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

exclude

Query

If false, the query retrieves only the business transactions that are included for monitoring. If true, the query retrieves only the excluded business transactions. Excluded business transactions are those that have been configured to be excluded from monitoring either from the UI or through the REST interface. The default is false.

No

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 - Retrieve list of all business transactions for the ACME Book Store.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/business-transactions

XML

/controller/rest/applications/ACME Book Store Application/business-transactions?output=JSON

JSON

Retrieve all tiers in a business application

URI: /controller/rest/applications/<application-name|application-id>/tiers

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

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 - Retrieve the list of all tiers for the ACME Book Store.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/tiers

XML

/controller/rest/applications/ACME Book Store Application/tiers?output=JSON

JSON

Retrieve machine, agent, and IP information about all nodes in a business application

URI: /controller/rest/applications/<application-name|application-id>/nodes

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

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 - Retrieve machine, agent and IP information about the nodes in application 3

URI

Sample object output

/controller/rest/applications/3/nodes

XML

Retrieve machine, agent, and IP information about a node by node name

URI: /controller/rest/applications/<application-name | application-id>/nodes/<node-name>

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

<node-name>

URI

Provide the node name

Yes

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 - Retrieve information about Node_8001 in application 3.

URI

Sample object output

/controller/rest/applications/3/nodes/Node_8001

XML

Retrieve machine, agent, and IP information about all the nodes in a tier

URI: /controller/rest/applications/<application-name | application-id>/tiers/<tier-name>/nodes

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

<tier-name>

URI

Provide the tier name.

Yes

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 - Retrieve information about the nodes in the E-Commerce tier in the ACME Online Book Store.

URI

Sample object output

/controller/rest/applications/ACME Online Book Store/tiers/E-Commerce/nodes/

XML

Retrieve information about a tier, including the tier ID and number of nodes, in a tier by tier name

URI: /controller/rest/applications/<application-name | application-id>/tiers/<tier-name>

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

<tier-name>

URI

Provide the tier name.

Yes

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 - Retrieve information about  the ECommerce tier in the ACME Online Book Store.

URI

Sample object output

/controller/rest/applications/ACME Online Book Store/tiers/ECommerce

XML

/controller/rest/applications/ACME Online Book Store/tiers/ECommerce?output=JSON

JSON

Retrieve metrics

AppDynamics groups the metrics that it collects into following categories:

  • Backends
  • End User Monitoring
  • Overall Application Performance
  • Business Transaction Performance
  • Application Infrastructure Performance
  • Errors
  • Information Points

To see the structure of the metric hierarchy of a business application in the AppDynamics UI, expand the nodes in the Metric Browser:

1. In the left navigation pane, select the application for which you are retrieving metrics.

2. Click Analyze -> Metric Browser.

3. In left panel expand the nodes in the metric tree.

You can copy the URI for fetching any metric directly from any node in the Metric Browser. This is the easiest way to construct a query to retrieve a particular metric. You can also copy just the metric path portion of the query.

The child elements in the metric path expression are separated by the pipe character (|). The pipe character must not appear at the beginning or end of the metric path expression.

The easiest way to construct a query to retrieve a metric is to select the metric in Metric Browser, copy the REST URL, rand paste it into your browser. An alternative is select the metric and  copy the metric path, and construct the query by prefacing the metric path with "metric-data?metric-path=".

To Copy the REST URL for a Metric

To copy the REST URL for any metric captured by AppDynamics:

1. Open the Metric Browser as described above.

2. Select the item for which you want to retrieve metrics in the metric tree. You can retrieve the URL at any level of the tree.

3. Right-click the item and select Copy REST URL from the drop-down menu.

4. Paste the URL into your Web browser to run the query.

The following example copies the URL for the Average Response Time in the Inventory-MSQL DB for the Acme Online Book Store application for the time period that was selected in the metric browser.

The copied query is

http://ec2-23-20-107-243.compute-1.amazonaws.com:8090/controller/rest/applications/AcmeOnlineBookStore
/metric-data?metric-path=Backends%7CINVENTORY-MySQL%20DB%7CAverage%20Response%20Time%20(ms)&time-range-type=BEFORE_NOW&duration-in-mins=15

The time range in the request is based on the setting of the time range in the Metric Browser when you copied the URL. You can edit a copied query to change the time range and duration. See Retrieve metrics for a time range for more information.

To Copy the Metric-Path Parameter

You also copy only the metric path for a specific metric.

To copy a metric path:

1. Open the Metric Browser as described above.

2. Select the item for which you want to retrieve metrics in the metric tree. You can retrieve the metric path at any level of the tree.

3. Right-click the item and select Copy Full Path from the drop-down menu.

4. Use the metric path to construct your query.

The copied data is

Business Transaction Performance|Business Transactions|E-Commerce|Add to cart

Structure of Returned Metrics

The data is returned in a tree structure. If a child element is a container item, its <type> tag is set to "folder". Otherwise the <type> tag for the child element is set to "leaf".

A folder <type> tag indicates that the metric has child elements. The API retrieves the first generation of child elements. You can expand only the children of the folder type.

Values of Returned Metrics

Results are returned in a metricValues structure that contains the following fields:

  • current
    Value for the current minute. Used only when the time rollup type used by the Controller is current.
  • count
    Number of times the agent collected the metric over the selected time period.
  • max
  • min
    The "min" and "max" values are the minimum and maximum values reported across the selected time period. These are not used for all metric types.
  • occurrences
    Number of data samples taken by the Controller to calculate the standard deviation.
  • standardDeviation
    Intermediate values calculated by the Controller during time rollup used to calculate standard deviation.
  • startTimeInMillis
    The startTimeInMillis is the start time of the time range to which the result metric data applies, in UNIX epoch time.
  • sum
    Total accumulated value for the metric over the selected time period.
  • useRange
    Used internally by the Controller to process the metric.
  • value
    The "value" value is one of the following for all metric values reported across the configured evaluation time length:
    • arithmetic average, if the metric time rollup type is average
    • sum, if the metric time rollup type is sum
    • latest, if the metric time rollup type is current

By default, the values of the returned metrics are rolled up into a single data point (rollup=true). To get separate results for all the values within the specified time range, set the rollup parameter to false in the query.

The returned metricValues structure typically looks like this:

Sample XML output with rollup=true

<metricValues>
    <metric-value>
        <startTimeInMillis>1411678680000</startTimeInMillis>
        <value>14</value>
        <min>0</min>
        <max>0</max>
        <current>6</current>
        <sum>205</sum>
        <count>30</count>
        <standardDeviation>0.0</standardDeviation>
        <occurrences>0</occurrences>
        <useRange>false</useRange>
    </metric-value>
</metricValues>

Sample XML output with rollup=false

<metricValues>
    <metric-value>
        <startTimeInMillis>1411678680000</startTimeInMillis>
        <value>28</value>
        <min>0</min>
        <max>0</max>
        <current>13</current>
        <sum>28</sum>
        <count>2</count>
        <standardDeviation>0.0</standardDeviation>
        <occurrences>0</occurrences>
        <useRange>false</useRange>
    </metric-value>
    <metric-value>
        <startTimeInMillis>1411678740000</startTimeInMillis>
        <value>17</value>
        <min>0</min>
        <max>0</max>
        <current>9</current>
        <sum>17</sum>
        <count>2</count>
        <standardDeviation>0.0</standardDeviation>
        <occurrences>0</occurrences>
        <useRange>false</useRange>
    </metric-value>
    <metric-value>
    . . . 
    . . . 

</metricValues>

Sample JSON output with rollup=true

  "metricValues": [  {
    "count": 30,
    "current": 8,
    "max": 0,
    "min": 0,
    "occurrences": 0,
    "standardDeviation": 0,
    "startTimeInMillis": 1411682880000,
    "sum": 145,
    "useRange": false,
    "value": 10
  }]

Sample JSON ouput with rollup=false

 "metricValues":   [
        {
      "count": 2,
      "current": 1,
      "max": 0,
      "min": 0,
      "occurrences": 0,
      "standardDeviation": 0,
      "startTimeInMillis": 1411682760000,
      "sum": 2,
      "useRange": false,
      "value": 2
    },
        {
      "count": 2,
      "current": 1,
      "max": 0,
      "min": 0,
      "occurrences": 0,
      "standardDeviation": 0,
      "startTimeInMillis": 1411682820000,
      "sum": 4,
      "useRange": false,
      "value": 4
    },
    . . . 
    . . . 
 

Retrieve metric hierarchy

URI: /controller/rest/applications/<application-name| application-id>/metrics

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

metrics

Query

 

Yes

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 - Retrieve the metric hierarchy for the ACME Book Store Application.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metrics

XML

/controller/rest/applications/ACME Book Store Application/metrics?output=JSON

JSON

Use Wild cards in Metric-Path Parameter

You can use the asterisk (*) wild card in the metric data to request metric data for all the instances of AppDynamics entity, such as a business transaction name, tier name or node name, in the metric path.

Example - Retrieve the average response time for all the tiers in the application using the wild card character for the tier name.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance|*|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance|*|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON

JSON

Example - Retrieve the CPU %Busy metric for all the nodes in the ECommerce tier using the wild card character for the node name.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|ECommerce Server|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|ECommerce Server|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15=JSON

JSON

Example - Retrieve the CPU %Busy metric for all the nodes in all the tiers using wild card characters for the tier and node names.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|*|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Application Infrastructure Performance|*|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON

JSON

Example - Retrieve the Calls per Minute metric for all the business transactions on the ECommerce tier using the wild card character for the business transaction name

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance|Business Transactions|ECommerce Server|*|Calls per Minute&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance|Business Transactions|ECommerce Server|*|Calls per Minute&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON

JSON

Retrieve metrics for a time range

You can fetch the data for any specified metrics for any time range.

Note that metric data REST URIs restrict the amount of data that can be returned. The maximum is 200 metrics.

URI: /controller/rest/applications/<application-name>/metric-data

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

metric-path

Query

The metric expression to get the metric data. 
Use the pipe character to separate the parent and child name elements in the tree.
The Pipe delimiter must not appear at the beginning or at the end of the metric expression.

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 the "BETWEEN_TIMES" 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 in UNIX epoch time.

If time-range-type is AFTER_TIME or BETWEEN_TIMES

end-time

Query

End time (in milliseconds) until which the metric data is returned in UNIX epoch time.

If time-range-type is BEFORE_TIME or BETWEEN_TIMES 

rollup

Query

Default is true.
If true, value as single data point is returned. If false, all the values within the specified time range are returned.

No

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 - Retrieve the average response time for the past 15 minutes on the ECommerce server.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance|ECommerce Server|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Overall Application Performance|ECommerce Server|Average Response Time (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15&output=JSON

JSON

Example - Retrieve the multiple metrics, for the past 15 minutes, for the ViewCart.sendItems transaction on the ECommerce server.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance|Business Transactions|ECommerce Server|ViewCart.sendItems|*&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business Transaction Performance|Business Transactions|ECommerce Server|ViewCart.sendItems|*&time-range-type=BEFORE_NOW&duration-in-mins=15

JSON

Example - Retrieve the average cpu used by the All Other Traffic business transaction during the past 15 minutes on the ECommerce server.

Enter "APPDYNAMICS_DEFAULT_TX" for the All Other Traffic" transaction for the tier. See All Other Traffic Business Transaction for general information about the All Other Traffic business transaction.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/metric-data?metric-path=Business  Transaction Performance|Business Transactions|ECommerce Server|APPDYNAMICS_DEFAULT_TX|Average CPU Used (ms)&time-range-type=BEFORE_NOW&duration-in-mins=15

XML

Example - Retrieve snapshots for the 15 minutes after Mon, 13 Aug 2012 08:20:41 for the ACME Book Store Application.

URI

Sample object output

/controller/rest/applications/3/request-snapshots?time-range-type=AFTER_TIME&start-time=1344846041495&duration-in-mins=15

XML

/controller/rest/applications/3/request-snapshots?time-range-type=AFTER_TIME&start-time=1344846041495&duration-in-mins=15&output=JSON

JSON

Example - Retrieve snapshots for the 15 minutes before Mon, 13 Aug 2012 08:20:41 for the ACME Book Store Application.

URI

Sample object output

/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15

XML

/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15&output=JSON

JSON

Example - Retrieve snapshots for the time range between Mon, 13 Aug 2012 08:20:41 and Mon, 13 Aug 2012 08:22:21 GMT for the ACME Book Store Application.

URI

Sample object output

/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15

XML

/controller/rest/applications/3/request-snapshots?time-range-type=BEFORE_TIME&end-time=1344846041495&duration-in-mins=15&output=JSON

JSON

Retrieve all health rule violations in a particular business application

URI: /controller/rest/applications/<application-name|application-id>/problems/healthrule-violations

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application 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 the "BETWEEN_TIMES" 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

Retrieve all policy violations in a particular business application

This URI is maintained for compatibility with pre-3.7 versions. Use Retrieve all health rule violations in a particular business application for 3.7 and later.

URI: /controller/rest/applications/<application-name|application-id>/problems/policy-violations

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application 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 the "BETWEEN_TIMES" 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 - Retrieve the list of all policy violations in the ACME Book Store for the past hour.

URI

Sample object output

/controller/rest/applications/ACME Book Store Application/problems/policy-violations?time-range-type=BEFORE_NOW&duration-in-mins=60&output=XML

XML

/controller/rest/applications/ACME Book Store Application/problems/policy-violations?time-range-type=BEFORE_NOW&duration-in-mins=60&output=JSON

JSON

Retrieve event data

You can capture data for the event types listed in the event-types parameter.

URI: /controller/rest/applications/<application-name|application-id>/events

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application 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 the "BETWEEN_TIMES" 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

Specify the duration (in minutes) to return the metric data.

If time-range-type is BEFORE_NOW, BEFORE_TIME, or AFTER_TIME

start-time

Query

Specify the start time (in milliseconds) from which the metric data is returned.

If time-range-type is AFTER_TIME or BETWEEN_TIMES

end-time

Query

Specify the end time (in milliseconds) until which the metric data is returned.

If time-range-type is BEFORE_TIME or BETWEEN_TIMES

event-types

Query

Specify the comma-separated list of event types for which you want to retrieve event information. See the Events Reference for the valid event types.

Yes

severities

Query

Specify the comma-separated list of severities for which you want to retrieve event information.

The severities are:

  • INFO
  • WARN
  • ERROR

Yes

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 - Retrieve the list of events of type "APPLICATION_ERROR" or "DIAGNOSTIC_SESSION" of any severity that occurred in the specified time range.

URI

Sample object output

/controller/rest/applications/ACME%20Book%20Store%20Application/events?time-range-type=BEFORE_NOW&duration-in-mins=30&event-types=%20APPLICATION_ERROR,DIAGNOSTIC_SESSION&severities=INFO,WARN,ERROR&output=XML

XML

/controller/rest/applications/ACME%20Book%20Store%20Application/events?time-range-type=BEFORE_NOW&duration-in-mins=30&event-types=%20APPLICATION_ERROR,DIAGNOSTIC_SESSION&severities=INFO,WARN,ERROR&output=JSON

JSON

Create Events

You can create APPLICATION_DEPLOYMENT and CUSTOM events.

Application Deployment Event Integration

The AppDynamics REST API lets you integrate events of type "APPLICATION_DEPLOYMENT" with other systems.

For example, suppose you want to create an event automatically in your AppDynamics monitored system for every new release. To integrate these systems, use the following REST API to create an event of type "APPLICATION_DEPLOYMENT" in your managed environment.

This is a POST request. You should receive the event ID after successful invocation of the request.

URI: /controller/rest/applications/<application-name|application-id>/events

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either application name or application id.

Yes

summary

Query

Provide the summary for the event.

Yes

comment

Query

Provide the comments (if any) for the event.

Yes

eventtype

Query

APPLICATION_DEPLOYMENT

Yes

Create a Custom Event

The AppDynamics REST API lets you create a custom event.

This is a POST request. You should receive the event ID after successful invocation of the request.

URI: /controller/rest/applications/<application-name|application-id>/events

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either application name or application id.

Yes

summary

Query

Provide a summary describing the event.

No

comment

Query

Provide a comment for the event.

Yes

severity
New in 3.9.5 
QueryProvide a severity level. Allowed values
  • "INFO" 
  • "WARN" 
  • "ERROR"

In the UI, these become "Info", "Warning", and "Critical"

No

eventtype

Query

CUSTOM

Yes

customeventtypeQueryProvide a name for the "type"; for example, the source, like "nagios"No
nodeQueryProvide the affected node nameNo
tierQueryProvide the affected tier nameYes, if node or bt is specified
btQueryProvide the affected business transaction nameNo
propertynamesQueryProvide a property name, ie, the "key"No
propertyvaluesQueryProvide the property value, ie, the "value"No
 

Example 

/controller/rest/applications/<application-name|application-id>/events?eventtype=CUSTOM&customeventtype=nagios&summary=test1&propertynames=key1&propertynames=key2&propertyvalues=value1&propertyvalues=value2

(info) Note the pattern for custom properties: propertynames and propertyvalues get matched up by order position, so to set N property values, you need N occurrences of propertynames and N occurrences of propertyvalues.

Create Custom URLS for Notifications

This is an HTTP POST operation.

Single tenants in a multi-tenant controller instance can specify a custom "vanity" URL for notification purposes, so that instead of a URL like "paid8.appdynamics.com" the host is displayed as something like "mycompany.appdynamics.com" in the notification.

URI: /controller/rest/accounts/<customer-name>/update-controller-url

Input parameters

Parameter Name
Parameter Type
Value
Mandatory
<customer-name>URIProvide the customer account nameYes

Body (Application/JSON)

{
"controllerURL": "http://<my-custom-hostname:port>"
}

Create and Delete Action Suppressions

New in 3.9.4.1

There are three methods available for managing action suppressions.  

(info) By default any response is in JSON, although XML can be requested by using the following header:

Name : Accept
Value : application/vnd.appd.cntrl+xml;v=1

Retrieve All Existing Action Suppressions

This is a GET request.  You should get a list of all existing action suppressions. 

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<account-id>URIThe account idYes

<application-id>

URI

The application id

Yes

Example request to get all action suppressions:

/controller/api/accounts/2/applications/9/actionsuppressions

Example response:

Status : 200 ok
Output Data :
{"actionSuppressions": [{"id": "15","name": "App-ASW","timeRange": {"startTimeMillis": "2014-10-25T04:16:30+0000","endTimeMillis": "2014-10-25T06:16:30+0000"},"affects": {"type": "APP"}},{"id": "16","name": "Node-ASW","timeRange": {"startTimeMillis": "2014-10-25T04:16:57+0000","endTimeMillis": "2014-10-25T05:16:57+0000"},"healthRuleIds": [60,61],"affects": {"type": "NODE","nodeAffectedEntities": {"type": "SPECIFIC","nodeType": "ALL","nodes": [17,18]}}}],"actions": [{"href": "http://ec2-54-80-163-175.compute-1.amazonaws.com:8090/controller/api/accounts/2/applications/9/actionsuppressions/%7Bactionsuppressions.id%7D/%7Bactions.name%7D","method": ["POST","DELETE"],"name": "enabled"}],"links": [{"href": "http://ec2-54-80-163-175.compute-1.amazonaws.com:8090/controller/api/accounts/2/applications/9/actionsuppressions/%7Bactionsuppressions.id%7D","name": "actionsuppressions"}]}

Retrieve a Specific Action Suppression by ID

This is a GET request.  You should get the action suppression of the ID you request. 

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions/<actionsuppression-id>

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<account-id>URIThe account idYes

<application-id>

URI

The application id

Yes

<actionsuppressions-id>URIThe action suppression idYes

Example request:

/controller/api/accounts/2/applications/9/actionsuppressions/15

Example response:

Status : 200 ok
Output Data :
{"id": "15","name": "App-ASW","timeRange": {"startTimeMillis": "2014-10-25T04:16:30+0000","endTimeMillis": "2014-10-25T06:16:30+0000"},"affects": {"type": "APP"}}

Create a New Action Suppression

This is a POST request.  You should only get a 201 - created.

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<account-id>URIThe account idYes

<application-id>

URI

The application id

Yes

namebody keyThe name of the action suppression windowYes
timeRangebody key

The start and end time of the window
Includes:
startTimeMillis, eg 2014-10-25T04:16:57+0000
endTimeMillis, eg  2014-10-25T05:16:57+0000

Yes
healthRuleIdsbody keyThe ids of the affected health rules. If not provided, all rules affectedNo
affectsbody keyType of entity and corresponding ids (see below)Yes

Content of "affects"

ScopeTypeValueExample
ApplicationAPPCovers the entire application"affects": {"type": "APP"}
Business TransactionBTCovers one or more Business Transactions 
  All Business Transactions "affects": {"type": "BT","btAffectedEntities": {"type": "ALL"}}
  Business Transactions from specific tiers"affects": {"type": "BT","btAffectedEntities": {"type": "WITHIN_TIERS","tiers": [11,12]}}  where 11,12 are Tier Ids
  Specific Business Transactions by id "affects": {"type": "BT","btAffectedEntities": {"type": "SPECIFIC","bts": [1,2]}} where 1,2 are BT Ids
  Business Transactions that match criteria

"affects": {"type": "BT","btAffectedEntities": {"type": "CRITERIA","matchesOperator": "CONTAINS","matchesValue": "pojo"}}
where "matchesOperator" can be:

  • CONTAINS
  • EQUALS
  • STARTS
  • ENDS
  • REGEX_VALUE
TierTIERCovers one or more tiers 
  All tiers "affects": {"type": "TIER","tierAffectedEntities": {"type": "ALL"}}
  Specific tiers"affects": {"type": "TIER","tierAffectedEntities": {"type": "SPECIFIC","tiers": [11,12]}} where 11,12 are Tier Ids
NodeNODECovers one or more nodes 
  All nodes"affects": {"type": "NODE","nodeAffectedEntities": {"type": "ALL","nodeType": "ALL"}}
  Nodes belonging to specific tiers"affects": {"type": "NODE","nodeAffectedEntities": {"type": "WITHIN_TIERS","nodeType": "ALL","tiers": [11,12]}} where 11,12 are Tier Ids
  Specific nodes"affects": {"type": "NODE","nodeAffectedEntities": {"type": "SPECIFIC","nodeType": "ALL","nodes": [9,10]}} where 9,10 are Node Ids
  Nodes that match criteria
 
"affects": {"type": "NODE","nodeAffectedEntities": {"type": "NAME_CRITERIA","nodeType": "ALL","nameMatchesOperator": "EQUALS","nameMatchesValue": "Node"}} - String match
 "affects": {"type": "NODE","nodeAffectedEntities": {"type": "PROPERTY_CRITERIA","nodeType": "ALL","metaInfoProperties": [{"name": "ProcessID","value": "12343"}]}} - Meta Info Properties match

where "matchesOperator" can be:

  • CONTAINS
  • EQUALS
  • STARTS
  • ENDS
  • REGEX_VALUE
MachineMACHINECovers one or more machines"affects": {"type": "MACHINE","machineAffectedEntities": {"type": "SPECIFIC","machines": [4,5]}} where 4,5 are Machine Ids

Example request:

 /controller/api/accounts/2/applications/9/actionsuppressions

Header

Name - Content-Type
Value - application/vnd.appd.cntrl+json;v=1

Body

{"name": "App-ASW_2","timeRange": {"startTimeMillis": "2014-10-25T04:16:30+0000","endTimeMillis": "2014-10-25T06:16:30+0000"},"affects": {"type": "APP"}}

or

{"name": "Node-ASW_1","timeRange": {"startTimeMillis": "2014-10-25T04:16:57+0000","endTimeMillis": "2014-10-25T05:16:57+0000"},"healthRuleIds": [60,61],"affects": {"type": "NODE","nodeAffectedEntities": {"type": "SPECIFIC","nodeType": "ALL","nodes": [17,18]}}}

Delete a Specific Action Suppression by ID

This is a DELETE request.  You should only get a 204 - No Content

URI: /controller/api/accounts/<account-id>/applications/<application-id>/actionsuppressions/<actionsuppression-id>

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<account-id>URIThe account idYes

<application-id>

URI

The application id

Yes

<actionsuppression-id>URIThe id of the action suppression to be deletedYes

Retrieve transaction snapshots for a Business Transaction for a time range

URI: /controller/rest/applications/<application-id>/request-snapshots

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-id>

URI

Provide either the application name or application 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 the "BETWEEN_TIMES" 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 data.

If time-range-type is BEFORE_NOW, BEFORE_TIME, or AFTER_TIME

start-time

Query

Start time (in milliseconds) from which the data is returned.

If time-range-type is AFTER_TIME or BETWEEN_TIMES

end-time

Query

End time (in milliseconds) until which the data is returned.

If time-range-type is BEFORE_TIMEor BETWEEN_TIMES

guids

Query

Array of comma-separated guids for the transaction snapshots. If not specified, retrieves all snapshots in the specified time range.

No

archived

Query

True to retrieve archived snapshots. Default is false.

No

deep-dive-policy

Query

Array of comma-separated snapshot policy filters to apply. Valid values are: 

  • SLA_FAILURE
  • TIME_SAMPLING
  • ERROR_SAMPLING
  • OCCURRENCE_SAMPLING 
  • ON_DEMAND
  • HOTSPOT
  • HOTSPOT_LEARN
  • APPLICATION_STARTUP
  • SLOW_DIAGNOSTIC_SESSION
  • ERROR_DIAGNOSTIC_SESSION
  • POLICY_FAILURE_DIAGNOSTIC_SESSION
  • DIAGNOSTIC_SESSION
  • INFLIGHT_SLOW_SESSION

No

application-component-ids

Query

Array of comma-separated tier IDs to filter. Default is all the tiers in the application.

No

application-component-node-ids

Query

Array of comma-separated node ID filters. Default is all the nodes in the application

No

business-transaction-ids

Query

Array of comma-separated business transaction ID filters. Default is all the business transactions in the application.

No

user-experience

Query

Array of comma-separated user experiences filters. Valid values are: 

  • NORMAL
  • SLOW
  • VERY_SLOW
  • STALL
  • ERROR

No

first-in-chain

Query

If true, retrieve only the first request from the chain. Default is false.

No

need-props

Query

If true, the values of the following snapshot properties are included in the output. These values correspond to the values of the data-collector-type parameter.
If false, these values are empty in the REST output.
The default is false. New in 3.7.11.

  • errorDetails
  • errorIDs
  • httpParameters
  • businessData
  • cookies
  • httpHeaders
  • sessionKeys
  • responseHeaders
  • logMessages
  • transactionProperties
  • transactionEvents
  • dotnetProperty

No

 

need-exit-calls

Query

If true, exit calls are included in the result. Default is false.

No

execution-time-in-milis

Query

If set, retrieves only data for requests with execution times greater than this value.

No

session-id

Query

If set, retrieves data only for this session id.

No

user-principal-id

Query

If set, retrieves data only for this user login. 

No

error-ids

Query

Array of comma-separated error codes to filter by. Default is to retrieve all error codes.

No

starting-request-id, ending-request-id

Query

If set, retrieves data only for this range of request IDs.

No

error-occurred

Query

If true, retrieves only error requests. Default is false.

No

diagnostic-snapshot

Query

If true, retrieves only diagnostic snapshots. Default is false.

No

bad-request

Query

If true, retrieves only slow and error requests. Default is false.

No

diagnostic-session-guid

Query

Array of comma-separated diagnostic session guids to filter.

No

data-collector-name

Query

Used with data-collector-value to filter snapshot collection based on the value of a data collector. New in 3.6.1.

No

data-collector-value

Query

Used with data-collector-name to filter snapshot collection based on the value of a data collector. New in 3.6.1.

If data-collector-name is set.

data-collector-type

Query

Used with data-collector-name and data-collector-value to filter snapshot collection based on the value of a data collector. New in 3.6.1. Some of the values contain spaces. All are case-sensitive and where indicated the spaces are required. Valid values are:

  • Error IDs
  • Stack Traces
  • Error Detail
  • Http Parameter
  • Business Data (This type is a method invocation data collector.)
  • Cookie
  • Http Header
  • Session Key
  • Response Header
  • Log Message
  • Transaction Property
  • Transaction Event
  • Dotnet Property
  • isProtoBuf
  • EUM Request GUID

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 - Retrieve list of transaction snapshots for the ACME Book Store.

URI

Sample object output

/controller/rest/applications/AcmeOnlineBookStore/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=2

XML

/controller/rest/applications/AcmeOnlineBookStore/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=2&output=JSON

JSON

Example - Retrieve list of transaction snapshots including the snapshot fields that are associated with an Http Parameter data collector.

URI

Sample object output

controller/rest/applications/2/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=120&data-collector-type=Http%20Parameter&data-collector-name=param1&data-collector-value=%5B100%5D&need-props=true]

XML

controller/rest/applications/2/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=120&data-collector-type=Http%20Parameter&data-collector-name=param1&data-collector-value=%5B100%5D&need-props=true&output=JSON]

JSON

Create and modify AppDynamics users

This is an HTTP POST operation.

The create and modify user URIs are identical except for the user-id parameter, which is not passed for the create operation. The user-id is generated by the create operation.
A response code of 200 indicates success.

URI: /controller/rest/users

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

user-name

Query

user name

Yes

user-id

Query

user id

No for a create; yes for an update

user-display-name

Query

display name

Yes

user-roles

Query

comma-separated list of roles

No

user-password

Query

user password

Yes for create; optional for update

user-email

Query

user email

Yes

Include or exclude a business transaction from monitoring

This is an HTTP POST operation.

To exclude a business transaction from monitoring, set the exclude parameter to true.

To turn on monitoring for a currently excluded business transaction, set the exclude parameter to false.

Send the list of business transactions to be excluded or re-included as xml payload, not as parameters.
A sample business-transaction-list is:

<business-transactions>
    <business-transaction>
        <id>15</id>
    </business-transaction>
    <business-transaction>
        <id>16</id>
    </business-transaction>
</business-transactions>

Make sure the Content-Type header is set to "application/xml".

URI: /controller/rest/applications/<application-name | application-id>/business-transactions

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application id.

Yes

exclude

Post

true|false

Yes

Example - Exclude business transaction 166 from monitoring.

URI

/controller/rest/applications/AcmeOnlineBookStore/business-transactions?exclude=true

This is the way the request appears in the Google Advanced REST Client:

Retrieve all controller global configuration values

These are the values that you set interactively from the Controller Settings screen in the AppDynamics Administration console.

Access requires the "root" password, which was created for the AppDynamics admin user when the controller was installed. See Access the Administration Console.

URI: /configuration

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

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 - Retrieve list of all global configuration values

URI

Sample object output

/controller/rest/configuration

XML

/controller/rest/configuration?output=JSON

JSON

Retrieve a single controller global configuration value

URI: /configuration?name=<controller_setting_name>

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

name

Query

Name of the Controller setting to retrieve

Yes

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 - Retrieve the global metrics buffer size.

URI

Sample object output

/controller/rest/configuration?name=metrics.buffer.size

XML

/controller/rest/configuration?name=metrics.buffer.size&output=JSON

JSON

Configure Global Controller Settings

This is an HTTP POST operation.

URI: /controller/rest/configuration

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

name

Query

name of a controller setting; to see all the names, retrieve all the values as described in Example - Retrieve list of all global configuration values

Yes

value

Query

value to set

Yes

Mark Nodes as Historical

This is an HTTP POST operation.

Pass as parameters a comma-separated list of one or more node ids of the nodes to be marked as historical. You can specify up to a maximum of 25 node ids to be marked.

AppDynamics stops collecting metrics for a node that is marked as historical.

By default AppDynamics marks as historical (soft deletes) a node that has lost contact with the Controller for the number of hours configured in the node.retention.period controller setting. The default is 500 hours.

Information from a historical node can be retrieved until the node has lost contact with the controller for the number of hours configured in the node.permanent.deletion.period, after which time the historical node is permanently deleted. The default is 720 hours.

URI: /controller/rest/mark-nodes-historical?application-component-node-ids=44,45

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

application-component-node-ids

Query

comma-separated list of node ids

Yes

Example - Mark nodes 44 and 45 as historical.

URI

Sample object output

/controller/rest/mark-nodes-historical?application-component-node-ids=44,45

XML

Retrieve all policy violations in a particular business application

URI: /controller/rest/applications/<application-name|application-id>/problems/policy-violations

Input parameters

Parameter Name

Parameter Type

Value

Mandatory

<application-name | application-id>

URI

Provide either the application name or application 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 the "BETWEEN_TIMES" option, you must also specify the "start-time" and "end-time" parameters.

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

incident-status

Query

If OPEN, retrieve only the policy violations that are open. If RESOLVED, retrieve only the policy violations that are resolved.

No

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 - Retrieve the list of all open policy violations in the ACME Book Store for the past 1000 minutes.

URI

Sample object output

/controller/rest/applications/2/problems/policy-violations?time-range-type=BEFORE_NOW&duration-in-mins=1000&incident-status=OPEN

XML

/controller/rest/applications/2/problems/policy-violations?time-range-type=BEFORE_NOW&duration-in-mins=1000&incident-status=OPEN&output=JSON

JSON