Quickstart: API Analytics

Knowing what’s happening on your API is a crucial step to being able to manage traffic, provision for peaks and identifying your top users so you can help them to even greater success. This quickstart guide shows you how to get Analytics connected and tuned.

Other Sections

Follow all our Quickstart guides to get up and running in no time:

For Architecture background and a general overview, head to the How it Works section.

Goal

By the end of this Quickstart you’ll have tuned your API Analytics to track the items you need, see top applications and time trends

Prerequisites

You’ll need to have done the basics of connecting your API to 3scale to proceed with this quickstart.

The guide assumes that you’re doing the integration using one of the existing 3scale code plugins, but you can follow a similar flow with other integration methods including Varnish Cache or one of the supported CDN. See the “Deployment”/ section for information on this modes.

Step by Step Guide

Step 1 Determine the metrics and methods you want to track

3scale acts as an infinitely scalable data repository for your API stats and you can track pretty much any metric you wish for your API

Example Metrics include:

  • Hits/Transactions: these are calls to the API. Hits are included by default as metrics on all APIs. Hits can be overall calls to the API or broken out into individual methods on the API.
  • Data Transfer: quantity of MB/GB of data uploaded and downloaded via the API.
  • CPU Hours: compute time (or some other internal resource) associated with calls to the API.
  • Results Returned: count of the number of records or data objects being returned.
  • Disk Storage: Total disk storage in use by an account.

and many more that might be relevant to your API. 3scale can track an arbitrary number of metrics and methods as long it is a countable quantity which can be incremented over time.

Step 2 Create Your Metrics and Methods

Having chosen your metrics they need to be registered in the 3scale Administration console. Navigate to the the API Area, select Application Plans on the API you wish to manage.

Navigate to the Application plans area on the API you wish to manage. Once here, select any of the application plans available (or create a new one if none have been created), click on edit on your chosen plan.

Navigate to the Application plans area on the API you wish to manage. Once in the edit view is open you can add metric and method definitions.

Note: Metrics and method definitions added will be applied to the whole service, not just the specific plan you are editing. However rate limits or pricing rules created against a metric on a given plan are for that plan only.

Add Metrics and Methods to the service and provide them with a Human readable name and a machine name. The machine name is used later in your plugin configuration.

Step 3 Set Up Reporting

Once the 3scale system has been configured with the names of the metrics you wish to track, it’s time to tweak your plugin setup to report the right metrics. The precise manner of doing this will depend on the plugin or integration method in use. However, in general you need to follow the following steps:

  1. By default the plugins will report hits (transactions on the API) only.
  2. Taking the list of metric and method system names, the application should pass the appropriate metric/method names to the plugin as determined by the incoming API call. The metric/method value and the increment required is an argument of authorize and/or report methods the plugin exposes.

If using the API Integration method, the API information can be found in the API Reference.

Note that when reporting traffic to specific methods on the API use the method system name in the metric argument. This automatically increments the counter both for the method reported and the hits metric.

Step 4 Check Traffic is being correctly reported

Now that the connection between the API and 3scale has been established, you can begin to send traffic to the API and watch it register on the API Analytics screens. To do this:

  • Head to the Accounts area of the API Dashboard and select one of the accounts with test keys in it (see the Hello World API Quickstart for how to generate the first set of credentials.
  • Select one of the Applications on the account and retrieve the API Keys.


API Keys for a sample application on you dashboard.

  • Use these keys to make API calls to your API in the normal way (e.g. from the command line using CURL or from the browser for GET queries). The precise calls to make will depend on the structure of the methods on your API.

Traffic from these calls should now appear on your analytics screens.

Troubleshooting

If traffic is not showing up on the analytics screens then check the following:

  • Are Authorize / Report calls responding correctly?: The plugins all call the 3scale traffic management API and have predetermined responses. Authorize calls for known keys should return Code 200 responses, Report calls should respond with Code 202.
  • Are there errors in the Integration Error Console?: Errors detected by the 3scale system on your API are available in the integration error log which can be found by clicking on Monitoring" and the *Errors.


The Integration Error Log flags parsing errors in traffic reports seen on our API.

  • Are the correct metric and method names being used?: The most common reason for failure is that the method and metric names passed in traffic reports do not correspond to those registered in the API Management Console. Check you are using the “system names” for each metric/method.

Controlling Who sees Stats

By default all statistics are visible both to you the API Administrator as well as the developer accounts who created the applications in questions (each developer can only see their own application stats – not those of others). However, you may wish to hide certain metrics from the Developer views, find out how to do this in the Developer Stats Howto.

Asynchronous and Batch Reporting Traffic

As well as reporting traffic on a call by call basis as API Traffic comes in, there are also two other modes of traffic reporting:

  1. Asynchronous traffic reports: plugins or varnish can be configured to make traffic report calls after the API call itself has returned, thus not blocking the API call return and causing latency. This is achieved with the same reporting call as normal, but by spawning a thread to make the report post return. See the Howto on Asynchronous Traffic Reports.
  2. Batch Reports: You can also report in batches rather than call by call by bundeling groups of calls together and sending them on a minute by minute basis or by some other criteria. See the API documentation on Traffic Reporting for more information.

Accessing Analytics Data by API and Email Reports

As well as seeing the results on the results on the API Dashboard you can also access the data in a couple of other ways:

  • Daily and Weekly Traffic Reports: these summarize your traffic, tell you about new subscribers to the API and top applications. Find out more with the Email Reports Howto.
  • By CSV Export: On each stats view there is a CSV Export Link at the bottom of the view to extract your data in Excel compatible CSV.
  • By API: all Analytics data is available via the Analytics API, you can use this to pull data into your internal reporting dashboards or into Developer Portal views.