Send Docs Feedback

Use custom aggregations

This topic discusses how to create custom collections or "aggregates" of Edge analytics data.

About custom aggregation

Apigee Edge Analytics Services automatically collects a set of pre-computed metrics. You can query this collected data to discover important information about how your API is performing. For example, the metric message_count keeps track of how many requests an API receives. Because this data is pre-aggregated (not mined on demand), it makes for fast processing time. To read more about computed metrics, see Analytics reference.

If you you have needs that exceed the automatically collected analytics data, you can also create custom aggregations. When you create a new custom aggregation, you can specify the metrics and dimensions that you wish to compute, and Edge collects and stores that data for you in the background, while your API is being used. Just as with the out-of-the-box pre-computed metrics, custom aggregations make access to the data much faster and more efficient than it would be to compute and return it on the fly.

You can use any of the four standard Analytics Services functions with any custom aggregate metrics. The functions are sum, avg, max, and min. For more information on metrics and functions, see Analytics reference.

Creating a new custom aggregation

Edge provides an API for creating custom aggregations of metric data. A custom aggregate can include up to three dimensions and five metrics, which you specify in the request payload. Here's an example of the POST command used to create a custom aggregate:

$ curl -H "Content-type:application/json" -X POST -d \
    "displayName": "my_custom_agg",
    “description” : “This is a sample custom aggregation”,
    "metrics": [
    "dimensions": [
}'  \ \
-u email:password

Notice that the request includes a list of metrics and dimensions. These dimensions and metrics are standard components that are used in Edge Analytics Services. For more information on dimensions and metrics, see "Dynamic Dimensions". For more information on the API for creating a new aggregate, see Create custom aggregate.

Starting and stopping aggregates

You can start and stop a custom aggregate's activity. When you stop an aggregation, the stored data up to that time is not deleted. After stopping an aggregation, you have up to 15 days to reactive it. After 15 days, the stored data is retained; however, you cannot restart the same aggregate. You need to create a new aggregate in that case.

When you activate or deactivate an aggregate, there is typically a time lag between when the command is issued and when it takes effect.

To stop a custom aggregate from collecting data, use this PUT call:

$ curl -H "Content-type:application/json" -X PUT -d \
“status” : “inactive”
}'  \{custom_agg_display_name} \
-u email:password

To start an inactive aggregate, use this PUT call:

$ curl -H "Content-type:application/json" -X PUT -d \
“status” : “active”
}'  \{custom_agg_display_name} \
-u email:password

Selecting dynamic dimensions from custom aggregates

Just as with other Edge statistical metrics, you can query custom aggregate metrics using the select query parameter. To drill into an aggregate data set, you simply need to provide the name of the custom aggregate as another query parameter, t, which specifies the unique name of the aggregate table stored in the database. For example, the following query returns the sum of response times stored in an aggregate with the unique name custom_agg_UUID.

$ curl -H "Content-type:application/json" -X GET -d \"custom_agg_UUID" \
-u email:password

Every aggregate has a unique name expressed by the value of the name attribute that is returned in the response when you create a new aggregate or retrieve an aggregate or list of aggregates through the API.The name is a UUID, a string of numbers and letters, that is assigned when the aggregate is created. In the following example, we simply use "custom_agg_UUID", but an acutal UUID would look something like this: my_custom_agg_250c1e623-e559-46b5-953e-bb532c245d3e.

For detailed information on using the select parameter to query Edge statistical dimensions, see "Dynamic Dimensions".  

Filtering custom aggregate data sets with the query parameter

Just as with other Apigee Edge Analtyics, you can use the filter query parameter with custom aggregates. Filtering lets you "drill down" on a dimension. For example, to filter on API proxies that start with "m":

$ curl -H "Content-type:application/json" -X GET -d \"custom_agg_UUID" \
&filter=(apiproxy LIKE 'm%') -u email:password

For detailed information using the filter parameter, see "Filtering Reports" and "Report Filters".

Help or comments?