You are viewing the Apigee Management API reference documentation. For the main product docs, and to search all docs, go to https://docs.apigee.com. For cross-site search, click Search all in the search results.

Get metrics organized by dimensions

Resource Summary

Security

Content Type

application/json

Category

Analytics,

retrieveandfiltermetricsforadimension

GET

Get metrics organized by dimensions

Retrieve metrics, group them by dimensions, and filter the results. If you are using Edge Microgateway with the analytics plugin enabled (default), API calls to Edge Microgateway are included in results.

 

For examples using this API, see Analytics command reference.

 

Data delay interval
After API calls are made to proxies, it may take up to 10 minutes for the data to appear in dashboards, custom reports, and management API calls.

 

You can use the _optimized=js query parameter to optimize the JSON in the response so that it is less verbose, as described in this community article. However, the _optimized query parameter has not been fully tested and its performance cannot be guaranteed.

Metrics

The types of metrics you can retrieve (specifid by the select query parameter) include traffic, message counts, API call latency, response size, and cache hits and counts. The documentation on metrics contains a table that specifies the metric name to use with the select query parameter and the aggregation function (sum, avg, min, max) supported by the metric.

 

For example, to get the average request size for your APIs, set the select query param as:

 

select=avg(request_size)

Dimensions

Dimensions let you view metrics in meaningful groups. For example, instead of looking at total API traffic in your organization, you can see API traffic for each API proxy, for each app, for each developer, and more.

 

For each dimension, you construct a request by adding the desired dimension in the URL after /stats. For example, to group metrics by API proxies, you'd use:

 

/stats/apiproxy

 

You can specify multiple dimenstions to the API, separated by commas. To group metrics by API proxy and target response code combinations, you'd comma-separate dimensions in the URL: 

 

/stats/apiproxy,target_response_code

 

For a description of all supported dimentsions, see Dimenssions. You can also include your own custom dimensions, as described in Analyze API message content using custom analytics.

 

Here's an example that shows how to get the average response time (metric) for all API proxies (dimension) in an environment:
 

/stats/apiproxy?select=avg(total_response_time)

Filters

You can also apply filters to limit the data that's returned. For example, if you're getting message counts grouped by API proxies, you can add a filter that returns only metrics for API proxies that return 4xx or 5xx status codes. Use any available dimensions or metrics to build your filters.

 

For more information on filters and the operators you can use, see filters.


Sample filters
Description Filter query structure
Metrics API proxies named either api1 or api2 filter=(apiproxy in 'api1','api2')
Metrics for all API proxies except api1 and api2 filter=(apiproxy notin 'ap1','api2')
Metrics where there are no errors filter=(is_error eq 0)
Metrics where there is an error or the API proxy name is api1 or api2 filter=(is_error eq 1) or (apiproxy in 'api1','api2')
Metrics where the response status code is 4xx or 5xx filter=(response_status_code ge 400 and response_status_code le 599)

 

Resource URL

https://api.enterprise.apigee.com/v1 /organizations/{org_name}/environments/{env_name}/stats/{dimension_name}

Query Parameters

Name Values Description
select
(required)

Designates one or more metrics to be aggregated for the report. For descriptions, see the Metrics. The documentation on metrics contains a table that specifies the metric name to use with the select query parameter and the function (sum, avg, min, max) supported by the metric.

Following are examples of supported metrics and aggregate functions:

sum(ax_cache_executed)
avg|min|max(ax_cache_l1_count)
sum(cache_hit)
sum(is_error)
sum(message_count)
sum(policy_error)
avg|min|max(request_processing_latency)
sum|avg|min|max(request_size)
avg|min|max(response_processing_latency)
sum|avg|min|max(response_size)
sum(target_error)
sum|avg|min|max(target_response_time)
sum|avg|min|max(total_response_time)
tps (Currently must use with another metric)

Separate more than one metric with a comma. For example:

sum(message_count),tps

timeRange
(required)

The start and end time for the desired interval. The date format is MM/DD/YYYY HH:MM. For example, 04/15/2017 00:00~05/15/2017 23:59

If you have high API traffic, report generation will be faster if you use smaller time ranges, such as 2 or 3 hours.

It takes at least 10 minutes after an API call for Edge analytics to register it.

Do not use 24:00 as the time because it wraps around to 00:00. Use 23:59 instead.

By default, the timeRange parameter specifies a UTC start and end time. To change the time zone from UTC to a different time zone, use the tzo parameter to set the offset, in minutes, from UTC to the desired time zone.

If you make a request through the API reference on this page, it automatically URL encodes the space character before HH:MM. However, if you are entering the time range in a cURL command from the command line, manually insert "%20" for the space character, in the form: MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM.

In a curl command, you can URL encode special characters in the date format, including: "%2F" for a forward slash ("/"), "%20" for a space, and "%3A" for a colon (":").

Note: Data older than six months from the current date is not accessible by default. If you want to access data older than six months, contact Apigee Support.


Note:If you set timeUnit to second, the timeRange cannot be longer than one hour.

timeUnit

A value of second, minute, hour, day, week, month, quarter, year, decade, century, millennium.

Note: second is not supported for Edge for the Private Cloud.

sortby

When two or more metrics are specified, use sortby to sort results by a specific metric. For example: when you include the metricssum(message_count),sum(is_error), use a sortby of sum(message_count) to sort the results by message count.

sort

Supported sort scopes are DESC or ASC.

topk

Take 'top k' results from results, for example, to return the top 5 results 'topk=5'.

filter

Enables drill-down on specific dimension values. Don't add the word "filter", and close value in parenthesis "()". For example: (response_status_code gt 500 and response_status_code lt 599)

SmartDocs automatically URL encodes the spaces.

limit

Set the limit for the number of entries returned by the API. The default limit is 1000 entries. If you expect your query to return more than 1000 entries, then set the limit appropriately. Otherwise, your query returns a maximum of 1000 entries.

offset

Use offset with limit to enable pagination of results. For example, to display results 11-20, set limit to '10' and offset to '10'.

Note: Edge ignores the offset parameter on queries that process raw fact data. For these "fact" queries, Edge uses Big Data (Apache Spark), which processes data using a parallel map-reduce technique. You can tell if the Spark query engine was used to process a query when you see something like the following in the response:

"notices" : [ "query served by:d62441a4-0951-4b90-abd3-318e86c23cf6", "Spark engine used" ]

tsAscending

Lists timestamps in ascending order if set to true. Recommend setting this value to true if you are using sortby with sort=DESC.

tzo

By default, the timeRange parameter specifies a UTC start and end time. To change the time zone from UTC to a different time zone, use the tzo parameter to set the offset, in minutes, from UTC to the desired time zone.

For example, the East coast of the United States is in the EST time zone. To change the time zone to EST, set tzo to -240. For California, in the PST timezone, set the offset to -480 minutes. For Bangalore, in the IST timezone, set the offset to 330 minutes.

Request Body

org_name Mention the organization name true

env_name Mention the environment name, such as test or prod true

dimension_name Mention the dimension name true

org_name Mention the organization name true

env_name Mention the environment name, such as test or prod true

dimension_name Mention the dimension name true

org_name Mention the organization name true

env_name Mention the environment name, such as test or prod true

dimension_name Mention the dimension name true

org_name Mention the organization name true

dimension_name Mention the dimension name true

org_name Mention the organization name true

dimension_name Mention the dimension name true

HTTP Basic

OAuth 2.0

API Key

Reset

Make a request and see the response.

Make a request and see the response.

Make a request and see the response.

Working...

Help or comments?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click the "Send Feedback" button.
    (Incorrect? Unclear? Broken link? Typo?)