This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation
.
On this page:
The Controller Metrics and Events API allows you to retrieve metric data information and information on various types of activities in your monitored environment, including Controller events. Additionally, you can configure how long you retain metrics.
Retrieve Metric Hierarchy
Returns information about the metric tree structure. In the response, if a child element is a container item, its type value is folder. Otherwise the type tag for the child element is leaf.
The API retrieves the first generation of child elements. You can expand only the children of the folder type.
Format
GET /controller/rest/applications/application_name/metrics
Input parameters
Parameter Name | Parameter Type | Value | Mandatory |
|---|---|---|---|
application_name | URI | The name or ID of the business application. Use the call to get the application ID in the Application Model API. | Yes |
output | Query | HTTP Request parameter included as part of the URL to change the output format. | No |
Example
curl --user 'user1@customer1:secret' http://demo.appdynamics.com/controller/rest/applications/ECommerce_E2E/metrics <metric-items><metric-item> <type>folder</type> <name>Backends</name> </metric-item> <metric-item> <type>folder</type> <name>Service Endpoints</name> </metric-item> <metric-item> <type>folder</type> <name>End User Experience</name> </metric-item> <metric-item> <type>folder</type> <name>Errors</name> </metric-item> <metric-item> <type>folder</type> <name>Business Transaction Performance</name> </metric-item> <metric-item> <type>folder</type> <name>Information Points</name> </metric-item> <metric-item> <type>folder</type> <name>Overall Application Performance</name> </metric-item> <metric-item> <type>folder</type> <name>Application Infrastructure Performance</name> </metric-item> <metric-item> <type>folder</type> <name>Mobile</name> </metric-item></metric-items>
Retrieve Metric Data
The metric data method lets you get values generated for metrics. To use the method, you need to specify these parameters to the API:
- The path of the metric to retrieve.
- The time frame for the data.
The easiest way to learn how to construct the metric path and time range-related parameters is by using the Controller UI. When you right-click on the metric in the Metric Browser, a menu option appears for copying the full REST URL for the metric. The copied URL includes the path to this metric and time range selected in the UI.
To test the path, paste the result directly into the URL field of a browser in which an authenticated session to the Controller UI is active.
Certain clients, such as most web browser, can also accept and properly encode the full path value as the metric path parameter. You can see the full path by hovering over the metric in the tree or copy it using the Copy Full Path option in the right-click menu. For reading clarity, certain examples below are shown with the full path value rather than the fully encoded URL value. If you test calls with the full path yourself, be sure to avoid having a pipe character appear at the start or end of the path.
The following sections provide additional details and examples for the metric data method:
- Metric Response Values
- Using Wildcards
- Using Time Ranges
- Retrieving All Other Traffic Business Transaction Metrics
Format
GET /controller/rest/applications/application_name/metric-data
Input Parameters
Parameter Name | Parameter Type | Value | Mandatory |
|---|---|---|---|
| metric-path | Query | The path to the metric in the metric hierarchy. | Yes |
rollup | Query | By default, the values of the returned metrics are rolled up into a single data point (rollup=true). To get separate results for all values within the time range, set the rollup parameter to false in the query. | No |
Additional mandatory parameters for specifying time ranges are described in Using Time Ranges.
Example
Retrieve metric values for a metric at an absolute path:
curl --user "user1@customer1:secret" http://demo.appdynamics.com/controller/rest/applications/ECommerce_E2E/metric-data?metric-path=Overall%20Application%20Performance%7CAverage%20Response%20Time%20%28ms%29\&time-range-type=BEFORE_NOW\&duration-in-mins=15
<metric-datas><metric-data>
<metricId>2339</metricId>
<metricPath>Overall Application Performance|Average Response Time (ms)</metricPath>
<metricName>BTM|Application Summary|Average Response Time (ms)</metricName>
<frequency>ONE_MIN</frequency>
<metricValues>
<metric-value>
<startTimeInMillis>1450562160000</startTimeInMillis>
<value>302</value>
<min>0</min>
<max>15212</max>
<current>15212</current>
<sum>97800</sum>
<count>324</count>
<standardDeviation>0.0</standardDeviation>
<occurrences>0</occurrences>
<useRange>true</useRange>
</metric-value>
</metricValues>
</metric-data>
</metric-datas>
Metric Response Values
Metrics results include the following fields:
| Name | Definition |
|---|---|
| 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. |
| min, max | 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. See Dynamic Baselines for information on how this value is calculated. |
| 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:
|
Using Wildcards
When you copy the REST URL in the Metric Browser, you get the path to a specific metric within a specific application and tier. Alternatively, you can use wildcard characters in one or more the steps in the URL path get metric data for entities, including multiple business transactions, tiers, or nodes.
The following format examples show where to put wildcard characters in various metric paths to achieve particular results. For reading clarity, these format examples use the "full path" for the metric (rather than the REST URL). For a full working example, click the expanding link under each format listing:
Retrieve the app agent availability time for all tiers in the application using a wildcard for the tier name:
/controller/rest/applications/ECommerce_E2E-Fulfillment/metric-data?metric-path=Application Infrastructure Performance|*|Agent|App|Availability&time-range-type=BEFORE_NOW&duration-in-mins=15
Retrieve the CPU % Busy metric for all the nodes in all tiers using a wildcard for the tier and node names:
/controller/rest/applications/ECommerce_E2E-Fulfillment/metric-data?metric-path=Application Infrastructure Performance|*|Individual Nodes|*|Hardware Resources|CPU|%Busy&time-range-type=BEFORE_NOW&duration-in-mins=15
Retrieve the Calls per Minute metric for all the business transactions on the ECommerce tier using a wildcard for the business transaction name:
/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
Retrieve data for multiple metrics for the ViewCart.addToCart transaction on the ECommerce-Services server:
/controller/rest/applications/ECommerce_E2E/metric-data?metric-path=Business Transaction Performance|Business Transactions|ECommerce Server|ViewCart.addToCart|*&time-range-type=BEFORE_NOW&duration-in-mins=15
Disabling Data Rollup
By default, metric data is rolled up for the time frame you request. You can set the rollup parameter to false to get all data points within the time frame. For example:
curl --user 'user1@customer1:secret' 'http://demo.appdynamics.com/controller/rest/applications/ECommerce_E2E/metric-data?rollup=false&metric-path=Overall%20Application%20Performance%7CAverage%20Response%20Time%20%28ms%29&time-range-type=BEFORE_NOW&duration-in-mins=15'
<metric-datas><metric-data>
<metricId>2339</metricId>
<metricPath>Overall Application Performance|Average Response Time (ms)</metricPath>
<metricName>BTM|Application Summary|Average Response Time (ms)</metricName>
<frequency>ONE_MIN</frequency>
<metricValues>
<metric-value>
<startTimeInMillis>1450503540000</startTimeInMillis>
<value>334</value>
<min>0</min>
<max>3340</max>
<current>2</current>
<sum>6678</sum>
<count>20</count>
<standardDeviation>0.0</standardDeviation>
<occurrences>0</occurrences>
<useRange>true</useRange>
</metric-value>
<metric-value>
<startTimeInMillis>1450503600000</startTimeInMillis>
<value>771</value>
<min>1</min>
<max>11235</max>
<current>4113</current>
<sum>15424</sum>
<count>20</count>
<standardDeviation>0.0</standardDeviation>
<occurrences>0</occurrences>
<useRange>true</useRange>
</metric-value>
<metric-value>
<startTimeInMillis>1450503660000</startTimeInMillis>
<value>215</value>
<min>0</min>
<max>4249</max>
<current>3</current>
<sum>4306</sum>
<count>20</count>
<standardDeviation>0.0</standardDeviation>
<occurrences>0</occurrences>
<useRange>true</useRange>
</metric-value>
...
</metricValues>
</metric-data>
</metric-datas>
Calling metric data with rollups disabled can result in a considerable number of results.
It is important to note that a limit exists on the amount of data that can be returned for the metric data method. The maximum result is 200 metrics.
Using Time Ranges
You can fetch metric data for any time range, including for a range between specific points (for example, from 2:00 to 2:15 pm Monday) or for a relative time range (the last 15 minutes).
Time-based input parameters for the metric data API method let you specify a time range in several ways, as described in the following table.
Time Range Input Parameters
Parameter Name | Parameter Type | Value | Mandatory |
|---|---|---|---|
time-range-type | Query | Possible values are:
| 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 |
Examples
Most examples on this page use the past 15 minutes as the request time range. The following format examples show other ways you can define the time range for the request.
Time range of the 15 minutes after December 19, 2015 5:40:00 AM GMT:
?time-range-type=AFTER_TIME&start-time=1450532400000&duration-in-mins=15
Time range of the 15 minutes before December 19, 2015 6:00:00 AM GMT.
?time-range-type=BEFORE_TIME&end-time=1450533600000&duration-in-mins=15
Time range between December 19, 2015 6:00:00 AM GMT and December 19, 2015 6:30:00 AM GMT:
?time-range-type=BETWEEN_TIMES&start-time=1450533600000&end-time=1450504800000
Retrieving All Other Traffic Business Transaction Metrics
The All Other Traffic business transaction is a type of business transaction that aggregates traffic for new transactions once the business transaction registration limits are reached. See Business Transactions for more about the All Other Traffic business transactions.
The All Other Traffic business transaction uses a special identifier in API URI paths, _APPDYNAMICS_DEFAULT_TX_ The following example shows an example of retrieving the average CPU used by the All Other Traffic business transaction:
curl --user user1@customer1:secret http://demo.appdynamics.com:8090/controller/rest/applications/ACME%20Book%20Store%20Application/metric-data?metric-path=Business%20Transaction%20Performance%7CBusiness%20Transactions%7CECommerce%20Server%7C_APPDYNAMICS_DEFAULT_TX_%7CAverage%20CPU%20Used%20%28ms%29\&time-range-type=BEFORE_NOW\&duration-in-mins=15
<metric-datas><metric-data>
<metricId>4000</metricId>
<metricPath>Business Transaction Performance|Business Transactions|ECommerce Server|_APPDYNAMICS_DEFAULT_TX_|Average CPU Used (ms)</metricPath>
<metricName>BTM|BTs|BT:78|Component:12|Average CPU Used (ms)</metricName>
<frequency>ONE_MIN</frequency>
<metricValues>
<metric-value>
<startTimeInMillis>1450570800000</startTimeInMillis>
<value>22</value>
<min>0</min>
<max>50</max>
<current>20</current>
<sum>3140</sum>
<count>146</count>
<standardDeviation>0.0</standardDeviation>
<occurrences>0</occurrences>
<useRange>true</useRange>
</metric-value>
</metricValues>
</metric-data>
</metric-datas>
Retrieve Transaction Snapshots
Snapshots contain details on transactions, by request segment. The time range parameters are the same for snapshots as for retrieving metrics. You can similarly specify a relative time range or a specific range. See Using Time Ranges for more information on using time range parameters.
Format
GET /controller/rest/applications/application_name/request-snapshots
Input parameters
Parameter Name | Parameter Type | Value | Mandatory | |
|---|---|---|---|---|
application_name | URI | Provide either the application name or application id. | Yes | |
time-range-type | Query | Possible values are:
| 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_TIME or 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:
| 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:
| 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, the default, these values are empty in the output.
| 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. | No | |
data-collector-value | Query | Used with data-collector-name to filter snapshot collection based on the value of a data collector. | 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. Some of the values contain spaces. All are case-sensitive and where indicated the spaces are required. Valid values are:
| ||
output | Query | HTTP Request parameter included as part of the URL to change the output format Valid values are "XML" (default) or "JSON". | No | |
| maximum-results | Query | A number, if specified, this number of maximum results will be returned. If not specified, default 600 results can be returned at most. | No |
Examples
Retrieve list of transaction snapshots for the ACME Book Store:
/controller/rest/applications/ECommerce_E2E-Fulfillment/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=5
Retrieve list of transaction snapshots including the snapshot fields that are associated with an HTTP parameter data collector:
/controller/rest/applications/ECommerce_E2E-Fulfillment/request-snapshots?time-range-type=BEFORE_NOW&duration-in-mins=5&data-collector-type=Http Parameter&data-collector-name=param1&data-collector-value=%5B100%5D&need-props=true
Retrieve Controller Audit History
The Controller audit history is a record of the configuration and user activities in the Controller configuration. The ControllerAuditHistory API method returns the audit log for the time range specified. This information is the same as that found in the Controller audit table. And in turn, the content found in the audit.log file is a subset of what's available in the controller audit table. See Controller Logs for more information.
Format
GET /controller/ ControllerAuditHistory?startTime=<start-time>&endTime=<end-time>
Input parameters
Parameter Name | Parameter Type | Value | Mandatory |
|---|---|---|---|
start-time | Query | Start time in the format: "yyyy-MM-dd'T'HH:mm:ss.SSSZ" | Yes |
end-time | Query | End time in the format: "yyyy-MM-dd'T'HH:mm:ss.SSSZ" | Yes |
| time-zone-id | Query | Time zone | No |
To control the size of the output, the range between the start-time and end-time cannot exceed twenty-four hours. For periods longer than 24 hours, use multiple queries with consecutive time parameters.
Example
curl --user user1@customer1:welcome http://demo.appdynamics.com:8090/controller/ControllerAuditHistory\?startTime=2015-12-19T10:50:03.607-0700\&endTime=2015-12-19T17:50:03.607-0700\&timeZoneId=America%2FSan%20Francisco
[{"timeStamp":1450569821811,"auditDateTime":"2015-12-20T00:03:41.811+0000","accountName":"customer1","securityProviderType":"INTERNAL","userName":"user1","action":"LOGIN"},{"timeStamp":1450570234518,"auditDateTime":"2015-12-20T00:10:34.518+0000","accountName":"customer1","securityProviderType":"INTERNAL","userName":"user1","action":"LOGIN"},{"timeStamp":1450570273841,"auditDateTime":"2015-12-20T00:11:13.841+0000","accountName":"customer1","securityProviderType":"INTERNAL","userName":"user1","action":"OBJECT_CREATED","objectType":"AGENT_CONFIGURATION"},
...
{"timeStamp":1450570675345,"auditDateTime":"2015-12-20T00:17:55.345+0000","accountName":"customer1","securityProviderType":"INTERNAL","userName":"user1","action":"OBJECT_DELETED","objectType":"BUSINESS_TRANSACTION"},{"timeStamp":1450570719240,"auditDateTime":"2015-12-20T00:18:39.240+0000","accountName":"customer1","securityProviderType":"INTERNAL","userName":"user1","action":"APP_CONFIGURATION","objectType":"APPLICATION","objectName":"ACME Book Store Application"},{"timeStamp":1450571834835,"auditDateTime":"2015-12-20T00:37:14.835+0000","accountName":"customer1","securityProviderType":"INTERNAL","userName":"user1","action":"LOGIN"}]
Overview
Content Tools
Apps