

Publish Custom Attributes With Analytics¶

Choreo Connect provides default set of attributes with the analytics data when an API invocation happens. Additional to that, users can add custom analytics data with an analytics event due to this feature. If there are specific request headers, response headers, response trailers relevant to the event, users can retrieve those values and use with Chore Connect analytics. This guide will explain the steps required to do it.

Update Level 14

This feature is available only as an update. After the Update of level 1.0.0.14 (released on 31^st October 2022) and further. For more information regarding Choreo Connect updates, refer to the documentation available in here.

Note

Request headers (headers sent to the upstream), Response headers (headers coming from the upstream) and Response trailers can only use with this feature.

Creating The Custom Analytics Data Provider JAR¶

You need to create a new Java Maven project to obtain this JAR.

There is an existing sample project in here. 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.

Configuring the pom.xml file¶

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>

2. Add relevant 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>

Info

If you need above mentioned JARs, you can find them from here.

When working with above sample project, 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 .jar files here.

Add the above .jar files to the local m2 repository 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 to the local m2 repository in the project pom file.
```
<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 the required class¶

AnalyticsCustomDataProvider Implementation Class¶

Analytics with custom attributes feature can be customized by implementing the AnalyticsCustomDataProvider interface. 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. From Choreo Connect analytics implementation, all the header values (request, response headers, response trailers) relevant to the request will be sent in a HashMap. Therefore, by processing it you can obtain the required headers.

Build the project JAR addition to the Enforcer¶

Build the project using the following command.
```
mvn clean install
```
Obtain the relevant JAR from target folder and mount it to the {CC_HOME}/resources/enforcer/dropins folder.

Creating The Custom Reporter JAR to log analytics data¶

In order to log the custom attributes for the event occurrences, you need to add Custom Reporter JAR to the dropins folder. You can follow the Step 1.1 explained here to obtain the JAR. Similar to the above after obtaining the JAR mount it to the enforcer/dropins folder.

Configure the log4j2.properties file with the following configurations.

Add a new logger to the Enforcer by adding the following configuration

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 = ENFORCER_ACCESS_LOG

Append the newly added logger as shown below.

    loggers = org-wso2-analytics-publisher, other_available_loggers...

Obtaining Custom Attributes with Analytics¶

Enable Choreo Connect analytics.
Initiate an event to publish analytics data.

In the Enforcer logs you will see the relevant attribute related to the API invocation under the properties field.

  choreo-connect-with-apim-enforcer-1  | ... Info -
  {
     "apiName":"TestAPI",
     "proxyResponseCode":401,
     "errorType":"AUTH",
     .
     .
     .
     "errorMessage":"AUTHENTICATION_FAILURE",
     "eventType":"fault",
     "regionId":"UNKNOWN",
     "applicationId":"UNKNOWN",
     "apiType":"HTTP",
     "properties":{
        "user-agent":"curl/7.83.0"
     }
  }

Top