Was this helpful?

This topic covers the Apigee Analytics Services API. Apigee Edge records a wide variety of operational and business data that flows across APIs. The metrics derived from this data are useful for operational monitoring and business monitoring. Using Analytics Services, you can, for example, determine which APIs are performing well or poorly, which developers are delivering the highest value traffic, and which apps are causing the most issues for your backend services.

To help access this data easily, Apigee Edge Analytics Services exposes a RESTful API. You can use this API when you need to automate certain Analytics functions, such as retrieving metrics periodically using an automation client or script. You can also use the API to build your own visualizations in the form of custom widgets that you can embed in portals or custom apps.

This topic demonstrates the RESTful Analytics API. To learn how to use Analytics in the API Edge management UI see Analytics Services overview.

Retrieving statistics: dimensions, metrics, and functions

Apigee Edge Analytics Services is based on the concept of 'dimensions'. A dimension is an entity that Apigee Edge automatically monitors and measures. The measurements that Analytics collects are called 'statistics'. In the API, this is abbreviated as /stats.

For this reason the base URL that you invoke to retrieve statistics for dimensions is the following:

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

To create a working request, substitute your organization name for the variable {org_name}. Substitute the environment name ('test' or 'prod') for the variable {env_name}.

For example:

https://api.enterprise.apigee.com/v1/o/apimakers/environments/prod/stats

This is the base URL that you invoke get statistics. To identify the dimension, you need to add the name of the dimension as a URI variable to this base URL.

The following dimensions are supported:

  • /apis
  • /apiproducts
  • /apps
  • /devs
  • /envs

For example, to get statistics for APIs:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apis

To get statistics for developers:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/devs

To get statistics for developer apps:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apps

To get statistics for APIs (or any other dimension) across all environments, a wildcard URI pattern is supported:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/*/stats/apis
In this topic, you will get metrics for the set of built-in dimensions. The next topic, Analyze API message content using custom analytics, shows you how to define and work with custom dimensions.

You will find that if you submit one of these requests, you will get the following error:

{
  "code" : "Missing select parameter",
  "message" : "Missing select parameter",
  "contexts" : [ ]
}

Now you need to add a select statement to the base URL for the chosen dimension. You create the select statement using query parameters.

Query parameters define:

  • Metrics: The attribute of the chosen dimension used to calculate statistics.
  • Functions: The calculation run against the metric defined for the dimension.
  • TimeRange: The time interval over which data should be analyzed.
  • Filters: The attribute used to drill-down into or sort across results.

For complete reference on these parameters, see Build custom reports.

Let's suppose that you want to get statistics across your API proxies that are deployed in the test environment. You want to find out how many request messages were received by all API proxies between 8/24/2013 and 9/25/2013. You want to find out a daily count for messages that were received. To do so, you create a select statement on the /stats/apis resource.

The example below demonstrates who you would construct a request for these statistics. The select statement defines the function sum for the metric message_count on the dimension apis deployed in the test environment. The report provides a snapshot of the request message throughput to all APIs for traffic received between 8/24/2013 and 9/25/2013:

$ curl  https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apis?"select=sum(message_count)&timeRange=8/24/2013%2000:00~9/25/2013%2000:00&timeUnit=day" \
-u myname:mypass

Sample Response:

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1379548800000,
          "value" : "1100.0"
        } ]
      } ],
      "name" : "target-reroute"
    } ],
    "name" : "test"
  } ],
  "metaData" : {
    "errors" : [ ],
    "failedEnvs" : "[]",
    "notices" : [ ],
    "samplingRate" : "100"
  }

This response indicates that 1100 message were received by one API proxy called 'target-reroute' running in the test environment between 8/24/2013 and 9/25/2013, on Thursday, 19 Sep 2013 00:00:00 GMT.

Note that the timestamp, 1379548800000, is in Unix timestamp format. There are many Unix timestamp conversion tools available on the Internet that you can use to decode these timestamps.

To get statistics for other dimensions, specify a different dimension as the URI parameter. For example, you can specify the apps dimensions to retrieve statistics for consumer apps. The following report shows the total throughput (messages received) from any apps for the specified time interval:

$ curl  https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apps?"select=sum(message_count)&timeRange=01/24/2013%2000:00~09/25/2013%2000:00&timeUnit=day" \
-u myname:mypass
{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1365379200000,
          "value" : "1.0"
        }, {
          "timestamp" : 1363046400000,
          "value" : "0"
        }, {
          "timestamp" : 1362441600000,
          "value" : "0"
        }, {
          "timestamp" : 1362355200000,
          "value" : "0"
        }, {
          "timestamp" : 1362096000000,
          "value" : "0"
        }, {
          "timestamp" : 1362009600000,
          "value" : "0"
        }, {
          "timestamp" : 1361404800000,
          "value" : "0"
        }, {
          "timestamp" : 1360022400000,
          "value" : "0"
        } ]
      } ],
      "name" : "weatherapp"
    }, {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1365379200000,
          "value" : "0"
        }, {
          "timestamp" : 1365033600000,
          "value" : "0"
        }, {
          "timestamp" : 1363305600000,
          "value" : "0"
        }, {
          "timestamp" : 1363046400000,
          "value" : "0"
        }, {
          "timestamp" : 1362441600000,
          "value" : "1.0"
        }, {
          "timestamp" : 1362355200000,
          "value" : "1.0"
        }, {
          "timestamp" : 1362096000000,
          "value" : "2.0"
        }, {
          "timestamp" : 1362009600000,
          "value" : "5.0"
        }, {
          "timestamp" : 1361404800000,
          "value" : "0"
        }, {
          "timestamp" : 1360022400000,
          "value" : "0"
        } ]
      } ],
      "name" : "thomas-app"
    } ],
    "name" : "test"
  } ],
  "metaData" : {
    "errors" : [ ],
    "failedEnvs" : "[]",
    "notices" : [ ],
    "samplingRate" : "100"
  }
}
Statistics can be retrieved for apps only when apps can be individually identified by an API key (also called a 'consumer key') or by an OAuth access token. Therefore, only use the /apps dimension for APIs that enforce security policies (API Key or OAuth).

Using metrics

For each dimension, Analytics Services records pre-defined statistics for a set of relevant metrics. Metrics are attributes of dimensions that can be measured, such as total_response_time and request_size. In the examples above, you used the metric message_count, which os one of a set of metrics supported by the /apis dimension.

Metrics are specific to each dimension. For example, for the dimension /stats/devs, Analytics Services records the following metrics message_count, error_count, app_count, user_count. These provide statistics on the number of messages submitted by the developer's app(s), the number of errors generated by the developer's app(s), the number of apps the developer has registered, and the count of app end users associated with the developer's app(s).

Because these metrics are available out-of-the-box, they are referred to as "computed metrics" or "pre-aggregated metrics". Analytics Services provides you with a 'menu' of pre-computed metrics for each dimension. Since the metrics are already computed, you can retrieve large data sets very quickly.

Analytics Services also defines a set of dimensions that have no associated pre-computed metrics--for those dimensions, metrics are calculated on demand, when you make a request to Analytics Services.

Examples of dimensions whose statistics are computed on-demand are:

  • /stats/access_token: Statistics based on OAuth access tokens presented by client apps.
  • /stats/client_id: Statistics based on API keys presented by client apps.
  • /stats/client_ip: Statistics based on the IP addresses of client apps.
  • /stats/target_url: Statistics based on the URL of the target backend service.
  • /stats/request_verb: Statistics based on the HTTP verb of the request message.

In this example, you use a dynamic dimension: target_url. Your goal is to determine how many requests to backend services result in errors. The report that you generate would be useful when communicating with the team responsible for backend services or when performing root-case analysis when an app developer reports issues when calling your APIs, and you suspect that the issue is related to failing backend services.

The is_error metric defines any message that results in an HTTP 4xx or 5xx HTTP status code. The sample request below defines the dimension target_url, the function count, and the metric is_error. The response will detail how many errors were returned by all target URLs called by API proxies deployed in the 'test' environment:

$ curl  https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/target_url?"select=count(is_error)&timeRange=8/08/2013%2000:00~9/15/2013%2000:00&timeUnit=week \
-u myname:mypass
{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "count(is_error)",
        "values" : [ {
          "timestamp" : 1344211200000,
          "value" : "44.0"
        }, {
          "timestamp" : 1344816000000,
          "value" : "1.0"
        } ]
      } ],
      "name" : "https://api.company.com"
    }, {
      "metrics" : [ {
        "name" : "count(is_error)",
        "values" : [ {
          "timestamp" : 1344211200000,
          "value" : "0"
        }, {
          "timestamp" : 1344816000000,
          "value" : "12.0"
        } ]
      } ],
      "name" : "http://weather.yahooapis.com"
    } ],
    "name" : "test"
  } ],
  "metaData" : {
    "samplingRate" : "100"
  }

Based on the statistics, you can see that the target URL https://api.company.com has a total of 45 errors during the period, while http://weather.yahooapis.com returned 12 errors during the period.

Sorting results by relative ranking

Many times when getting statistics, you only want to get results for a subset of the total set of metrics. Usually, you need to get the results for the "top 10", for example, the "top 10 slowest APIs", the "top 10 most active apps". You can do this using the topk query parameter as part of the request.

For example you may be interested to know who your top developers are, measured by throughput, or what your worst performers (i.e., 'top slowest') target APIs are by latency.

The topk (meaning 'top k' entities) enables reporting on the entities associated with the highest value for a given metric. This enables you to filter statistics for a list of entities that exemplify a particular condition. For example, to find which target URL was the most error prone over the last week, the topk parameter is appended to the request, with a value of 1.

In the example below

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/target_url?"select=count(is_error)&timeRange=8/08/2013%2000:00~8/15/2013%2000:00&timeUnit=week&sortby=count(is_error)&topk=1" -u myname:mypass
{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "count(is_error)",
        "values" : [ {
          "timestamp" : 1344816000000,
          "value" : "1.0"
        }, {
          "timestamp" : 1344211200000,
          "value" : "44.0"
        } ]
      } ],
      "name" : "https://api.company.com"
    } ],
    "name" : "test"
  } ],
  "metaData" : {
    "samplingRate" : "100"
  }
}

The result of this request is a set of statistics that show that the buggiest target URL is http://api.company.com.

You can also use the topk parameter to sort for the APIs experiencing the highest throughput. The following example retrieves statistics on the top ranked API, defined by highest throughput in the last week:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apis?"select=message_count&timeRange=7/24/2012%2000:00~8/25/2012%2000:00&timeUnit=week&sortby=message_count&sort=DESC&topk=1" \
-u myname:mypass

Sample Response

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "message_count",
        "values" : [ {
          "timestamp" : 1345420800000,
          "value" : "14.0"
        }, {
          "timestamp" : 1344816000000,
          "value" : "8.0"
        }, {
          "timestamp" : 1344211200000,
          "value" : "111.0"
        }, {
          "timestamp" : 1343606400000,
          "value" : "405.0"
        } ]
      } ],
      "name" : "weatherAPI"
    } ],
    "name" : "test"
  } ],
  "metaData" : {
  }
}

Filtering results

For greater granularity, you can filter results to enable 'drill-down' on a dimension of interest. When using filters, you must use dynamic dimensions as filter properties. Computer metrics (/apis, /devs, /apps, etc.) cannot be used as filters.

For example, let's suppose that you need to retrieve a count of errors from backend services filtered by the HTTP verb of the request. Your goal is find out how many POST and PUT requests are generating errors per backend service. To do so, you use the dimension target_url along with the filter request_verb.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/target_url?"select=count(is_error)&timeRange=8/08/2013%2000:00~8/15/2013%2000:00&timeUnit=week&filter=(request_verb&20in&20'POST','PUT')" \
-u myname:mypass

Paginating results

In production environments, some request to the Analytics Services API return very large data sets. To make it easy to display large data sets in the context of a UI-based application, the API natively supports pagination.

To paginate results, use the offset and limit query parameters.

For example, the following request would be likely to return a large data set, since it retrieves metrics for all errors on all APIs in the product environment for the last week.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/prod/stats/apis?"select=count(is_error)&timeRange=8/08/2013%2000:00~8/15/2013%2000:00&timeUnit=week" \
-u myname:mypass

If your UI-based application can reasonably display 50 results per page, you can set the limit to 50, as follows:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/prod/stats/apis?"select=count(is_error)&timeRange=8/08/2013%2000:00~8/15/2013%2000:00&timeUnit=week&limit=50&offset=0" \
-u myname:mypass

For the second 'page' of results, use the offset query parameter, as follows:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/prod/stats/apis?"select=count(is_error)&timeRange=8/08/2013%2000:00~8/15/2013%2000:00&timeUnit=week&limit=50&offset=1" \
-u myname:mypass

Reference: Analytics calls made by the Apigee API dashboard

The following API calls are made by the dashboards in the Management UI. They are provided here for your reference.

All API Traffic

$ curl  https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/?'select=message_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&sortby=message_count&timeUnit=hour' -u myname:mypass

Top API Movers

$ curl  'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apis?select=message_count,error_count,&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=message_count&timeUnit=hour' -u myname:mypass

Top API Products

$ curl  'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apiproducts?select=message_count,app_count,developer_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=app_count&timeUnit=hour' -u myname:mypass

Top Ranked Apps

$ curl  'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apps?select=message_count,error_count,user_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=user_count&timeUnit=hour' -u myname:mypass

Top Ranked Developers

$ curl  'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/devs?select=message_count,error_count,user_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=user_count&timeUnit=hour' -u myname:mypass

Opt in or out of daily analytics reports

In addition to the analytics available online through Apigee Edge, all organization administrators are automatically subscribed to receive daily analytics summary reports through email. You can unsubscribe (opt out) of receiving daily analytics reports through an opt out link in the actual report that is emailed to you. You can also opt in or opt out of daily summary reports using these API calls:

Opt out of receiving a daily summary report:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{myorg}/stats/preferences/reports/dailysummaryreport?optin=false

Opt in to receiving a daily summary report:

$ curl -u myname:mypass 
https://api.enterprise.apigee.com/v1/o/{myorg}/stats/preferences/reports/dailysummaryreport?optin=true

Retrieve list of users who have opted in or opted out:

$ curl -u myname:mypass 
https://api.enterprise.apigee.com/v1/o/{myorg}stats/preferences/reports/dailysummaryreport/users

 

Comments

The above dailysummaryreport with optin does not work. It should be
https://api.enterprise.apigee.com/v1/organizations/{org}/stats/preferences/reports/dailysummaryreport?optin=true
https://api.enterprise.apigee.com/v1/organizations/{org}/stats/preferences/reports/dailysummaryreport?optin=false

Thanks Srikanth, I updated the page.

Stephen

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.