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.

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 the wso2-nexus repository to the pom.xml file.

    <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 package.

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. <APIM_HOME> refers to the root folder of the extracted WSO2 APIM.

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

Place the created .jar file inside the <APIM_HOME>/repository/components/lib directory.
Configure the deployment.toml file.

Edit the apim.analytics configurations in the deployment.toml file located inside <APIM_HOME>/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.

Enabling Logs

To enable trace logs for the component: org.wso2.am.analytics.publisher, edit log4j2.properties file located inside <APIM_HOME>/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 <APIM_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":"admin@carbon.super"
    },
    "responseLatency":2446,
    "regionId":"default",
    "responseMediationLatency":2,
    "userIp":"127.0.0.1",
    "applicationId":"5d6d0135-810a-4b4e-8f9a-45187e943fff",
    "apiType":"HTTP"
 }