How to Publish Custom Attributes from WSO2 API Manager to WSO2 Analytics

Published in

API Integration Essentials

4 min readDec 11, 2018

Say you need to publish a set of custom attributes to the WSO2 API Manager Analytics from the WSO2 API Manager Gateway side. This can be achieved via a custom Handler and a custom Data Publisher.

I am going to provide you a step by step guide to implement a custom Handler and a custom Data Publisher [1] to do this.

Here I will be using WSO2 API Manager 2.1.0 version with the WSO2 APIM-Analytics 2.1.0 (Powered by WSO2 DAS 3.1.0) version.

API Manager (Gateway Node in a Distributed Setup) Side

Implement a CustomRequestPublisherDTO.java [2] class extending from the PublisherDTO, specifying the custom attributes you want. Here I have only given the “resProg” property as a reference.
Implement the APIMgtCustomHandler class extending from the AbstractHandler as in [3]. Here in [4] you have to create the particular CustomRequestPublisherDTO object and then set the values for the custom attributes as done in [5].
The set of attributes defined here in [6] are the default set of attributes coming from the PublisherDTO class.
Implement a APIMgtCustomUsageDataBridgeDataPublisher.java [7] class extending from the APIMgtUsageDataBridgeDataPublisherand as in [8], give your custom stream ID. Here I have given “org.wso2.apimgt.custom.statistics:1.0.0” as my stream ID.
In the handler, you have to give your custom data publisher class as I have given in [9].
Add CustomDataBridgeRequestPublisherDTO [10] class with the default and custom attributes you have used. This should be extracted from the CustomRequestPublisherDTO class you implemented above. Here while creating the payload, make sure to give the list of attributes as same as to the order given in the custom stream.

Building the Handler and the Publisher project

You can use the same set of dependencies I have used in the pom.xml [11] file.
Clone this repository and build it as a maven project using “mvn clean install” command.
Inside target directory, you can find the built jar file.

Deploying the custom Handler and the Publisher

Add the built jar (wso2-custom-data-publisher-1.0-SNAPSHOT.jar) into <APIM_HOME>/repository/components/lib folder.
Add the custom handler into your APIs as below. Go to the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api directory and open the xml file corresponding to your API. Then add “<handler class=”org.wso2.handlers.analytics.APIMgtCustomHandler”/>” as below under the handlers section.

<handlers>
      <handler class="org.wso2.carbon.apimgt.gateway.handlers.common.APIMgtLatencyStatsHandler"/>
      <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler">
         <property name="apiImplementationType" value="ENDPOINT"/>
      </handler>
      <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"/>
      <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.ThrottleHandler"/>
      <handler class="org.wso2.carbon.apimgt.gateway.handlers.analytics.APIMgtUsageHandler"/>
      <handler class="org.wso2.handlers.analytics.APIMgtCustomHandler"/>
      <handler class="org.wso2.carbon.apimgt.gateway.handlers.analytics.APIMgtGoogleAnalyticsTrackingHandler">
         <property name="configKey" value="gov:/apimgt/statistics/ga-config.xml"/>
      </handler>
      <handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>
</handlers>

Now you have deployed the handler and the publisher in the API Manager side. In order to receive the events at the Analytics side, you need to do the following.

Analytics Side

Create an Event Stream matching to your incoming event. In order to create an Event Stream, go to the Management Console of the Analytics server (https://172.17.0.1:9444/carbon) and go to Streams under Manage tab in the left side corner. Then click on “Add Event Stream” from the top. Give the same name you have given above in the Gateway side when implementing the APIMgtCustomUsageDataBridgeDataPublisher.
In my case the stream name is “org.wso2.apimgt.custom.statistics” and the version is “1.0.0”. Then you need to add the same set of attributes as shown below.

Set of Attributes defined in an Event Stream

Then in order to Store events to the database, add event store by clicking “Next(Persist Event)” and ticking “Persist Event Stream” and selecting all the attributes listed under Payload Data Attributes. Click on Save Event Stream at the end.
Finally you can add an Event Receiver to receive events as below. You can give any name to the event receiver, but make sure to select the respective event stream you have created in the previous step.
To add an Event Receiver, click on Receivers from the left side corner under Manage. Click “Add Event Receiver” and add as below.

Now when you invoke an API, the data will get published and you can see the published custom attributes at the Data Explorer. You can see them under a table named “ORG_WSO2_APIMGT_CUSTOM_STATISTICS”.

You can use this published data when displaying them via a custom Dashboard.

Enjoy!

References