11436 SSO

Tutorial: Adding Analytics to Apigee-127 APIs

Mar 05, 2015

You’ve built out a set of APIs using Apigee-127. Developers are downloading and using them. They’re building apps, and people are using those apps. At some point, sooner rather than later, you really need to know how things are going with your APIs.

What’s working well? What’s broken? What are your top apps? Who’s using those apps, and where? Who are your best app developers? Which APIs are most popular?

Even if you’ve already started using Apigee-127, you may not be aware that your APIs can plug directly into and take full advantage of Apigee Edge Analytics Services and a full suite of analytics dashboards, like the Traffic Composition dashboard shown below. These tools help give you the insight needed to improve your APIs.

Note: To take advantage of Edge analytics, you need to sign up for an Apigee Edge account. You can sign up for Edge Free, which allows a limited number of API calls per quarter (5 million). For details about Edge and Edge Free pricing options, see the Apigee Edge pricing features page

Screen Shot 2015-03-03 at 9.48.30 PM.png


Build analytics into your Apigee-127 APIs

To tap into a wealth of analytics data, just add and configure an Apigee analytics policy in your Apigee-127 API. Then, analytics data automatically flows from your API through the Apigee Edge Analytics Service. From there, you can access and visualize that data using Analytics dashboards, like the Proxy Performance dashboard shown below. It measures overall traffic patterns, error rates, and performance metrics.




How to add analytics to your API

If you want to try this out, you’ll need to install Apigee-127 and create a project.

Open the Swagger Editor and declare the analytics policy in your project’s swagger.yaml file like this:

    provider: "volos-analytics-apigee"
      key: *apigeeProxyKey
      uri: *apigeeProxyUri
      proxy: hello

The provider, volos-analytics-apigee, is an NPM module that must be installed with your project. Not to worry, though, as it’s installed automatically when you create a new project. You can read about additional configuration options for the policy in the Apigee-127 documentation.

Next, the analytics service requires a little configuration in the x-a127-config section, like this:

 RemoteProxyAx.key: &apigeeProxyKey CONFIGURED
 RemoteProxyAx.uri: &apigeeProxyUri CONFIGURED

Note the RemoteProxyAx suffix on the required key and uri variables. This suffix is the name of a RemoteProxy service that you must create and bind to your project. A remote service is just a service that Apigee-127 can talk to no matter where your API is deployed, and this particular service provides a “conduit” through which Apigee-127 and the Apigee Edge Analytics Services communicate. See “using remote services” to learn more.

It just takes a few steps to set things up. Here’s a quick summary:

  1. Create an Apigee-127 account that includes the apigee provider. This requires that you obtain an Apigee account first (it’s free). The command for creating an Apigee-127 account is: a127 account create <account_name>.
  2. Create a RemoteProxy service with the command: a127 service create <service_name>.

  3. Bind the service to your project with the command: a127 project bind <service name>. The bound remote proxy is automatically deployed to Apigee Edge.

Finally, apply the policy to any API paths from which you want to collect analytics data, like this:

   x-swagger-router-controller: hello_world
     analytics: {}

That’s it. If you’ve already been using Apigee-127, you probably noticed that the analytics policy follows the same configuration pattern as other Apigee-127 policies, like quota, cache, and OAuth.

Check the Apigee Edge dashboards

Whenever the API is called, data is passed to Edge Analytics, where it is processed, and you can then use the Analytics dashboards on Apigee Edge to visualize that data in a variety of ways. Just log in to your Edge account and look under the Analytics menu. For example, the Error Analysis dashboard, shown below, helps you identify problem areas (hopefully before your users do!) so that you can take corrective action.

You might not see your analytics data show up right away. If the time range is an hour or less, the data should appear quickly. If more than an hour, it may take up to 20 minutes.




For more information

The weather-advanced sample in the apigee-127/samples repo on GitHub is a complete working sample that includes analytics. Read more about the analytics policy in the Apigee-127 documentation.

Scaling Microservices