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 31st 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.
2. Add relevant dependencies.<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>
<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
andorg.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.
Follow the same URL pattern when providing the repo url.<repository> <id> local-maven-repo </id> <url> file://home/user/.m2/repository </url> </repository>
- Find the
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 theenforcer/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" } }