Metrics

Summary

The Metrics REST API provides access to periodic analytics of the Portal's application usage.

With the Metrics API, it is possible to track application invocation, errors, and response times. There are two reports: summary, which provides an aggregated report over a configurable time, and timeline which provides a timeline report for a single metric over a configurable time.

Resources

Resource	Since Version	Description
GET /api/portal/v1.3/metrics/fields		Gets a list of metric field names available for summary and timeline queries.
GET /api/portal/v1.3/metrics/reports/{type}/summary/{level}		Gets a summary report for application usage
GET /api/portal/v1.3/metrics/reports/{type}/timeline/{level}/{metricType}		Gets a timeline report for application usage

GET /api/portal/v1.3/metrics/fields

Summary

Gets a list of metric field names available for summary and timeline queries.

Description

Retrieves a set of metric fields that may be used when querying or interpreting the summary and timeline reports. The metricType is the metric name. The aggreggateName is the metric name for the aggregated metricType.

Parameters

none

Status Codes

HTTP Status Code	Reason
200	OK
404	Monitoring is disabled
500	Internal Server Error

Returns Array

[ MetricField ]

Example

GET https://localhost:8075/api/portal/v1.3/metrics/fields

Response
HTTP 1.1 200 OK

[ {
  "metricType" : "exceptions",
  "aggregateName" : "totalExceptions"
}, {
  "metricType" : "failures",
  "aggregateName" : "totalFailures"
}, {
  "metricType" : "numMessages",
  "aggregateName" : "totalNumMessages"
}, {
  "metricType" : "successes",
  "aggregateName" : "totalSuccesses"
}, {
  "metricType" : "processingTime",
  "aggregateName" : "totalProcessingTime"
}, {
  "metricType" : "processingTimeMin",
  "aggregateName" : "minimumProcessingTimeMin"
}, {
  "metricType" : "processingTimeMax",
  "aggregateName" : "maximumProcessingTimeMax"
}, {
  "metricType" : "processingTimeAvg",
  "aggregateName" : "maximumProcessingTimeAvg"
} ]

GET /api/portal/v1.3/metrics/reports/{type}/summary/{level}

Summary

Gets a summary report for application usage

Description

The summary report groups applications and services and provides metrics usage information over a specified time period, between from and to, where from and to are date times in a URL encoded ISO-8601 combined date and time format (e.g. 2013-03-13T00%3A00%3A00Z).

The report may be filtered by specifying one or more client, where client is a valid Application ID. If client is specified, only those clients will be summarized in the report. The report may also be filtered by specifying one or more service, where service is a valid API name. If service is specified, only those clients using the service will be summarized in the report. The report may also be filtered by method where method is a valid API method name associated with a specific service. The report may also be filtered by a specific organization where organization is a valid organization name. If organization and client is specified, only those clients associated with the specified organization will be summarized in the report.

A combination of organization,__client__ ,__service__ and method is also permitted. In this case, the report will be filtered by the specifed client application associated with an organization using the specified API service and API method.

Depending on the report type (either 'api' or 'app') and the report sub type, this method returns an array where each item in the array is a set of attribute values that may include CLIENTNAME (the Application ID), SERVICENAME (the API service name), METHODNAME (the Method Name) or ORGANIZATIONNAME (the Organization Name) as well as keys and values for a number of aggregated metrics (see fields).

If the report type is 'api' and the reportsubtype is 'original', the report consists of 2 levels. The 1st level (zero based level 0) report returns a breakdown per API service. The 2nd level (zero based level 1) returns a breakdown per method (for a specified API service).
If the report type is 'api' and the reportsubtype is 'trafficAll', the report consists of 1 level and returns a breakdown per API service and method.
If the report type is 'api' and the reportsubtype is 'trafficSubset', the report consists of 1 level and returns a breakdown per API service only.

If the report type is 'app' and the reportsubtype is 'original', the report consists of 2 levels. The 1st level (zero based level 0) report returns a breakdown per organization. The 2nd level (zero based level 1) returns a breakdown per client (for a specified organization).
If the report type is 'app' and the reportsubtype is 'trafficAll', the report consists of 1 level and returns a breakdown per organization and client.
If the report type is 'app' and the reportsubtype is 'trafficSubset', the report consists of 1 level and returns a breakdown per organization only.

Parameters

Parameter	Description	Data Type	Location	Required
`type`	The report type, either 'app' or 'api'	String	path	Required
`level`	The report level (0 or 1 for drill-through)	Integer	path	Required
`from`	The starting date/time for the report.	String	query	Required
`to`	The end date/time for the report.	String	query	Required
`client`	Filter a specific client ID (multiple permitted).	String	query
`service`	Filter a specific service name (multiple permitted).	String	query
`method`	Filter a specific method.	String	query
`organization`	Filter a specific organziation.	String	query
`reportsubtype`	Define the report subtype. Allowed values are : 'original', 'trafficAll' or 'trafficSubset'. Defaults to 'original' if absent	String	query

Status Codes

HTTP Status Code	Reason
200	OK
404	Monitoring is disabled
400	Bad Request
500	Internal Server Error

Return Value

[ {"attr1": value, "attr2": value, … }, {"attr1": value, "attr2": value, … } ]

Example

GET https://localhost:8075/api/portal/v1.3/metrics/reports/{type}/summary/{level}

Response
HTTP 1.1 200 OK

[ {
  "SERVICENAME" : "",
  "CLIENTNAME" : "2a1359e7-6f29-4922-84b3-f8631fdb3d63",
  "totalNumMessages" : 0,
  "maximumProcessingTimeAvg" : 0,
  "totalExceptions" : 0,
  "totalFailures" : 0,
  "totalSuccesses" : 0
} ]

GET /api/portal/v1.3/metrics/reports/{type}/timeline/{level}/{metricType}

Summary

Gets a timeline report for application usage

Description

Produces a timeline report for a metricType over a specified time range. The from and two parameters should be a URL encoded ISO-8601 combined date and time format (e.g. 2013-03-13T00%3A00%3A00Z). The metricType name is one of the types returned from fields.

Parameters

Parameter	Description	Data Type	Location	Required
`type`	The report type, either 'app' or 'api'	string	path	Required
`level`	The report level (0 or 1 for drill-through)	Integer	path	Required
`from`	The starting date/time for the report.	String	query	Required
`to`	The end date/time for the report.	String	query	Required
`client`	Filter a specific client ID (multiple permitted).	String	query
`service`	Filter a specific service name (multiple permitted).	String	query
`method`	Filter a specific method.	String	query
`organization`	Filter a specific organziation.	String	query
`metricType`	The metric type to query.	String	path	Required
`reportsubtype`	Define the report subtype. Allowed values are : 'original', 'trafficAll' or 'trafficSubset'. Defaults to 'original' if absent	String	query

Status Codes

HTTP Status Code	Reason
200	OK
404	Monitoring is disabled
400	Bad Request
500	Internal Server Error

Returns Class

MetricTimeline

Example

GET https://localhost:8075/api/portal/v1.3/metrics/reports/{type}/timeline/{level}/{metricType}

Response
HTTP 1.1 200 OK

{
  "name" : "numMessages",
  "series" : [ {
    "name" : "numMessages",
    "pointInterval" : 300000,
    "pointStart" : 1363737600000,
    "data" : [ 0.0, 0.0, 1.0, 0.0, 2.0, 0.0, 3.0, 0.0, 4.0 ]
  } ]
}