apim
2016/09/15
15 Sep, 2016

[Article] Generating Alerts Using WSO2 API Manager Analytics

  • Chamila Adhikarinayake
  • Associate Technical Lead - WSO2

WSO2 API Manager can generate alerts and send notifications based on abnormal behavior such as abnormal response time, unseen source IP access, etc. This is done by integrating WSO2 API Manager with WSO2 API Manager Analytics server. This article will discuss how to do this.

Table of contents



Applies to

WSO2 API Manager Version 2.0 and above
WSO2 API Manager Analytics Version 2.0 and above



Introduction

WSO2 API Manager now comes with a separate analytics product, the WSO2 API Manager Analytics server, which can be plugged in for any API-related analytics needs. One of its tasks is to generate alerts for different tasks in WSO2 API Manager. This tutorial describes these alerts and shows how to generate one type of alert using these systems.



Types of alerts

WSO2 API Manager Analytics server supports nine types of alerts and these alerts are generated for three types of users. These alerts include the following.

  1. Abnormal response time

    This alert is generated when there is a sudden increase in the response time of a resource in an API. This could be a result of a slow backend or slow API manager runtime.

  2. Abnormal backend time

    This alert is generated when there is a sudden increase in the backend time. It can be used as an indicator of a slow backend.

  3. Abnormal request counts

    This alert is generated when there is a sudden spike or drop in the request count within a time period (default 1 minute) for an API resource. These alerts could be treated as an indication of possible high traffic, a suspicious act or possible malfunction of the client application among other things.

  4. Abnormal resource access pattern

    This alert is generated when there is a change in the resource access pattern for an application. It is an indication of suspicious activity done by a user over the application.

  5. Unseen source IP access

    This alert is generated if there is a change in the request source IP address of a particular API of an application or if a request is coming from an IP that was used over 30 days ago. These alerts can be considered suspicious activity done by a user over an API.

  6. Abnormal renewal of access tokens

    These alerts are generated when there is a change in the pattern of renewing access tokens for an application. This indicates a stolen token.

  7. Frequent tier limit hitting (tier crossing)

    This alert is generated if a particular application gets throttled out for hitting the subscribed tier limit of that application more than 10 times within a day (default). It is also generated if the user of an application, gets throttled out for hitting the subscribed tier limit of a particular API, more than 10 times within a day (default).

  8. Abnormal API usage

    This alert is triggered if there is a drastic reduction in API usage for a given user. This can be treated as a failure of the application used to access the API.

  9. Availability of APIs

    This alert is triggered if the response time of an API is greater than the response time upper percentile of that particular API, if the request count of an API per minute is greater than the request count per minute lower percentile or if the response status code is between 500 and 600.



Types of users for alerts

  1. System administrators

    An administrator can subscribe to all of the above alert types by logging in to the admin portal (https://localhost:9443/admin/) and going to the Analytics > Manage Alert Types section. They can then define an email address to receive selected alerts.

    Figure 1

    Admin users can also view alerts as notification by selecting the notification button on the top right corner.

  2. Figure 2

  3. API publisher

    The API publisher can subscribe for ‘Abnormal response time’, Abnormal backend time’, ‘Abnormal API usage’ and ‘Availability of APIs’ alerts. This is configured in the Manage Alert Types section in the Publisher jaggery application.

    Figure 3

  4. API subscriber

    The API subscriber can subscribe to ‘Abnormal request counts’, ‘Abnormal resource access pattern’, ‘Unseen source IP access’,’ Abnormal renewal of access tokens’ and ‘Frequent tier limit hitting’ alerts. This can be configured in the Statistics > Manage Alerts Type section in the Store jaggery application.

    Figure 4



    Setting up analytics

    The WSO2 API Manager Analytics pack comes with default port offset 1.

    APIMAnalytics

    • To configure an email account to use for alert sending, open <APIMAnalytics_HOME>/repository/conf/output-event-adapters.xml and modify <adapterConfig type="email"> section with the credentials.

    API Manager

    • To enable analytics open <AM_HOME>/repository/conf/api-manager.xml and set <Enabled>true</Enabled> in the <Analytics> element.

    First start WSO2 API Manager Analytics server and then start WSO2 API Manager.



    Scenario


    Frequent tier limit hitting (tier crossing)

    The following sample demonstrates the frequent tier hitting alert scenario. Once the application is throttled out it will wait for additional throttle out requests for a specific time period and generate alerts for the application creator. Use the following steps to generate the alerts. They are done in WSO2 API Manager.

    1. Log in to the Publisher and deploy the sample API.
    2. Log in to the store and create an application with a limited tier (say 10/min quota) and generate tokens.
    3. Subscribe the API to that application.
    4. To enable email alerts for subscribed user, log in to the Store and go to Statistics -> Manage Alert Types and complete the section. For this scenario, select 'Frequent tier limit hitting' and add an email address to receive emails.
    5. Send requests till it gets throttled out and do extra requests to generate the alert. For example, do 10 requests/min to throttle out and do an additional 10 or more requests to pass the tier crossing limit.

    To view alerts, log in to admin portal application in https://localhost:9443/admin and select Alerts at the top right corner of the page. You can see all the alerts and each type of alert.

    Figure 5

    The subscriber should get an email notification as well.



    How it works

    Figure 6 shows the overall flow of this implementation.

    Figure 6

    These event stream definitions, execution plan, etc. can be viewed by logging into the APIMAnalytics server carbon console. All the execution plans are defined in Home > Manage > Streaming Analytics > Execution Plans and persisted data related to event stream can be viewed at Home > Manage > Interactive Analytics > Data Explorer.

    Email notification sending happens similar to the above implementation. Figure 7 shows an overall flow for that.

    Figure 7

    When an email is registered through WSO2 API Manager, it generates an event and sends it to the alertStakeHolderInfo event stream. The APIMAnalytics server stores that event and APIMAnalytics-EmailNotification execution plan uses that stored data to identify subscribed users.

    A similar kind of execution plan is written for all the alert types. Some of the stream data is persisted. Users can view them using the analytics server carbon console.

    Figure 8



    Configure alerts from WSO2 API Manager Analytics server

    API Manager Analytics server comes with a predefined set of configurations for each alert type. For example, for the frequent tier limit hitting alert type, alerts are generated once the throttled requests exceed 10 requests. These values can be changed by

    1. Logging into API Manager Analytics server management console (https://localhost:9444/carbon/) and selecting Template Manager under the Dashboard section. This will open the Template Manager web application.
    2. Selecting ‘APIMAnalytics’ in the Domains section. This will list down the configurations for all the scenarios.
    3. Selecting Edit to modify the parameters.



    Conclusion

    WSO2 API Manager uses WSO2 API Manager Analytics for all API-related analytics needs. This article explored the various alert types and how three different types of users can make use of them to generate alerts and send notifications based on abnormal behavior.

 

About Author

  • Chamila Adhikarinayake
  • Associate Technical Lead
  • WSO2 Inc.