

Publishing Custom Analytics Events Data¶

Introduction¶

Instead of publishing already available analytics events data, it is also possible to publish custom analytics data with the existing event schema. This guide will explain the steps required to do it.

Important

Note that, support for publishing custom analytics events data has been introduced to WSO2 API Manager 4.1.0 via an U2 update (Update level 21).
You can check if this feature is available in your current pack by viewing the trace logs without adding the jar containing the implemented class as here.
If the feature is available in the pack you will be able to see a property object named property which includes apiContext and userName as default values.

"properties":{
    "apiContext":"/api/1.0.0",
    "userName":"[email protected]"
},

This section will cover the steps required to create a sample and configure the created sample with WSO2 API-M.

Creating the Sample¶

You have to create a new Java/Maven project.

There is an already created sample and if you wish to use that sample instead of developing the sample from scratch, then you can ignore the steps of creating the sample and start from here.

This section will cover how to configure the pom.xml, class implementations and building the created sample.

Configuring pom.xml¶

Add wso2-nexus repository to pom.xml.

<repository>
    <id>wso2-nexus</id>
    <name>WSO2 internal Repository</name>
    <url>https://maven.wso2.org/nexus/content/groups/wso2-public/</url>
    <releases>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
        <checksumPolicy>ignore</checksumPolicy>
    </releases>
</repository>

Add dependencies,

<dependency>
    <groupId>org.wso2.carbon.apimgt</groupId>
    <artifactId>org.wso2.carbon.apimgt.gateway</artifactId>
    <version>${carbon.apimgt.version}</version>
</dependency>
<dependency>
    <groupId>org.wso2.carbon.apimgt</groupId>
    <artifactId>org.wso2.carbon.apimgt.common.analytics</artifactId>
    <version>${carbon.apimgt.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.synapse</groupId>
       <artifactId>synapse-extensions</artifactId>
       <version>${synapse.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.synapse</groupId>
    <artifactId>synapse-core</artifactId>
    <version>${synapse.version}</version>
    <exclusions>
        <exclusion>
            <groupId>org.apache.axis2</groupId>
            <artifactId>axis2-codegen</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.wso2.orbit.com.github.fge</groupId>
            <artifactId>json-schema-validator-all</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Info

The versions for ${carbon.apimgt.version}, and ${synapse.version} can be found in the jar versions available in the current API Manager 4.1.0 package.

Since this feature support available in the latest update levels, you have to follow the below steps to add the required artifacts to the local m2 repository and point it as a repository in pom file.

Find the org.wso2.carbon.apimgt.gateway and org.wso2.carbon.apimgt.common.analytics jars inside the <APIM_HOME>/repository/components/plugins directory in latest U2 updated APIM pack.

Add the above jars to the local m2 manually.

mvn install:install-file -Dfile=<PATH_TO_FILE>/org.wso2.carbon.apimgt.gateway_<COMPENENT_VERSION>.jar -DgroupId=org.wso2.carbon.apimgt -DartifactId=org.wso2.carbon.apimgt.gateway -Dversion=<COMPENENT_VERSION> -Dpackaging=jar
mvn install:install-file -Dfile=<PATH_TO_FILE>/org.wso2.carbon.apimgt.common.analytics_<COMPENENT_VERSION>.jar -DgroupId=org.wso2.carbon.apimgt -DartifactId=org.wso2.carbon.apimgt.common.analytics -Dversion=<COMPENENT_VERSION> -Dpackaging=jar

Point local m2 repository in project pom

<repository>
    <id> local-maven-repo </id>
    <url> file://home/user/.m2/repository </url>
</repository>

Follow the same URL pattern when providing the repo url

Implementing Required Class¶

AnalyticsCustomDataProvider Implementation Class¶

Custom analytics data can be added to the existing event schema with the use of a class of type AnalyticsCustomDataProvider. Therefore, it is required to implement a class from the AnalyticsCustomDataProvider interface. By overriding the getCustomProperties method it is possible to push custom analytics data.

In order to achieve this behavior, create a class implementing the AnalyticsCustomDataProvider Interface of org.wso2.carbon.apimgt.common.analytics.collectors.

Implementation of this class should look something similar to this.

Build the Project¶

Build the project using,

mvn clean install

Configuring the Sample¶

This section will cover the steps required to configure WSO2 API-M Gateway for the sample created above. The steps covered are adding the .jar file, configuring the deployment.toml file, and enabling the logs.

Add the jar file created in the target directory after building the project.

Place the created .jar file inside the wso2am-4.1.0/repository/components/lib directory.
Configure the deployment.toml file.

Edit the apim.analytics configurations in the deployment.toml file located inside wso2am-4.1.0/repository/conf with the following configuration.
```
[apim.analytics]
enable = true
properties."publisher.custom.data.provider.class" = "<FullyQualifiedClassNameOfAnalyticsCustomDataProviderImplClass>"
type = "elk"
```
This configuration will be used when engaging the custom data provider class.

Important

Type should be given as elk as this property value is filtered out in cloud implementation.

Enable Logs

To enable trace logs for the component: org.wso2.am.analytics.publisher, edit the log4j2.properties file located inside wso2am-4.1.0/repository/conf directory.

Add new publisher to the loggers list:

loggers = org-wso2-analytics-publisher, ...(list of other available loggers)

Add the following configurations after the loggers:

logger.org-wso2-analytics-publisher.name = org.wso2.am.analytics.publisher
logger.org-wso2-analytics-publisher.level = TRACE
logger.org-wso2-analytics-publisher.appenderRef.CARBON_TRACE_LOGFILE.ref = CARBON_TRACE_LOGFILE

Now you can trigger an event and check the <WSO2AM-4.1.0-HOME>/repository/logs/wso2carbon-trace-messages.log to find the event object passed out from API Manager.

TRACE {org.wso2.am.analytics.publisher.client.EventHubClient} - [{ Cloud-Analytics-Queue-Worker-pool-2-thread-1 }] - 
 Adding event: 
 {
    "apiName":"API1",
    "proxyResponseCode":200,
    "destination":"https://run.mocky.io/v3/d14fad1d-d57b-41bc-8be3-146b6aaddfaf",
    "apiCreatorTenantDomain":"carbon.super",
    "platform":"Linux",
    "apiMethod":"GET",
    "apiVersion":"2.0.0",
    "gatewayType":"SYNAPSE",
    "apiCreator":"admin",
    "responseCacheHit":false,
    "backendLatency":1866,
    "correlationId":"00a94b54-5579-4f5d-95c1-4bd909fd4c20",
    "requestMediationLatency":578,
    "keyType":"SANDBOX",
    "apiId":"fd5a22ee-144f-4fc1-9f22-ce5ff0382023",
    "applicationName":"AppUser",
    "targetResponseCode":200,
    "requestTimestamp":"2022-07-18T06:49:19Z",
    "applicationOwner":"admin",
    "userAgent":"Chrome",
    "eventType":"response",
    "apiResourceTemplate":"/test",
    "properties":{
         "tokenIssuer":"https://localhost:9443/oauth2/token",
         "apiContext":"/api1/2.0.0",
         "userName":"[email protected]"
    },
    "responseLatency":2446,
    "regionId":"default",
    "responseMediationLatency":2,
    "userIp":"127.0.0.1",
    "applicationId":"5d6d0135-810a-4b4e-8f9a-45187e943fff",
    "apiType":"HTTP"
 }

Top